Plot comparisons on the y-axis against values of one or more predictors (x-axis, 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 user-specified grid. This is analogous to using the `newdata`

argument and `datagrid()`

function in a `comparisons()`

call. Unspecified variables are held at their mean or mode.

See the "Plots" vignette and website for tutorials and information on how to customize plots:

https://vincentarelbundock.github.io/marginaleffects/articles/plot.html

https://vincentarelbundock.github.io/marginaleffects

## Usage

```
plot_comparisons(
model,
variables = NULL,
condition = NULL,
by = NULL,
type = "response",
vcov = NULL,
conf_level = 0.95,
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 y-axis.

- 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: x-axis. 2: color/shape. 3: facets.

Numeric variables in positions 2 and 3 are summarized by Tukey's five numbers

`?stats::fivenum`

.

- by
Aggregate unit-level estimates (aka, marginalize, average over). Valid inputs:

`FALSE`

: return the original unit-level 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.

- 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 model-specific list of acceptable values is returned in an error message. When

`type`

is`NULL`

, the default value is used. This default is the first model-related 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: Unit-level standard errors using the default

`vcov(model)`

variance-covariance matrix.String which indicates the kind of uncertainty estimates to return.

Heteroskedasticity-consistent:

`"HC"`

,`"HC0"`

,`"HC1"`

,`"HC2"`

,`"HC3"`

,`"HC4"`

,`"HC4m"`

,`"HC5"`

. See`?sandwich::vcovHC`

Heteroskedasticity and autocorrelation consistent:

`"HAC"`

Mixed-Models degrees of freedom: "satterthwaite", "kenward-roger"

Other:

`"NeweyWest"`

,`"KernHAC"`

,`"OPG"`

. See the`sandwich`

package documentation.

One-sided 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.

- comparison
How should pairs of predictions be compared? Difference, ratio, odds ratio, or user-defined 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 equal-length numeric vectors of adjusted predictions (

`hi`

and`lo`

) and returns a vector of contrasts of the same length, or a unique numeric value.See the Transformations section below for examples of valid functions.

- transform
string or function. Transformation applied to unit-level 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 mixed-effects 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 "Model-Specific Arguments" section of the`?marginaleffects`

documentation for a non-exhaustive list of available arguments.

## Examples

```
mod <- lm(mpg ~ hp * drat * factor(am), data = mtcars)
plot_comparisons(mod, variables = "hp", condition = "drat")
plot_comparisons(mod, variables = "hp", condition = c("drat", "am"))
plot_comparisons(mod, variables = "hp", condition = list("am", "drat" = 3:5))
plot_comparisons(mod, variables = "am", condition = list("hp", "drat" = range))
plot_comparisons(mod, variables = "am", condition = list("hp", "drat" = "threenum"))
```