This alias is kept for backward compatibility and because some users may prefer that name.

## Usage

```
marginalmeans(
model,
variables = NULL,
variables_grid = NULL,
vcov = TRUE,
conf_level = 0.95,
type = NULL,
transform_post = NULL,
cross = FALSE,
hypothesis = NULL,
df = Inf,
wts = "equal",
by = NULL,
...
)
```

## Arguments

- model
Model object

- variables
character vector Categorical predictors over which to compute marginal means.

`NULL`

calculates marginal means for all logical, character, or factor variables in the dataset used to fit`model`

. Set`cross=TRUE`

to compute marginal means at combinations of the predictors specified in the`variables`

argument.- variables_grid
character vector Categorical predictors used to construct the prediction grid over which adjusted predictions are averaged (character vector).

`NULL`

creates a grid with all combinations of all categorical predictors. This grid can be very large when there are many variables and many response levels, so it is advisable to select a limited number of variables in the`variables`

and`variables_grid`

arguments.- 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.

- type
string indicates the type (scale) of the predictions used to compute marginal effects or contrasts. 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. If`type`

is`NULL`

and the default value is "response", the function tries to compute marginal means on the link scale before backtransforming them using the inverse link function.- transform_post
(experimental) A function applied to unit-level adjusted predictions and confidence intervals just before the function returns results. For bayesian models, this function is applied to individual draws from the posterior distribution, before computing summaries.

- cross
TRUE or FALSE

`FALSE`

(default): Marginal means are computed for each predictor individually.`TRUE`

: Marginal means are computed for each combination of predictors specified in the`variables`

argument.

- hypothesis
specify a hypothesis test or custom contrast using a numeric value, vector, or matrix, a string, or a string formula.

Numeric:

Single value: the null hypothesis used in the computation of Z and p (before applying

`transform_post`

).Vector: Weights to compute a linear combination of (custom contrast between) estimates. Length equal to the number of rows generated by the same function call, but without the

`hypothesis`

argument.Matrix: Each column is a vector of weights, as describe above, used to compute a distinct linear combination of (contrast between) estimates. The column names of the matrix are used as labels in the output.

String formula to specify linear or non-linear hypothesis tests. If the

`term`

column uniquely identifies rows, terms can be used in the formula. Otherwise, use`b1`

,`b2`

, etc. to identify the position of each parameter. Examples:`hp = drat`

`hp + drat = 12`

`b1 + b2 + b3 = 0`

String:

"pairwise": pairwise differences between estimates in each row.

"reference": differences between the estimates in each row and the estimate in the first row.

"sequential": difference between an estimate and the estimate in the next row.

"revpairwise", "revreference", "revsequential": inverse of the corresponding hypotheses, as described above.

See the Examples section below and the vignette: https://vincentarelbundock.github.io/marginaleffects/articles/hypothesis.html

- df
Degrees of freedom used to compute p values and confidence intervals. A single numeric value between 1 and

`Inf`

. When`df`

is`Inf`

, the normal distribution is used. When`df`

is finite, the`t`

distribution is used. See insight::get_df for a convenient function to extract degrees of freedom. Ex:`slopes(model, df = insight::get_df(model))`

- wts
character value. Weights to use in the averaging.

"equal": each combination of variables in

`variables_grid`

gets an equal weight."cells": each combination of values for the variables in the

`variables_grid`

gets a weight proportional to its frequency in the original data."proportional": each combination of values for the variables in the

`variables_grid`

-- except for those in the`variables`

argument -- gets a weight proportional to its frequency in the original data.

- by
Collapse marginal means into categories. 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.- ...
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.

## Details

This function begins by calling the `predictions`

function to obtain a
grid of predictors, and adjusted predictions for each cell. The grid
includes all combinations of the categorical variables listed in the
`variables`

and `variables_grid`

arguments, or all combinations of the
categorical variables used to fit the model if `variables_grid`

is `NULL`

.
In the prediction grid, numeric variables are held at their means.

After constructing the grid and filling the grid with adjusted predictions,
`marginal_means`

computes marginal means for the variables listed in the
`variables`

argument, by average across all categories in the grid.

`marginal_means`

can only compute standard errors for linear models, or for
predictions on the link scale, that is, with the `type`

argument set to
"link".

The `marginaleffects`

website compares the output of this function to the
popular `emmeans`

package, which provides similar but more advanced
functionality: https://vincentarelbundock.github.io/marginaleffects/

## Model-Specific Arguments

Some model types allow model-specific arguments to modify the nature of marginal effects, predictions, marginal means, and contrasts.

Package | Class | Argument | Documentation |

`brms` | `brmsfit` | `ndraws` | brms::posterior_predict |

`re_formula` | |||

`lme4` | `merMod` | `include_random` | insight::get_predicted |

`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 |

## Bayesian posterior summaries

By default, credible intervals in bayesian models are built as equal-tailed intervals. This can be changed to a highest density interval by setting a global option:

`options("marginaleffects_posterior_interval" = "eti")`

`options("marginaleffects_posterior_interval" = "hdi")`

By default, the center of the posterior distribution in bayesian models is identified by the median. Users can use a different summary function by setting a global option:

`options("marginaleffects_posterior_center" = "mean")`

`options("marginaleffects_posterior_center" = "median")`

When estimates are averaged using the `by`

argument, the `tidy()`

function, or
the `summary()`

function, the posterior distribution is marginalized twice over.
First, we take the average *across* units but *within* each iteration of the
MCMC chain, according to what the user requested in `by`

argument or
`tidy()/summary()`

functions. Then, we identify the center of the resulting
posterior using the function supplied to the
`"marginaleffects_posterior_center"`

option (the median by default).

## Examples

```
library(marginaleffects)
# simple marginal means for each level of `cyl`
dat <- mtcars
dat$carb <- factor(dat$carb)
dat$cyl <- factor(dat$cyl)
dat$am <- as.logical(dat$am)
mod <- lm(mpg ~ carb + cyl + am, dat)
marginal_means(
mod,
variables = "cyl")
#> Error: Elements of the `variables` argument were not found as column names in
#> the data used to fit the model: cyl
# collapse levels of cyl by averaging
by <- data.frame(
cyl = c(4, 6, 8),
by = c("4 & 6", "4 & 6", "8"))
marginal_means(mod,
variables = "cyl",
by = by)
#> Error: The `by` argument must be either:
#>
#> 1. Character vector in which each element is part of: Package, Function,
#> dydx, se, stata_dydx, stata_se, margins_dydx, margins_se, emmeans_dydx,
#> emmeans_se
#>
#> 2. A data frame with a `by` column of labels, and in which all other
#> columns are elements of: Package, Function, dydx, se, stata_dydx,
#> stata_se, margins_dydx, margins_se, emmeans_dydx, emmeans_se
#>
#> It can sometimes be useful to supply a data frame explicitly to the
#> `newdata` argument in order to be able to group by different columns.
# pairwise differences between collapsed levels
marginal_means(mod,
variables = "cyl",
by = by,
hypothesis = "pairwise")
#> Error: The `by` argument must be either:
#>
#> 1. Character vector in which each element is part of: Package, Function,
#> dydx, se, stata_dydx, stata_se, margins_dydx, margins_se, emmeans_dydx,
#> emmeans_se
#>
#> 2. A data frame with a `by` column of labels, and in which all other
#> columns are elements of: Package, Function, dydx, se, stata_dydx,
#> stata_se, margins_dydx, margins_se, emmeans_dydx, emmeans_se
#>
#> It can sometimes be useful to supply a data frame explicitly to the
#> `newdata` argument in order to be able to group by different columns.
# cross
marginal_means(mod,
variables = c("cyl", "carb"),
cross = TRUE)
#> Error: Elements of the `variables` argument were not found as column names in
#> the data used to fit the model: cyl, carb
# collapsed cross
by <- expand.grid(
cyl = unique(mtcars$cyl),
carb = unique(mtcars$carb))
by$by <- ifelse(
by$cyl == 4,
paste("Control:", by$carb),
paste("Treatment:", by$carb))
# Convert numeric variables to categorical before fitting the model
dat <- mtcars
dat$am <- as.logical(dat$am)
dat$carb <- as.factor(dat$carb)
mod <- lm(mpg ~ hp + am + carb, data = dat)
# Compute and summarize marginal means
marginal_means(mod)
#> Error: No logical, factor, or character variable was found in the dataset used
#> to fit the `model` object. This error is often raised when users convert
#> variables to factor in the model formula (e.g., `lm(y ~ factor(x)`). If
#> this is the case, you may consider converting variables in the dataset
#> before fitting the model.
# Contrast between marginal means (carb2 - carb1), or "is the 1st marginal means equal to the 2nd?"
# see the vignette on "Hypothesis Tests and Custom Contrasts" on the `marginaleffects` website.
lc <- c(-1, 1, 0, 0, 0, 0)
marginal_means(mod, variables = "carb", hypothesis = "b2 = b1")
#> Error: Elements of the `variables` argument were not found as column names in
#> the data used to fit the model: carb
marginal_means(mod, variables = "carb", hypothesis = lc)
#> Error: Elements of the `variables` argument were not found as column names in
#> the data used to fit the model: carb
# Multiple custom contrasts
lc <- matrix(c(
-2, 1, 1, 0, -1, 1,
-1, 1, 0, 0, 0, 0
),
ncol = 2,
dimnames = list(NULL, c("A", "B")))
marginal_means(mod, variables = "carb", hypothesis = lc)
#> Error: Elements of the `variables` argument were not found as column names in
#> the data used to fit the model: carb
```