emmip: Interaction-style plots for estimated marginal means

Description

Creates an interaction plot of EMMs based on a fitted model and a simple formula specification.

Usage

emmip(object, formula, ...)
# S3 method for default
emmip(object, formula, type, CIs = FALSE, PIs = FALSE,
  style, engine = get_emm_option("graphics.engine"), pch = c(1, 2, 6, 7, 9,
  10, 15:20), lty = 1, col = NULL, plotit = TRUE,
  nesting.order = FALSE, ...)

Arguments

object

An object of class emmGrid, or a fitted model of a class supported by the emmeans package

formula

Formula of the form trace.factors ~ x.factors | by.factors. The EMMs are plotted against x.factor for each level of trace.factors. by.factors is optional, but if present, it determines separate panels. Each element of this formula may be a single factor in the model, or a combination of factors using the * operator.

...

Additional arguments passed to emmeans (when object is not already an emmGrid object), predict.emmGrid, ggplot, or xyplot.

type

As in predict.emmGrid, this determines whether we want to inverse-transform the predictions (type = "response") or not (any other choice). The default is "link", unless the "predict.type" option is in force; see emm_options.

CIs

Logical value. If TRUE, confidence intervals (or HPD intervals for Bayesian models) are added to the plot (works only with engine = "ggplot").

PIs

Logical value. If TRUE, prediction intervals are added to the plot (works only with engine = "ggplot"). If both CIs and CIs are TRUE, the prediction intervals will be somewhat longer, lighter, and thinner than the confidence intervals. Additional parameters to predict.emmGrid (e.g., sigma) may be passed via .... For Bayesian models, PIs require frequentist = TRUE and a value for sigma.

style

Optional character value. This has an effect only when the horizontal variable is a single numeric variable. If style is unspecified or "numeric", the horizontal scale will be numeric and curves are plotted using lines (and no symbols). With style = "factor", the horizontal variable is treated as the levels of a factor (equally spaced along the horizontal scale), and curves are plotted using lines and symbols. When the horizontal variable is character or factor, or a combination of more than one predictor, "factor" style is always used.

engine

Character value matching "ggplot" (default) or "lattice". The graphics engine to be used to produce the plot. These require, respectively, the ggplot2 or lattice package to be installed.

pch

The plotting characters to use for each group (i.e., levels of trace.factors). They are recycled as needed.

lty

The line types to use for each group. Recycled as needed.

col

The colors to use for each group, recycled as needed. If not specified, the default trellis colors are used.

plotit

Logical value. If TRUE, a graphical object is returned; if FALSE, a data.frame is returned containing all the values used to construct the plot.

nesting.order

Logical value. If TRUE, factors that are nested are presented in order according to their nesting factors, even if those nesting factors are not present in formula. If FALSE, only the variables in formula are used to order the variables.

Value

If plotit = FALSE, a data.frame (actually, a summary_emm object) with the table of EMMs that would be plotted. The variables plotted are named xvar and yvar, and the trace factor is named tvar. This data frame has an added "labs" attribute containing the labels xlab, ylab, and tlab for these respective variables. The confidence limits are also included, renamed LCL and UCL.

If plotit = TRUE, the function returns an object of class "ggplot" or a "trellis", depending on engine.

Details

If object is a fitted model, emmeans is called with an appropriate specification to obtain estimated marginal means for each combination of the factors present in formula (in addition, any arguments in … that match at, trend, cov.reduce, or fac.reduce are passed to emmeans). Otherwise, if object is an emmGrid object, its first element is used, and it must contain one estimate for each combination of the factors present in formula.

Examples

Run this code

# NOT RUN {
#--- Three-factor example
noise.lm = lm(noise ~ size * type * side, data = auto.noise)

# Separate interaction plots of size by type, for each side
emmip(noise.lm, type ~ size | side)

# One interaction plot, using combinations of size and side as the x factor
# ... with added confidence intervals
emmip(noise.lm, type ~ side * size, CIs = TRUE)

# One interaction plot using combinations of type and side as the trace factor
emmip(noise.lm, type * side ~ size)

# Individual traces in panels
emmip(noise.lm, ~ size | type * side)

# Example for the 'style' argument
fib.lm = lm(strength ~ machine * sqrt(diameter), data = fiber)
fib.rg = ref_grid(fib.lm, at = list(diameter = c(3.5, 4, 4.5, 5, 5.5, 6)^2))
emmip(fib.rg, machine ~ diameter)   # curves (because diameter is numeric)
emmip(fib.rg, machine ~ diameter, style = "factor")  # points and lines

# For an example using extra ggplot2 code, see 'vignette("messy-data")',
# in the section on nested models.
# }