View source: R/marginalmeans.R
marginalmeans | R Documentation |
Marginal means are adjusted predictions, averaged across a grid of categorical predictors, holding other numeric predictors at their means. To learn more, read the marginal means vignette, visit the package website, or scroll down this page for a full list of vignettes:
marginalmeans( model, variables = NULL, variables_grid = NULL, vcov = TRUE, conf_level = 0.95, type = NULL, transform_post = NULL, cross = FALSE, hypothesis = NULL, wts = "equal", by = NULL, ... )
model |
Model object |
variables |
character vector Categorical predictors over which to
compute marginal means. |
variables_grid |
character vector Categorical predictors used to
construct the prediction grid over which adjusted predictions are averaged
(character vector). |
vcov |
Type of uncertainty estimates to report (e.g., for robust standard errors). Acceptable values:
|
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 |
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
|
hypothesis |
specify a hypothesis test or custom contrast using a vector, matrix, string, or string formula.
|
wts |
character value. Weights to use in the averaging.
|
by |
Collapse marginal means into categories. Data frame with a |
... |
Additional arguments are passed to the |
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/
Data frame of marginal means with one row per variable-value combination.
Vignettes:
Case studies:
Tips and technical notes:
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 | ||
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) marginalmeans( mod, variables = "cyl") # collapse levels of cyl by averaging by <- data.frame( cyl = c(4, 6, 8), by = c("4 & 6", "4 & 6", "8")) marginalmeans(mod, variables = "cyl", by = by) # pairwise differences between collapsed levels marginalmeans(mod, variables = "cyl", by = by, hypothesis = "pairwise") # cross marginalmeans(mod, variables = c("cyl", "carb"), cross = TRUE) # 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 mm <- marginalmeans(mod) summary(mm) # 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) marginalmeans(mod, variables = "carb", hypothesis = "b2 = b1") marginalmeans(mod, variables = "carb", hypothesis = lc) # 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"))) marginalmeans(mod, variables = "carb", hypothesis = lc)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.