exploreLSDs.alldiffs {asremlPlus}

Explores the computed LSD values for pairwise differences between predictions.

Description

Given an alldiffs.object with an sed component, the LSDs are calculated for all pairwise comparisons of predictions. It then calculates (i) a table of frequencies of the LSD values, (ii) the distinct values of the LSDs after rounding, (iii) various statistics from the LSD values, (iv) a measure of the accuracy of each of the LSD statistics, (v) the numbers of false positives and false negatives for each of the LSD statistics if pairwise comparisons are based on the LSD statistic, (vi) the accuracy of each statistic in representing the LSD values for each prediction and (vii) a matrix containing the LSD values for comparing each pair of predictions. Histograms of the frequencies can also be produced.

Usage

## S3 method for class 'alldiffs'
exploreLSDs(alldiffs.obj, LSDtype = "overall", LSDby = NULL, 
            LSDaccuracy = "maxAbsDeviation", alpha = 0.05, digits = 3, 
            retain.zeroLSDs = FALSE, 
            zero.tolerance = .Machine$double.eps ^ 0.5, 
            plotHistogram = FALSE, ...)

Arguments

alldiffs.obj

An alldiffs.object.

LSDtype

A character string that can be overall or factor.combinations. It determines whether the LSD values that are investigated and stored are (i) the overall minimum, quantile10, quantile25, mean, median, quantile75, quantile90, and maximum of all pairwise LSDs, or (ii) the minimum, quantile10, quantile25, mean, median, quantile75, quantile90, and maximum for the pairwise LSDs for each factor.combination, unless there is only one prediction for a factor.combination, when notional LSDs are calculated. The LSDtype specified here does not have to match that used in the creating the alldiffs.object.

See LSD.frame for further information on how the LSD statistics are calculated.

LSDby

A character (vector) of variables names, being the names of the factors or numerics in the classify; for each combination of the values the of the factors and numerics, the LSD statistics and accuracy are computed, as well histograms plotted, when LSDtype is factor.combinatons. The LSDby specified here does not have to match that used in the creating the alldiffs.object.

LSDaccuracy

A character nominating one of maxAbsDeviation, maxDeviation, q90Deviation or RootMeanSqDeviation as the statistic to be calculated as a measure of the accuracy of an LSD statistic when its values are used as an approximate LSD. The option q90Deviation produces the sample quantile corresponding to a probability of 0.90. The deviations are the differences between a set of LSDs and an LSD statistic calculated from those LSDs; the accuracy is expressed as a proportion of the value of the LSD statistic.

alpha

A numeric specifying the significance level for an LSD to compare a pair of predictions.

digits

A numeric specifying the number of significant digits to retain in rounding the LSDs before determining the distinct rounded LSDs.

retain.zeroLSDs

A logical indicating whether to retain or omit LSDs that are zero when calculating the summaries of LSDs.

zero.tolerance

A numeric specifying the value such that if an LSD is less than it, the LSD will be considered to be zero.

plotHistogram

A logical indicating whether or not histograms of the LSD values are to be plotted. The LSDtype argument controls whether one histogram of all LSD values is plotted or histograms are plotted for each combination of the levels of the factors specified by the LSDby argument.

...

Provision for passing arguments to functions called internally - not used at present.

Details

The false positives and negatives are computed by comparing, for each pair of predictions within each levels-combination of the LSDby variables, the significance of the pair difference determined using (i) the true LSD that is computed from the standard error of differences for the pair and (ii) the approximate LSD that is a statistic computed from the true LSDs for all pairwise difference within each levels-combination of the LSDby variables. The number of false positives is the number of pairwise differences for which a difference is declared significant using the approximate LSD, but not using the true LSD. The number of false negatives is the number of pairwise differences for which a difference is declared nonsignificant using the approximate LSD, but significant using the true LSD.

The LSD accuracy for a set of LSDs is a function of the deviations of those LSDs and an LSD statistic calculated from them; the accuracy is expressed as a proportion of the value of the LSD statistic.

Value

A list with components frequencies, distinct.vals, statistics, accuracy, per.pred.accuracy and LSD:

1. frequencies is a data.frame with the frequency distribution of the LSD values;

2. distinct.vals is a list, each component of which contains the distinct values of the LSDs after rounding;

3. statistics is a data.frame with the minimum, quantile10, quantile25, mean, median, quantile75, quantile90, and maximum of the LSD values;

4. accuracy is a data.frame with the accuracies of the minimum, quantile10, quantile25, mean, median, quantile75, quantile90, and maximum of the LSD values with respect to the values from which these statistics are calculated;

5. false.pos is a data.frame with the numbers of false positives for the pairwise comparisons within each levels-combination of the LSDby variables when each of the minimum, quantile10, quantile25, mean, median, quantile75, quantile90, and maximum of the LSD values is used as an approximate LSD in determining the significance of the pairwise differences;

6. false.neg is a data.frame with the numbers of false negatives for the pairwise comparisons within each levels-combination of the LSDby variables when each of the minimum, quantile10, quantile25, mean, median, quantile75, quantile90, and maximum of the LSD values is used as an approximate LSD in determining the significance of the pairwise differences;

7. per.pred.accuracy is a data.frame with the accuracies of the minimum, quantile10, quantile25, mean, median, quantile75, quantile90, and maximum of the LSD values for a set of predictions when these statistics are used to represent the LSDs for the comparisons amongst the set of predictions;

8. LSD is a square matrix containing the LSD values for all pairwise comparisons of the predictions contained in the supplied alldiffs.obj.

In the statistics, accuracy, false.pos and false.neg data.frames, c is the number of pairwise comparisons on which the values in the same row are based. The accuracy measure is specified by the LSDaccuracy argument.

Author(s)

Chris Brien

See Also

asremlPlus-package, plotLSDs.data.frame, plotLSDs.alldiffs,
plotLSDerrors.alldiffs, plotLSDerrors.data.frame, recalcLSD.alldiffs,
pickLSDstatistics.alldiffs, redoErrorIntervals.alldiffs

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)
TS.diffs <- predictPlus(classify = "Sources:Type", 
                        asreml.obj = current.asr, 
                        wald.tab = current.asrt$wald.tab, 
                        present = c("Sources", "Type", "Species"))

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

## Plot p-values for predictions obtained using asreml or lmerTest
if (exists("TS.diffs"))
{
  ##Explore the LSD values for predictions obtained using asreml or lmerTest  
  LSDstat <- exploreLSDs(TS.diffs, LSDtype = "factor.combinations", 
                         LSDby = "Sources")
}