pairdiffsTransform.alldiffs: Calculates the differences between nominated pairs of predictions stored in an `alldiffs.object`.

Description

Predictions of differences and their error intervals are formed for two levels of a factor, the pairs.factor. For each pair of a level of the pairs.factor in numerator.levels with a level in denominator.levels, an alldiffs.object is formed that contains the differences between predictions with this pair of levels for all of the combinations of the levels of the other factors in the classify of the alldiffs.object. These prediction differences are obtained using linTransform by forming a suitable contrast matrix to specify the linear.transformation. This function has the advantage that the factors indexing the differences are included in the components of the alldiffs.objects.

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.

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
pairdiffsTransform(alldiffs.obj, pairs.factor, first.levels, second.levels, 
                   Vmatrix = FALSE, error.intervals = "Confidence", 
                   avsed.tolerance = 0.25, accuracy.threshold = NA, 
                   LSDtype = "overall", LSDsupplied = NULL, LSDby = NULL, 
                   LSDstatistic = "mean", LSDaccuracy = "maxAbsDeviation", 
                   response = NULL, response.title = NULL, tables = "all", 
                   pairwise = TRUE, alpha = 0.05, ...)

Value

A list of alldiffs.objects with a component for each combination of a first.levels with a second.levels. The name of a component will be a level from first.levels combined with a level from second.levels, separated by a comma. If the predictions in the supplied alldiffs.object

are based on a response that was transformed, each alldiffs.object

in the list will include a backtransforms component that contains a column labelled backtransformed.predictions, along with the backtransforms of the nominated error.intervals. The predictions and backtransforms

components in an alldiffs.object will be indexed by the variables in the

classify of alldiffs.obj, except that the pairs.factor is omitted. If the transformation was the logarithmic transformation, these

backtransformed.predictions are predicted ratios of the untransformed response.

If sortFactor attribute is set and is not the

ratio.factor, the predictions and, if present, their backtransforms will be sorted using the sortOrder attribute of the alldiffs.object, and both sortFactor and sortOrder will be set as attributes to the object.

Arguments

alldiffs.obj

An alldiffs.object.

pairs.factor

A character string giving the name of the factor for whose levels the differences are to be calculated.

first.levels

A character string containing the levels of the pairs.factor whose predictions are those subtracted from.

second.levels

A character string containing the levels of the pairs.factor whose predictions are those that are subtracted.

Vmatrix

A logical indicating whether the variance matrix of the predictions will be stored as a component of the alldiffs.object that is returned.

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.

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.

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.

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.

...

further arguments passed to linTransform.alldiffs.

Author

Chris Brien

Examples

Run this code

#### Form the differences for log(RGR) for Salinity
load(system.file("extdata", "testDiffs.rda", package = "asremlPlus", mustWork = TRUE))
#### For the ratios for Cl per WU Temperature - use backtransforms of log-predictions
Preds.ratio.ClUp <- pairdiffsTransform(diffs.ClUp, 
                                       pairs.factor = "Temperature", 
                                       first.levels = "Hot",
                                       second.levels = "Cool",
                                       error.intervals = "halfLeast",
                                       tables = "backtransforms") #Backtransforms are ratios

#### Form the differences for Nitrogen compared to no Nitrogen                                  
data("Oats.dat")
if (FALSE) {
m1.asr <- asreml(Yield ~ Nitrogen*Variety, 
                 random=~Blocks/Wplots,
                 data=Oats.dat)
current.asrt <- as.asrtests(m1.asr)
wald.tab <-  current.asrt$wald.tab
Var.diffs <- predictPlus(m1.asr, classify="Nitrogen:Variety", pairwise = TRUE,
                         Vmatrix = TRUE, error.intervals = "halfLeast",
                         LSDtype = "factor", LSDby = "Variety",
                         wald.tab = wald.tab)
}

 ## Use lme4 and emmmeans to get predictions and associated statistics
if (requireNamespace("lmerTest", quietly = TRUE) & 
    requireNamespace("emmeans", quietly = TRUE))
{
  m1.lmer <- lmerTest::lmer(Yield ~ Nitrogen*Variety + (1|Blocks/Wplots),
                              data=Oats.dat)
  ## Set up a wald.tab
  int <- as.data.frame(rbind(rep(NA,4)))
  rownames(int) <- "(Intercept)"
  wald.tab <- anova(m1.lmer, ddf = "Kenward", type = 1)[,3:6]
  names(wald.tab) <- names(int) <- c("Df", "denDF", "F.inc", "Pr")
  wald.tab <- rbind(int, wald.tab)
  #Get predictions
  Var.emm <- emmeans::emmeans(m1.lmer, specs = ~ Nitrogen:Variety)
  Var.preds <- summary(Var.emm)
  ## Modify Var.preds to be compatible with a predictions.frame
  Var.preds <- as.predictions.frame(Var.preds, predictions = "emmean", 
                                    se = "SE", interval.type = "CI", 
                                    interval.names = c("lower.CL", "upper.CL"))
  Var.vcov <- vcov(Var.emm)
  Var.sed <- NULL
  den.df <- wald.tab[match("Variety", rownames(wald.tab)), "denDF"]
  
  #Create alldiffs object
  Var.diffs <- as.alldiffs(predictions = Var.preds, 
                           sed = Var.sed, vcov = Var.vcov, 
                           classify = "Nitrogen:Variety", response = "Yield", tdf = den.df)
} 

if (exists("Var.diffs"))
  Preds.diffs.OatsN <- pairdiffsTransform(alldiffs.obj = Var.diffs,
                                          pairs.factor = "Nitrogen", 
                                          first.levels = c("0.2","0.4","0.6"),
                                          second.levels = "0", error.intervals = "halfLeast",
                                          tables = "none")