Plot Conditional or Marginal Comparisons
Description
Plot comparisons on the yaxis against values of one or more predictors (xaxis, colors/shapes, and facets).
The by
argument is used to plot marginal comparisons, that is, comparisons made on the original data, but averaged by subgroups. This is analogous to using the by
argument in the comparisons()
function.
The condition
argument is used to plot conditional comparisons, that is, comparisons made on a userspecified grid. This is analogous to using the newdata
argument and datagrid()
function in a comparisons()
call.
All unspecified variables are held at their mean or mode. This includes grouping variables in mixedeffects models, so analysts who fit such models may want to specify the groups of interest using the variables
argument, or supply modelspecific arguments to compute populationlevel estimates. See details below. See the "Plots" vignette and website for tutorials and information on how to customize plots:
Usage
plot_comparisons(
model,
variables = NULL,
condition = NULL,
by = NULL,
newdata = NULL,
type = "response",
vcov = NULL,
conf_level = 0.95,
wts = NULL,
comparison = "difference",
transform = NULL,
rug = FALSE,
gray = FALSE,
draw = TRUE,
...
)
Arguments
model 
Model object

variables 
Name of the variable whose contrast we want to plot on the yaxis.

condition 
Conditional slopes

Character vector (max length 3): Names of the predictors to display.

Named list (max length 3): List names correspond to predictors. List elements can be:

Numeric vector

Function which returns a numeric vector or a set of unique categorical values

Shortcut strings for common reference values: "minmax", "quartile", "threenum"

1: xaxis. 2: color/shape. 3: facets.

Numeric variables in positions 2 and 3 are summarized by Tukey’s five numbers ?stats::fivenum .

by 
Aggregate unitlevel estimates (aka, marginalize, average over). Valid inputs:

FALSE : return the original unitlevel estimates.

TRUE : aggregate estimates for each term.

Character vector of column names in newdata or in the data frame produced by calling the function without the by argument.

Data frame with a by column of group labels, and merging columns shared by newdata or the data frame produced by calling the same function without the by argument.

See examples below.

newdata 
When newdata is NULL , the grid is determined by the condition argument. When newdata is not NULL , the argument behaves in the same way as in the comparisons() function.

type 
string indicates the type (scale) of the predictions used to compute contrasts or slopes. This can differ based on the model type, but will typically be a string such as: "response", "link", "probs", or "zero". When an unsupported string is entered, the modelspecific list of acceptable values is returned in an error message. When type is NULL , the default value is used. This default is the first modelrelated row in the marginaleffects:::type_dictionary dataframe.

vcov 
Type of uncertainty estimates to report (e.g., for robust standard errors). Acceptable values:

FALSE: Do not compute standard errors. This can speed up computation considerably.

TRUE: Unitlevel standard errors using the default vcov(model) variancecovariance matrix.

String which indicates the kind of uncertainty estimates to return.

Heteroskedasticityconsistent: “HC” , “HC0” , “HC1” , “HC2” , “HC3” , “HC4” , “HC4m” , “HC5” . See ?sandwich::vcovHC

Heteroskedasticity and autocorrelation consistent: “HAC”

MixedModels degrees of freedom: "satterthwaite", "kenwardroger"

Other: “NeweyWest” , “KernHAC” , “OPG” . See the sandwich package documentation.

Onesided formula which indicates the name of cluster variables (e.g., ~unit_id ). This formula is passed to the cluster argument of the sandwich::vcovCL function.

Square covariance matrix

Function which returns a covariance matrix (e.g., stats::vcov(model) )

conf_level 
numeric value between 0 and 1. Confidence level to use to build a confidence interval.

wts 
string or numeric: weights to use when computing average contrasts or slopes. These weights only affect the averaging in avg_*() or with the by argument, and not the unitlevel estimates themselves. Internally, estimates and weights are passed to the weighted.mean() function.

string: column name of the weights variable in newdata . When supplying a column name to wts , it is recommended to supply the original data (including the weights variable) explicitly to newdata .

numeric: vector of length equal to the number of rows in the original data or in newdata (if supplied).

comparison 
How should pairs of predictions be compared? Difference, ratio, odds ratio, or userdefined functions.

string: shortcuts to common contrast functions.

Supported shortcuts strings: difference, differenceavg, differenceavgwts, dydx, eyex, eydx, dyex, dydxavg, eyexavg, eydxavg, dyexavg, dydxavgwts, eyexavgwts, eydxavgwts, dyexavgwts, ratio, ratioavg, ratioavgwts, lnratio, lnratioavg, lnratioavgwts, lnor, lnoravg, lnoravgwts, expdydx, expdydxavg, expdydxavgwts

See the Comparisons section below for definitions of each transformation.

function: accept two equallength numeric vectors of adjusted predictions (hi and lo ) and returns a vector of contrasts of the same length, or a unique numeric value.

transform 
string or function. Transformation applied to unitlevel estimates and confidence intervals just before the function returns results. Functions must accept a vector and return a vector of the same length. Support string shortcuts: "exp", "ln"

rug 
TRUE displays tick marks on the axes to mark the distribution of raw data.

gray 
FALSE grayscale or color plot

draw 
TRUE returns a ggplot2 plot. FALSE returns a data.frame of the underlying data.

... 
Additional arguments are passed to the predict() method supplied by the modeling package.These arguments are particularly useful for mixedeffects or bayesian models (see the online vignettes on the marginaleffects website). Available arguments can vary from model to model, depending on the range of supported arguments by each modeling package. See the "ModelSpecific Arguments" section of the ?marginaleffects documentation for a nonexhaustive list of available arguments.

ModelSpecific Arguments
Some model types allow modelspecific arguments to modify the nature of marginal effects, predictions, marginal means, and contrasts. Please report other packagespecific predict()
arguments on Github so we can add them to the table below.
https://github.com/vincentarelbundock/marginaleffects/issues
Package

Class

Argument

Documentation

brms

brmsfit

ndraws

brms::posterior_predict



re_formula

brms::posterior_predict

lme4

merMod

re.form

lme4::predict.merMod



allow.new.levels

lme4::predict.merMod

glmmTMB

glmmTMB

re.form

glmmTMB::predict.glmmTMB



allow.new.levels

glmmTMB::predict.glmmTMB



zitype

glmmTMB::predict.glmmTMB

mgcv

bam

exclude

mgcv::predict.bam

robustlmm

rlmerMod

re.form

robustlmm::predict.rlmerMod



allow.new.levels

robustlmm::predict.rlmerMod

MCMCglmm

MCMCglmm

ndraws



Examples
Warning: The `am` variable is treated as a categorical (factor) variable, but the
original data is of class numeric. It is safer and faster to convert
such variables to factor before fitting the model and calling `slopes`
functions.
This warning appears once per session.