plotPvalues.alldiffs {asremlPlus}R Documentation

Plots a heat map of p-values for pairwise differences between predictions.

Description

Produces a heat-map plot of the p-values for pairwise differences between predictions that is stored in the p.differences component of an all.diffs object. This 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 for the alldiffs.object. The plots are produced using plotPvalues.data.frame. The order of plotting the levels of one of the factors indexing the predictions can be modified using sort.alldiffs.

Usage

plotPvalues(object, ...)
## S3 method for class 'alldiffs'
plotPvalues(object, sections = NULL, 
            gridspacing = 0, factors.per.grid = 0, 
            show.sig = FALSE, alpha = 0.10, 
            sig.size = 3, sig.colour = "black", 
            sig.face = "plain", sig.family = "",  
            triangles = "both", 
            title = NULL, axis.labels = TRUE, axis.text.size = 12, 
            sep=",", colours = RColorBrewer::brewer.pal(3, "Set2"), 
            ggplotFuncs = NULL, printPlot = TRUE, 
            sortFactor = NULL, sortParallelToCombo = NULL, 
            sortNestingFactor = NULL, sortOrder = NULL, 
            decreasing = FALSE, ...)

Arguments

object

An alldiffs.object with a p.differences component that is not NULL.

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.

show.sig

A logical that specifies whether asterisks indicating the level of significance are to be added to the plot. If they are then ‘***’ indicates that p \leq 0.001, ‘**’ that 0.001 < p \leq 0.01, ‘*’ that 0.01 < p \leq 0.05 ‘.’ that 0.05 < p \leq 0.10. The last is only included for alpha = 0.10.

alpha

A numeric giving the significance level for testing pairwise differences; must be 0.05 or 0.10.

sig.size

A numeric specifying the size, in pts, of the significance asterisks.

sig.colour

A character specifying the colour to use for the significance asterisks.

sig.face

A character specifying the font face for the significance asterisks ("plain", "italic", "bold", "bold.italic").

sig.family

A character specifying the font family for the significance asterisks. The font families that are available depends on the system. For font families other than the basic Postscript fonts, see the extrafont package.

triangles

A character indicating whether the plot should include the lower, upper or both traingle(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 p-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 p.differences component.

colours

A vector of 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 ggplot function. It is created by calling the list function with a ggplot function call for each element. It is passed to ggplot via plotPvalues.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.

Value

A list with components named pvalues and plots. The pvalues component contains the data.frame with the columns Rows, Columns, p, sections1 and sections2. This data.frame is formed using the sed component of object and is used by plotPvalues.data.frame in producng the plot. 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.

Author(s)

Chris Brien

See Also

plotPvalues.data.frame, allDifferences.data.frame, sort.alldiffs, subset.alldiffs, ggplot

Examples

##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

## 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= 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"))

## 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"))
{
  plotPvalues(TS.diffs, gridspacing = rep(c(3,4), c(4,2)), show.sig = TRUE)

  plotPvalues(TS.diffs, sections = "Sources", show.sig = TRUE, axis.labels = TRUE)
  
}

[Package asremlPlus version 4.4.27 Index]