emmeans: plot – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

plot

Plot an emmGrid or summary_emm object

Description

Methods are provided to plot EMMs as side-by-side CIs, and optionally to display “comparison arrows” for displaying pairwise comparisons.

Usage

## S3 method for class 'emmGrid'
plot(x, y, type, CIs = TRUE, PIs = FALSE,
  comparisons = FALSE, colors = c("black", "blue", "blue", "red"),
  alpha = 0.05, adjust = "tukey", int.adjust = "none", intervals,
  frequentist, ...)

## S3 method for class 'summary_emm'
plot(x, y, horizontal = TRUE, CIs = TRUE, xlab, ylab,
  layout, colors = c("black", "blue", "blue", "red"), intervals,
  plotit = TRUE, ...)

Arguments

`x`	Object of class `emmGrid` or `summary_emm`
`y`	(Required but ignored)
`type`	Character value specifying the type of prediction desired (matching `"linear.predictor"`, `"link"`, or `"response"`). See details under `summary.emmGrid`.
`CIs`	Logical value. If `TRUE`, confidence intervals are plotted for each estimate.
`PIs`	Logical value. If `TRUE`, prediction intervals are plotted for each estimate. If `objecct` is a Bayesian model, this requires `frequentist = TRUE` and `sigma =` (some value). Note that the `PIs` option is not available with `summary_emm` objects – only for `emmGrid` objects. Also, prediction intervals are not available with `engine = "lattice"`.
`comparisons`	Logical value. If `TRUE`, “comparison arrows” are added to the plot, in such a way that the degree to which arrows overlap reflects as much as possible the significance of the comparison of the two estimates. (A warning is issued if this can't be done.) Note that comparison arrows are not available with 'summary_emm' objects.
`colors`	Character vector of color names to use for estimates, CIs, PIs, and comparison arrows, respectively. CIs and PIs are rendered with some transparency, and colors are recycled if the length is less than four; so all plot elements are visible even if a single color is specified.
`alpha`	The significance level to use in constructing comparison arrows
`adjust`	Character value: Multiplicity adjustment method for comparison arrows only.
`int.adjust`	Character value: Multiplicity adjustment method for the plotted confidence intervals only.
`intervals`	If specified, it is used to set `CIs`. This is the previous argument name for `CIs` and is provided for backward compatibility.
`frequentist`	Logical value. If there is a posterior MCMC sample and `frequentist` is non-missing and TRUE, a frequentist summary is used for obtaining the plot data, rather than the posterior point estimate and HPD intervals. This argument is ignored when it is not a Bayesian model.
`...`	Additional arguments passed to `update.emmGrid`, `predict.emmGrid`, or `dotplot`
`horizontal`	Logical value specifying whether the intervals should be plotted horizontally or vertically
`xlab`	Character label for horizontal axis
`ylab`	Character label for vertical axis
`layout`	Numeric value passed to `dotplot` when `engine == "lattice"`.
`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.

Value

If plotit = TRUE, a graphical object is returned.

If plotit = FALSE, a data.frame with the table of EMMs that would be plotted. In the latter case, the estimate being plotted is named the.emmean, and any factors involved have the same names as in the object. Confidence limits are named lower.CL and upper.CL, prediction limits are named lpl and upl, and comparison-arrow limits are named lcmpl and ucmpl. There is also a variable named pri.fac which contains the factor combinations that are not among the by variables.

Details

If any by variables are in force, the plot is divided into separate panels. For "summary_emm" objects, the ... arguments in plot are passed only to dotplot, whereas for "emmGrid" objects, the object is updated using ... before summarizing and plotting.

In plots with comparisons = TRUE, the resulting arrows are only approximate, and in some cases may fail to accurately reflect the pairwise comparisons of the estimates – especially when estimates having large and small standard errors are intermingled in just the wrong way. Note that the maximum and minimum estimates have arrows only in one direction, since there is no need to compare them with anything higher or lower, respectively. See the vignette("xplanations", "emmeans") for details on how these are derived.

If adjust or int.adjust are not supplied, they default to the internal adjust setting saved in pairs(x) and x respectively (see update.emmGrid).

Examples

warp.lm <- lm(breaks ~ wool * tension, data = warpbreaks)
warp.emm <- emmeans(warp.lm, ~ tension | wool)
plot(warp.emm)
plot(warp.emm, by = NULL, comparisons = TRUE, adjust = "mvt", 
     horizontal = FALSE, colors = "darkgreen")

emmeans

Estimated Marginal Means, aka Least-Squares Means

v1.6.0

GPL-2 | GPL-3

Authors

Russell V. Lenth [aut, cre, cph], Paul Buerkner [ctb], Maxime Herve [ctb], Jonathon Love [ctb], Hannes Riebl [ctb], Henrik Singmann [ctb]

Initial release

2021-04-25