plotPredictions.data.frame: Plots the predictions for a term, possibly with error bars.

Description

This function plots the predictions y that are based on classify and stored in the data.frame data. The package ggplot2 is used to produce the plots. Line plots are produced when variables involving x.num or x.fac are involved in classify for the predictions; otherwise, bar charts are produced. Further, for line charts, the argument panels determines whether a single plot or multiple plots in a single window are produced; for bar charts, the argument panels is ignored.

Usage

# S3 method for data.frame
plotPredictions(data, classify, y, 
                x.num = NULL, x.fac = NULL, nonx.fac.order = NULL,  
                colour.scheme = "colour", panels = "multiple", 
                graphics.device = NULL,
                error.intervals = "Confidence", interval.annotate = TRUE,
                titles = NULL, y.title = NULL, 
                filestem = NULL, printPlot = TRUE, ggplotFuncs = NULL, ...)

Value

An object of class ggplot, which can be plotted using print or otherwise manipulated.

Arguments

data

A predictions.frame, or data.frame, containing the values of the variables to be plotted. Generally, it should contain the variables classifying the predictions and include a column with the name specified in the y argument, usually predicted.value or backtransformed.predictions; each row contains a single predicted value. It should also include columns for the standard.error and est.status. The number of rows should equal the number of unique combinations of the classifying variables. While such a data.frame can be constructed from the beginning, the pvals component of the value produced by predict.asreml is a suitable value to supply for this argument. Note that the names standard.error and est.status have been changed to std.error and status in the pvals component produced by asreml-R4; if the new names are in the data.frame supplied to predictions, they will be returned to the previous names.

If error.intervals is not "none", then the predictions component and, if present, the backtransforms component should contain columns for the lower and upper values of the limits for the interval with names that begin with lower and upper, respectively. The second part of the name must be one of Confidence, StandardError or halfLeastSignificant. The last part needs to be consistent between the lower and upper limits.

classify

A character string giving the combinations of the independent variables on which the predictions are based. It is an interaction type term formed from the independent variables, that is, separating the variable names with the : operator. To predict the overall mean, set the classify to "(Intercept)".

y

A character string giving the name of the variable that is to be plotted on the Y axis.

x.num

A character string giving the name of the numeric covariate that (i) is potentially included in terms in the fitted model and (ii) is the x-axis variable for plots. Its values will not be converted to a factor.

x.fac

A character string giving the name of the factor that corresponds to x.num, is potentially included in terms in the fitted model and which corresponds to the x-axis variable. It should have the same number of levels as the number of unique values in x.num. The levels of x.fac must be in the order in which they are to be plotted - if they are dates, then they should be in the form yyyymmdd, which can be achieved using as.Date. However, the levels can be non-numeric in nature, provided that x.num is also set.

nonx.fac.order

A character vector giving the order in which factors other than x.fac are to be plotted in faceted plots (i.e. where the number of non x factors is greater than 1). The first factor in the vector will be plotted on the X axis (if there is no x.num or x.fac. Otherwise, the order of plotting the factors is in columns (X facets) and then rows (Y facets). By default the order is in decreasing order for the numbers of levels of the non x factors.

colour.scheme

A character string specifying the colour scheme for the plots. The default is "colour" which produces coloured lines and bars, a grey background and white gridlines. A value of "black" results in black lines, grey bars and gridlines and a white background.

panels

Possible values are "single" and "multiple". When line plots are to be produced, because variables involving x.num or x.fac are involved in classify for the predictions, panels determines whether or not a single panel or multiple panels in a single window are produced. The panels argument is ignored for bar charts.

graphics.device

A character specifying a graphics device for plotting. The default is
graphics.device = NULL, which will result in plots being produced on the current graphics device. Setting it to "windows", for example, will result in a windows graphics device being opened.

error.intervals

A character string indicating the type of error interval, if any, to plot in order to indicate uncertainty in the results. Possible values are "none", "StandardError", "Confidence" and "halfLeastSignificant". Here, any option other than "none" will result in the interval limits contained in data being plotted.

interval.annotate

A logical indicating whether the plot annotation indicating the type of error.interval is to be included in the plot.

titles

A list, each component of which is named for a column in the data.frame for the asreml.obj used in making the predictions and contains a character string giving a title to use in output (e.g. tables and graphs). Here they will be used for axis labels for nonresponse variables. For response variable labels see y.title.

y.title

The title to be displayed on the y axis of any plot.

filestem

A character sting giving the beginning of the name of the file in which to save the plot. If filestem = NULL, the plot is not saved. The remainder of the file name will be generated automatically and consists of the following elements separated by full stops: the classify term, Bar or Line and, if error.intervals is not "none", one of SE, CI or LSI. The file will be saved as a `png' file in the current work directory.

printPlot

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

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. These functions are applied in creating the ggplot object for plotting.

...

further arguments passed to ggplot.

Author

Chris Brien

Examples

Run this code

if (FALSE) {
data(WaterRunoff.dat)
asreml.options(keep.order = TRUE) #required for asreml-R4 only
current.asr <- asreml(fixed = log.Turbidity ~ Benches + Sources + Type + Species +
                                Sources:Type + Sources:Species + 
                                Sources:xDay + Species:xDay + Species:Date,
                      data = WaterRunoff.dat, keep.order = TRUE)
current.asrt <- as.asrtests(current.asr, NULL, NULL)

#### Get the observed combinations of the factors and variables in classify
class.facs <- c("Species","Date","xDay")
levs <- as.data.frame(table(WaterRunoff.dat[class.facs]))
levs <- as.list(levs[levs$Freq != 0, class.facs])
levs$xDay <- as.numfac(levs$xDay)

predictions <- predict(current.asr, classify="Species:Date:xDay", 
                       parallel = TRUE, levels = levs, 
                       present = c("Type","Species","Sources"))
#### for asreml-R3
predictions <- predictions$predictions$pvals
predictions <- predictions[predictions$est.status == "Estimable",]
#### for asreml-R4
predictions <- predictions$pvals
predictions <- predictions[predictions$status == "Estimable",]
#### end
plotPredictions(classify="Species:Date:xDay", y = "predicted.value", 
                data = predictions, 
                x.num = "xDay", x.fac = "Date", 
                x.title = "Days since first observation",
                y.title = "Predicted log(Turbidity)",
                present = c("Type","Species","Sources"),
                error.intervals = "none",
                ggplotFuncs = list(ggtitle("Transformed turbidity over time")))
  
diffs <- predictPlus(classify="Species:Date:xDay", 
                     present=c("Type","Species","Sources"), 
                     asreml.obj = current.asr, tables = "none", 
                     x.num = "xDay", x.fac = "Date", 
                     parallel = TRUE, levels = levs, 
                     x.plot.values=c(0,28,56,84),
                     wald.tab = current.asrt$wald.tab)
x.title <- "Days since first observation"
names(x.title) <- "xDay"
plotPredictions(classify="Species:Date:xDay", y = "predicted.value", 
               data = diffs$predictions, 
               x.num = "xDay", x.fac = "Date", 
               titles = x.title,
               y.title = "Predicted log(Turbidity)")
}

## Use lmerTest and emmmeans to get predictions and associated statistics
if (requireNamespace("lmerTest", quietly = TRUE) & 
    requireNamespace("emmeans", quietly = TRUE))
{
  data(Ladybird.dat)
  m1.lmer <- lmerTest::lmer(logitP ~ Host*Cadavers*Ladybird + (1|Run),
                            data=Ladybird.dat)
  HCL.emm <- emmeans::emmeans(m1.lmer, specs = ~ Host:Cadavers:Ladybird)
  HCL.preds <- summary(HCL.emm)
  den.df <- min(HCL.preds$df)
  ## Modify HCL.preds to be compatible with a predictions.frame
  HCL.preds <- as.predictions.frame(HCL.preds, predictions = "emmean", 
                                   se = "SE", interval.type = "CI", 
                                   interval.names = c("lower.CL", "upper.CL"))
  ## Plot the predictions
  plotPredictions(HCL.preds, y = "predicted.value", "Host:Cadavers:Ladybird")
}