Compute estimated marginal means for specified factors.

marginalmeans(
model,
variables = NULL,
variables_grid = NULL,
vcov = insight::get_varcov(model),
type = "response"
)

## Arguments

model Model object Categorical predictors over which to compute marginal means (character vector). NULL calculates marginal means for all logical, character, or factor variables in the dataset used to fit model. 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. Matrix or boolean FALSE: does not compute unit-level standard errors. TRUE: computes unit-level standard errors using the default vcov(model) variance-covariance matrix. Named square matrix: computes standard errors with a user-supplied variance-covariance matrix. This matrix must be square and have dimensions equal to the number of coefficients in get_coef(model). Type(s) of prediction as string or vector This can differ based on the model type, but will typically be a string such as: "response", "link", "probs", or "zero".

## Value

Data frame of marginal means with one row per variable-value combination.

## 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, marginalmeans computes marginal means for the variables listed in the variables argument, by average across all categories in the grid.

marginalmeans 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/

## Examples

library(marginaleffects)

# Convert numeric variables to categorical before fitting the model
dat <- mtcars
dat$cyl <- as.factor(dat$cyl)
dat$am <- as.logical(dat$am)
mod <- lm(mpg ~ hp + cyl + am, data = dat)

# Compute and summarize marginal means
mm <- marginalmeans(mod)
summary(mm)
#> Estimated marginal means
#>   Term Group  Mean Std. Error z value   Pr(>|z|) 2.5 % 97.5 %
#> 1  cyl     4 22.88     1.3566   16.87 < 2.22e-16 20.23  25.54
#> 2  cyl     6 18.96     1.0729   17.67 < 2.22e-16 16.86  21.06
#> 3  cyl     8 19.35     1.3771   14.05 < 2.22e-16 16.65  22.05
#> 4   am FALSE 18.32     0.7854   23.33 < 2.22e-16 16.78  19.86
#> 5   am  TRUE 22.48     0.8343   26.94 < 2.22e-16 20.84  24.11
#>
#> Model type:  lm
#> Prediction type:  response