# Calculates the differences between nominated pairs of predictions stored in an `alldiffs.object`. 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.object`s. 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`. ```r ## S3 method for class '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, ...) ``` ## 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: 1. If `avsed.tolerance` is `NA` then mean LSDs of the type specified by `LSDtype` are calculated and used in `error.intervals` and plots. 2. Irrespective of the setting of `LSDtype`, if `avsed.tolerance` is not exceeded then the mean LSDs are used in `error.intervals` and plots. 3. 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. 4. 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. 5. 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`. ## Returns A `list` of `alldiffs.object`s 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. ## Author(s) Chris Brien ## See Also `linTransform`, `ratioTransform`, `predictPlus.asreml`, `as.alldiffs`, `print.alldiffs`, `sort.alldiffs`, `subset.alldiffs`, `allDifferences.data.frame`, `redoErrorIntervals.alldiffs`, `recalcLSD.alldiffs`, `pickLSDstatistics.alldiffs`, `predictPresent.asreml`, `plotPredictions.data.frame`, `as.Date`, `predict.asreml` ## Examples ```r #### 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") ## Not run: 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) ## End(Not run) ## 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") ```

pairdiffsTransform.alldiffs function