plotLSDerrors.alldiffs: Plots a map of the errors that occur in using the computed LSD values for pairwise differences between predictions.

Description

Produces a plot of the errors that occur in using the computed LSD values for pairwise differences predictions by comparing the result obtained from using the LSDs stored in the assignedLSD column of the LSD component of the alldiffs.object with those computed from the sed component using the t-value for the df stored in the tdf attribute of the alldiffs.object. The sed component is generally a matrix whose rows and columns are labelled by the levels of one or more factors, the set of labels being the same for rows and columns. The sections argument allows multiple plots to be produced, one for each combination of the levels of the factors listed in sections. Otherwise, a single plot is produced for all observed combinations of the levels of the factors in the classify attribute for the alldiffs.object. The plots are produced using plotLSDerrors.data.frame. The order of plotting the levels of one of the factors indexing the predictions can be modified using sort.alldiffs.

Usage

plotLSDerrors(object, ...)
# S3 method for alldiffs
plotLSDerrors(object, alpha = 0.05, useIntervals = FALSE, 
              sections = NULL, gridspacing = 0, factors.per.grid = 0, 
              triangles = "both", title = NULL, 
              axis.labels = TRUE, axis.text.size = 12, 
              sep=",", colours = c("white","blue","red","grey"), 
              ggplotFuncs = NULL, printPlot = TRUE, 
              sortFactor = NULL, sortParallelToCombo = NULL, 
              sortNestingFactor = NULL, sortOrder = NULL, 
              decreasing = FALSE, ...)

Value

A list with components named LSDresults and plots. The LSDresults component contains the data.frame with the columns Rows,

Columns, LSDresults, sections1 and sections2. This data.frame

is formed using the LSD and sed components of object and is used by plotLSDerrors.data.frame in producng the plots. The plots

component contains a list of ggplot objects, one for each plot produced. Multiple plots are stored in the plots component if the sections argument is set and the plots are are named for the levels combinations of the sections.

Arguments

object

An alldiffs.object with both LSD and sed components that are not NULL.

alpha

A numeric giving the significance level for the LSD.

useIntervals

A logical indicating whether to use the interval limits stored in the predictions component of object, instead of the LSDs stored in the LSD component, for determining whether pairs of predictions are significantly different. It allows a check of how the error.intervals in the predictions component will perform if they are used for all pairwise predictions comparisons, whereas the comparisons to which the LSDs apply may be restricted by the setting of the LSDby attribute of object. There is no restriction on the error.intervals that can be used. However, the limits for them must be in columns in the predictions component of object and their names must end with .limits and begin with lower. and upper.

sections

A character listing the names of the factors that are to be used to break the plot into sections. A separate plot will be produced for each observed combination of the levels of these factors.

gridspacing

A numeric specifying the number(s) of rows and columns that form groups in the grid of differences. An alternative is to specify the factors.per.grid argument to have the grid spacings automatically calculated. Grids are most useful when two or more factors index the rows and columns. If a single, nonzero number, k say, is given then a grid line is placed after every kth row and column. If a vector of values is given then the number of grid lines is the length of the vector and the spacing between each is specified by the elements of the vector.

factors.per.grid

A numeric specifying the number of factors to include within each grid of differences. The gridspacing will then be computed based on the numbers of combinations observed within the levels of the remaining factors in a single plot. The gridspacing argument to this function will be ignored if factors.per.grid is greater than zero. Grids are most useful when two or more factors index the rows and columns of each plot.

triangles

A character indicating whether the plot should include the lower, upper or both triangle(s).

title

A character string giving the main title for the plot and to which is appended the levels combination of the sectioning factors, if any, for each plot.

axis.labels

A logical indicating whether a label is to be added to the x- and y-axes. If TRUE, the label is the comma-separated list of factors whose levels combinations are involved in the prediction differences for which the LSD values are calculated.

axis.text.size

A numeric giving the size of the labels on the axes of the heatmap.

sep

A character giving the characters separating the levels of different factors in the row and column names of the sed component.

colours

A vector of colours to be passed to the ggplot function scale\_colour\_gradientn.

ggplotFuncs

A list, each element of which contains the results of evaluating a ggplot2 function. It is created by calling the list function with a ggplot2 function call for each element. It is passed to ggplot via plotLSDerrors.data.frame to be applied in creating the ggplot object.

printPlot

A logical indicating whether or not the a plot is to be printed. This would be used when just the returned data.frame is required.

sortFactor

A character containing the name of the factor that indexes the set of predicted values that determines the sorting of the components. If there is only one variable in the classify term then sortFactor can be NULL and the order is defined by the complete set of predicted values. If there is more than one variable in the classify term then sortFactor must be set. In this case the sortFactor is sorted in the same order within each combination of the values of the sortParallelToCombo variables: the classify variables, excluding the sortFactor. There should be only one predicted value for each unique value of sortFactor within each set defined by a combination of the values of the classify variables, excluding the sortFactor factor. The order to use is determined by either sortParallelToCombo or sortOrder.

sortParallelToCombo

A list that specifies a combination of the values of the factors and numerics, excluding sortFactor, that are in classify. Each of the components of the supplied list is named for a classify variable and specifies a single value for it. The combination of this set of values will be used to define a subset of the predicted values whose order will define the order of sortFactor. Each of the other combinations of the values of the factors and numerics will be sorted in parallel. If sortParallelToCombo is NULL then the first value of each classify variable, except for the sortFactor factor, in the predictions component is used to define sortParallelToCombo. If there is only one variable in the classify then sortParallelToCombo is ignored.

sortNestingFactor

A character containing the name of the factor that defines groups of the sortFactor within which the predicted values are to be ordered. If there is only one variable in the classify then sortNestingFactor is ignored.

sortOrder

A character vector whose length is the same as the number of levels for sortFactor in the predictions component of the alldiffs.object. It specifies the desired order of the levels in the reordered components of the alldiffs.object. The argument sortParallelToCombo is ignored.

The following creates a sortOrder vector levs for factor f based on the values in x: levs <- levels(f)[order(x)].

decreasing

A logical passed to order that detemines whether the order for sorting the alldiffs.object components is for increasing or decreasing magnitude of the predicted values.

...

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

Author

Chris Brien

Examples

Run this code

##Subset WaterRunoff data to reduce time to execute
data(WaterRunoff.dat)
tmp <- subset(WaterRunoff.dat, Date == "05-18" & Benches != "3")

##Use asreml to get predictions and associated statistics

if (FALSE) {
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= tmp)
current.asrt <- as.asrtests(current.asr, NULL, NULL)
TS.diffs <- predictPlus.asreml(classify = "Sources:Type", 
                               asreml.obj = current.asr, tables = "none", 
                               wald.tab = current.asrt$wald.tab, 
                               present = c("Type","Species","Sources"))
}

## 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 LSD values for predictions obtained using asreml or lmerTest
if (exists("TS.diffs"))
{
  plotLSDerrors(TS.diffs, gridspacing = rep(c(3,4), c(4,2)))
# \donttest{
  plotLSDerrors(TS.diffs, sections = "Sources", axis.labels = TRUE)
# }  
}