linTransform.alldiffs: 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 their lower and upper confidence 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 alldiffs
linTransform(alldiffs.obj, classify = NULL, term = NULL, 
             linear.transformation = NULL, Vmatrix = FALSE, 
             error.intervals = "Confidence", avsed.tolerance = 0.25, 
             meanLSD.type = "overall", LSDby = NULL, 
             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 to be predicted. 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.

linear.transformation

A formula or a matrix. If a formula is given then it is taken to be a submodel of the model term corresponding to the classify. The projection matrix that transforms the predictions so that they conform to the submodel is obtained; the submodel should involving the variables in 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.

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.

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 meanLSD.type 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. 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 meanLSD.type are calculated and used in error.intervals and plots.
Irrespective of the setting of meanLSD.type, if avsed.tolerance is not exceeded then the mean LSDs are used in error.intervals and plots.
If meanLSD.type is set to overall, avsed.tolerance is not NA, and avsed.tolerance is exceeded then error.intervals and plotting revert to confidence intervals.
If meanLSD.type 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 meanLSD.type 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.

meanLSD.type

A character string determining whether the mean LSD stored is (i) the overall mean, based on the square root of the mean of the variances of all pairwise variances, (ii) the mean for each factor.combination of the factors specified by LSDby, which is based on the square root of the mean of the variances for all pairwise differences for each factor combination, or (iii) the per.prediction mean, based, for each prediction, on the square root of the mean of the variances for all pairwise differences involving that prediction, unless there is only one prediction for a factor.combination, when notional LSDs are calculated that are based on the standard error of the prediction multiplied by the square root of two. It also determines, in conjunction with avsed.tolerance, which LSD will be used in calculating error.intervals and, hence, is used for plots.

LSDby

A character (vector) of variables names, being the names of the factors or numerics in the classify for each combination of which a mean LSD, minLSD and max LSD is stored in the LSD component of the alldiffs.object when meanLSD.type is factor.combinatons.

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) corresponds to x.fac, (ii) is potentially included in terms in the fitted model, and (iii) which corresponds to the x-axis variable. It should have the same number of unique values as the number of levels in x.fac.

x.fac

A character string giving the name of the factor that (i) corresponds to x.num, (ii) is potentially included in terms in the fitted model, and (iii) which corresponds to the x-axis variable. 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 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.

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.

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 componnent, 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, sortFactor and the sortOrder will be set as attributes to the object.

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.

The matrix \(\mathbf{L}\) is directly specified by setting linear.transformation to it. If linear.transformation is a formula then \(\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".

Examples

Run this code

# NOT RUN {
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"))
# }
# 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")
}
# }

Run the code above in your browser using DataLab