R: Calculates a linear transformation of the predictions stored...

linTransform.alldiffs {asremlPlus}

R Documentation

Calculates a linear transformation of the predictions stored in an `alldiffs.object`.

Description

Effects the linear transformation of the predictions in the supplied alldiffs.object, the transformation being specified by a matrix or a formula. The values of the transformed values are stored in an alldiffs.object. A matrix might be a contrast matrix or a matrix of weights for the levels of a factor used to obtain the weighted average over the levels of that factor. A formula gives rise to a projection matrix that linearly transforms the predictions so that they conform to the model specified by the formula, this model being a submodel of that inherent in the classify.

If pairwise = TRUE, all pairwise differences between the linear transforms of the predictions, their standard errors, p-values and LSD statistics are computed as using allDifferences.data.frame. This adds them to the alldiffs.object as additional list components named differences, sed, p.differences and LSD.

If a transformation has been applied (any one of transform.power is not one, scale is not one and offset is nonzero), the backtransforms of the transformed values and of the lower and upper limits of their error.intervals are added to a data.frame that is consistent with a predictions.frame. If transform.power is other than one, the standard.error column of the data.frame is set to NA. This data.frame is added to the alldiffs.object as a list component called backtransforms.

The printing of the components produced is controlled by the tables argument. The order of plotting the levels of one of the factors indexing the predictions can be modified and is achieved using sort.alldiffs.

Usage

## S3 method for class 'alldiffs'
linTransform(alldiffs.obj, classify = NULL, term = NULL, 
             linear.transformation = NULL, EGLS.linTransform = TRUE, 
             Vmatrix = FALSE, error.intervals = "Confidence", 
             avsed.tolerance = 0.25, accuracy.threshold = NA, 
             LSDtype = "overall", LSDsupplied = NULL, 
             LSDby = NULL, LSDstatistic = "mean", 
             LSDaccuracy = "maxAbsDeviation", 
             zero.tolerance = .Machine$double.eps ^ 0.5, 
             response = NULL, response.title = NULL, 
             x.num = NULL, x.fac = NULL, 
             tables = "all", level.length = NA, 
             pairwise = TRUE, alpha = 0.05,
             inestimable.rm = TRUE, ...)

Arguments

`alldiffs.obj`	An `alldiffs.object`.
`classify`	A `character` string giving the variables that define the margins of the multiway table corresponding to the `predictions` in `alldiffs.obj`. Multiway tables are specified by forming an interaction type term from the classifying variables, that is, separating the variable names with the `:` operator.
`term`	A `character` string giving the variables that define the term that was fitted using `asreml` and that corresponds to `classify`. It only needs to be specified when it is different to `classify`; it is stored as an attribute of the `alldiffs.object`. It is likely to be needed when the fitted model includes terms that involve both a `numeric` covariate and a `factor` that parallel each other; the `classify` would include the covariate and the `term` would include the `factor`.
`linear.transformation`	A `formula` or a `matrix`. If a `formula` is given then it is taken to be a submodel of a model term corresponding to the `classify`. The projection matrix that transforms the `predictions` so that they conform to the submodel is obtained; the submodel does not have to involve variables in the `classify`, but the variables must be columns in the `predictions` component of `alldiffs.obj` and the space for the submodel must be a subspace of the space for the term specified by the `classify`. For example, for `classify` set to `"A:B"`, the submodel `~ A + B` will result in the `predictions` for the combinations of `A` and `B` being made additive for the `factors` `A` and `B`. The submodel space corresponding to `A + B` is a subspace of the space `A:B`. In this case both the submodel and the classify involve only the factors A and B. To fit an intercept-only submodel, specify `linear.transformation` to be the formula `~1`. If a `matrix` is provided then it will be used to apply the linear transformation to the `predictions`. The number of rows in the `matrix` should equal the number of linear combinations of the `predictions` desired and the number of columns should equal the number of `predictions`. In either case, as well as the values of the linear combinations, their standard errors, pairwise differences and associated statistics are returned.
`EGLS.linTransform`	A `logical` indicating whether or not the `linear.transformation` of the predictions stored in an `alldiffs.object` by fitting a submodel supplied in a `formula` is to take into account the variance of the predictions using a Estimated Generalized Least Squares (EGLS) approach. This is likely to be appropriate when the variance matrix of the predictions is not compound symmetric i.e. when not all the variances are equal or not all the covariances are equal. If the variance matrix is compund symmetric, then the setting of `EGLS.linTransform` will not affect the transformed predictions.
`Vmatrix`	A `logical` indicating whether the variance matrix of the `predictions` will be stored as a component of the `alldiffs.object` that is returned. If `linear.transformation` is set, it will be stored irrespective of the value of `Vmatrix`.
`error.intervals`	A `character` string indicating the type of error interval, if any, to calculate in order to indicate uncertainty in the results. Possible values are `"none"`, `"StandardError"`, `"Confidence"` and `"halfLeastSignificant"`. The default is for confidence limits to be used. The `"halfLeastSignificant"` option results in half the Least Significant Difference (LSD) being added and subtracted to the predictions, the LSD being calculated using the square root of the mean of the variances of all or a subset of pairwise differences between the predictions. If the LSD is zero, as can happen when predictions are constrained to be equal, then the limits of the error intervals are set to `NA`. If `LSDtype` is set to `overall`, the `avsed.tolerance` is not `NA` and the range of the SEDs divided by the average of the SEDs exceeds `avsed.tolerance` then the `error.intervals` calculations and the plotting will revert to confidence intervals.
`avsed.tolerance`	A `numeric` giving the value of the SED range, the range of the SEDs divided by the square root of the mean of the variances of all or a subset of the pairwise differences, that is considered reasonable in calculating `error.intervals`. To have it ignored, set it to `NA`. It should be a value between 0 and 1. The following rules apply: If `avsed.tolerance` is `NA` then mean LSDs of the type specified by `LSDtype` are calculated and used in `error.intervals` and plots. Irrespective of the setting of `LSDtype`, if `avsed.tolerance` is not exceeded then the mean LSDs are used in `error.intervals` and plots. If `LSDtype` is set to `overall`, `avsed.tolerance` is not `NA`, and `avsed.tolerance` is exceeded then `error.intervals` and plotting revert to confidence intervals. If `LSDtype` is set to `factor.combinations` and `avsed.tolerance` is not exceeded for any factor combination then the half LSDs are used in `error.intervals` and plots; otherwise, `error.intervals` and plotting revert to confidence intervals. If `LSDtype` is set to `per.prediction` and `avsed.tolerance` is not exceeded for any prediction then the half LSDs are used in `error.intervals` and plots; otherwise, `error.intervals` and plotting revert to confidence intervals.
`accuracy.threshold`	A `numeric` specifying the value of the LSD accuracy measure, which measure is specified by `LSDaccuracy`, as a threshold value in determining whether the `hallfLeastSignificant` `error.interval` for a predicted value is a reasonable approximation; this will be the case if the LSDs across all pairwise comparisons for which the interval's LSD was computed, as specified by `LSDtype` and `LSDby`, are similar enough to the interval's LSD, as measured by `LSDaccuracy`. If it is `NA`, it will be ignored. If it is not `NA`, a column of `logicals` named `LSDwarning` will be added to the `predictions` component of the `alldiffs.object`. The value of `LSDwarning` for a `predicted.value` will be `TRUE` if the value of the `LSDaccuracy` measure computed from the LSDs for differences between this `predicted.value` and the other `predicted.values` as compared to its `assignedLSD` exceeds the value of `accuracy.threshold`. Otherwise, the value of `LSDwarning` for a `predicted.value` will be `FALSE`.
`LSDtype`	A `character` string that can be `overall`, `factor.combinations`, `per.prediction` or `supplied`. It determines whether the values stored in a row of a `LSD.frame` are the values calculated (i) `overall` from the LSD values for all pairwise comparison2, (ii) the values calculated from the pairwise LSDs for the levels of each `factor.combination`, unless there is only one prediction for a level of the `factor.combination`, when a notional LSD is calculated, (iii) `per.prediction`, being based, for each prediction, on all pairwise differences involving that prediction, or (iv) as `supplied` values of the LSD, specified with the `LSDsupplied` argument; these supplied values are to be placed in the `assignedLSD` column of the `LSD.frame` stored in an `alldiffs.object` so that they can be used in LSD calculations. See `LSD.frame` for further information on the values in a row of this `data.frame` and how they are calculated.
`LSDsupplied`	A `data.frame` or a named `numeric` containing a set of `LSD` values that correspond to the observed combinations of the values of the `LSDby` variables in the `predictions.frame` or a single LSD value that is an overall LSD. If a `data.frame`, it may have (i) a column for the `LSDby` variable and a column of `LSD` values or (ii) a single column of `LSD` values with rownames being the combinations of the observed values of the `LSDby` variables. Any name can be used for the column of `LSD` values; `assignedLSD` is sensible, but not obligatory. Otherwise, a `numeric` containing the `LSD` values, each of which is named for the observed combination of the values of the `LSDby` variables to which it corresponds. (Applying the `function` `dae::fac.combine` to the `predictions` component is one way of forming the required combinations for the (row) names.) The values supplied will be incorporated into `assignedLSD` column of the `LSD.frame` stored as the `LSD` component of the `alldiffs.object`.
`LSDby`	A `character` (vector) of variables names, being the names of the `factors` or `numerics` in the `classify`; for each combination of their levels and values, there will be or is a row in the `LSD.frame` stored in the `LSD` component of the `alldiffs.object` when `LSDtype` is `factor.combinatons`.
`LSDstatistic`	A `character` nominating one or more of `minimum`, `q10`, `q25`, `mean`, `median`, `q75`, `q90` or `maximum` as the value(s) to be stored in the `assignedLSD` column in an `LSD.frame`; the values in the `assignedLSD` column are used in computing `halfLeastSignificant` `error.intervals`. Here `q10`, `q25`, `q75` and `q90` indicate the sample quantiles corresponding to probabilities of 0.1, 0.25, 0.75 and 0.9 for the group of LSDs from which a single LSD value is calculated. The function `quantile` is used to obtain them. The `mean` LSD is calculated as the square root of the mean of the squares of the LSDs for the group. The `median` is calculated using the `median` function. Multiple values are only produced for `LSDtype` set to `factor.combination`, in which case `LSDby` must not be `NULL` and the number of values must equal the number of observed combinations of the values of the variables specified by `LSDby`. If `LSDstatistic` is `NULL`, it is reset to `mean`.
`LSDaccuracy`	A `character` nominating one of `maxAbsDeviation`, `maxDeviation`, `q90Deviation` or `RootMeanSqDeviation` as the statistic to be calculated as a measure of the accuracy of `assignedLSD`. The option `q90Deviation` produces the sample quantile corresponding to a probability of 0.90. The deviations are the differences between the LSDs used in calculating the LSD statistics and each assigned LSD and the accuracy is expressed as a proportion of the assigned LSD value. The calculated values are stored in the column named `accuracyLSD` in an `LSD.frame`.
`zero.tolerance`	A `numeric` specifying the value such that if a `predicted.value`, its variance-covariance, or an `LSD` is less than it, the LSD will be considered to be zero.
`response`	A `character` specifying the response variable for the predictions. It is stored as an attribute to the `alldiffs.object` .
`response.title`	A `character` specifying the title for the response variable for the predictions. It is stored as an attribute to the `alldiffs.object`.
`x.num`	A `character` string giving the name of the numeric covariate that (i) is potentially included in terms in the fitted model and (ii) is the x-axis variable for plots. Its values will not be converted to a `factor`.
`x.fac`	A `character` string giving the name of the factor that (i) corresponds to `x.num` and (ii) is potentially included in terms in the fitted model. It should have the same number of levels as the number of unique values in `x.num`. The levels of `x.fac` must be in the order in which they are to be plotted - if they are dates, then they should be in the form yyyymmdd, which can be achieved using `as.Date`. However, the levels can be non-numeric in nature, provided that `x.num` is also set.
`tables`	A `character` vector containing a combination of `none`, `predictions`, `vcov`, `backtransforms`, `differences`, `p.differences`, `sed`, `LSD` and `all`. These nominate which components of the `alldiffs.object` to print.
`level.length`	The maximum number of characters from the levels of factors to use in the row and column labels of the tables of pairwise differences and their p-values and standard errors.
`pairwise`	A `logical` indicating whether all pairwise differences of the `predictions` and their standard errors and p-values are to be computed and stored. If `tables` is equal to `"differences"` or `"all"` or `error.intervals` is equal to `"halfLeastSignificant"`, they will be stored irrespective of the value of `pairwise`.
`alpha`	A `numeric` giving the significance level for LSDs or one minus the confidence level for confidence intervals. It is stored as an attribute to the `alldiffs.object`.
`inestimable.rm`	A `logical` indicating whether rows for predictions that are not estimable are to be removed from the components of the `alldiffs.object`.
`...`	further arguments passed to `redoErrorIntervals.alldiffs`.

Details

For a matrix \mathbf{L}, vector of predictions \mathbf{p} and variance matrix of the predictions \mathbf{V}_p, the linear transformed predictions are given by \mathbf{Lp} with variance matrix \mathbf{LV}_p\mathbf{L}^\mathrm{T}. The last matrix is used to compute the variance of pairwise differences between the transformed values.

If linear.transformation is a matrix, \mathbf{M} say, then the linear-transformation matrix, \mathbf{L}, is just the supplied matrix \mathbf{M}.

If linear.transformation is a formula and EGLS.linTransform is TRUE, then a matrix \mathbf{M} is obtained that is the design matrix for all of the terms in the formula. Using \mathbf{M}, the linear-transformation matrix, \mathbf{L}, is formed as \mathbf{M} (\mathbf{M}^\top \widehat{\mathbf{V}}^- \mathbf{M})^- (\mathbf{M}^\top \widehat{\mathbf{V}}^-).

On the other hand, for linear.transformation a formula and EGLS.linTransform set to FALSE, \mathbf{L} is formed as the sum of the orthogonal projection matrices obtained using pstructure.formula from the package dae; grandMean is set to TRUE and orthogonalize to "eigenmethods".

Value

A alldiffs.object with the linear transformation of the predictions and their standard errors and all pairwise differences between the linear transforms of their predictions, their standard errors and p-values and LSD statistics.

If the supplied alldiffs.object contained a backtransforms component, then the returned alldiffs.object will contain a backtransforms component with the backtransformed linear transformation of the predictions. The backtransformation will, after backtransforming for any power transformation, subtract the offset and then divide by the scale.

If error.intervals is not "none", then the predictions component and, if present, the backtransforms component will contain columns for the lower and upper values of the limits for the interval. The names of these columns will consist of three parts separated by full stops: 1) the first part will be lower or upper; 2) the second part will be one of Confidence, StandardError or halfLeastSignificant; 3) the third component will be limits.

The name of the response, the response.title, the term, the classify, tdf, alpha, sortFactor and the sortOrder will be set as attributes to the object. Also, if error.intervals is "halfLeastSignificant", then those of LSDtype, LSDby and LSDstatistic that are not NULL will be added as attributes of the object and of the predictions frame; additionally, LSDvalues will be added as attribute of the predictions frame, LSDvalues being the LSD values used in calculating the error.intervals.

Author(s)

Chris Brien

Examples

data(WaterRunoff.dat)

##Use asreml to get predictions and associated statistics

## Not run: 
asreml.options(keep.order = TRUE) #required for asreml-R4 only
current.asr <- asreml(fixed = pH ~ Benches + (Sources * (Type + Species)), 
                      random = ~ Benches:MainPlots,
                      keep.order=TRUE, data= WaterRunoff.dat)
current.asrt <- as.asrtests(current.asr, NULL, NULL)
#Get additive predictions directly using predictPlus
diffs.sub <- predictPlus.asreml(classify = "Sources:Species", Vmatrix = TRUE, 
                                linear.transformation = ~ Sources + Species,
                                asreml.obj = current.asr, tables = "none", 
                                wald.tab = current.asrt$wald.tab, 
                                present = c("Type","Species","Sources"))

## End(Not run)

## Use lmeTest and emmmeans to get predictions and associated statistics

if (requireNamespace("lmerTest", quietly = TRUE) & 
    requireNamespace("emmeans", quietly = TRUE))
{
  m1.lmer <- lmerTest::lmer(pH ~ Benches + (Sources * Species) + 
                              (1|Benches:MainPlots),
                            data=na.omit(WaterRunoff.dat))
  SS.emm <- emmeans::emmeans(m1.lmer, specs = ~ Sources:Species)
  SS.preds <- summary(SS.emm)
  den.df <- min(SS.preds$df, na.rm = TRUE)
  ## Modify SS.preds to be compatible with a predictions.frame
  SS.preds <- as.predictions.frame(SS.preds, predictions = "emmean", 
                                   se = "SE", interval.type = "CI", 
                                   interval.names = c("lower.CL", "upper.CL"))
  
  ## Form an all.diffs object and check its validity
  SS.vcov <- vcov(SS.emm)
  SS.diffs <- allDifferences(predictions = SS.preds, classify = "Sources:Species", 
                             vcov = SS.vcov, tdf = den.df)
  validAlldiffs(SS.diffs)

  #Get additive predictions
  diffs.sub <- linTransform(SS.diffs, classify = "Sources:Species", 
                            linear.transformation = ~ Sources + Species,
                            Vmatrix = TRUE, tables = "none")
}  
 
##Calculate contrasts from prediction obtained using asreml or lmerTest 
if (exists("diffs.sub"))
{ 
  #Contrast matrix for differences between each species and non-planted for the last source
  L <- cbind(matrix(rep(0,7*32), nrow = 7, ncol = 32),
             diag(1, nrow = 7), 
             matrix(rep(-1, 7), ncol = 1))
  rownames(L) <- as.character(diffs.sub$predictions$Species[33:39])
  diffs.L <- linTransform(diffs.sub, 
                          classify = "Sources:Species",
                          linear.transformation = L,
                          tables = "predictions")
}

[Package asremlPlus version 4.4.35 Index]

Calculates a linear transformation of the predictions stored in an alldiffs.object.