View source: R/marginaleffects.R
marginaleffects | R Documentation |
Partial derivative (slope) of the regression equation with respect to a
regressor of interest. The tidy()
and summary()
functions can be used to
aggregate and summarize the output of marginaleffects()
. To learn more,
read the marginal effects vignette, visit the package website, or scroll
down this page for a full list of vignettes:
marginaleffects( model, newdata = NULL, variables = NULL, vcov = TRUE, conf_level = 0.95, type = NULL, slope = "dydx", by = NULL, wts = NULL, hypothesis = NULL, eps = NULL, ... )
model |
Model object |
newdata |
|
variables |
|
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 |
slope |
string indicates the type of slope or (semi-)elasticity to compute:
|
by |
Character vector of variable names over which to compute group-wise estimates. |
wts |
string or numeric: weights to use when computing average
contrasts or marginaleffects. These weights only affect the averaging in
|
hypothesis |
specify a hypothesis test or custom contrast using a vector, matrix, string, or string formula.
|
eps |
NULL or numeric value which determines the step size to use when
calculating numerical derivatives: (f(x+eps)-f(x))/eps. When |
... |
Additional arguments are passed to the |
A "marginal effect" is the partial derivative of the regression equation with respect to a variable in the model. This function uses automatic differentiation to compute marginal effects for a vast array of models, including non-linear models with transformations (e.g., polynomials). Uncertainty estimates are computed using the delta method.
The newdata
argument can be used to control the kind of marginal effects to report:
Average Marginal Effects (AME)
Group-Average Marginal Effects (G-AME)
Marginal Effects at the Mean (MEM) or
Marginal Effects at User-Specified values (aka Marginal Effects at Representative values, MER).
See the marginaleffects vignette for worked-out examples of each kind of marginal effect.
Numerical derivatives for the marginaleffects
function are calculated
using a simple epsilon difference approach: dY/dX = (f(X + e) - f(X)) / e,
where f is the predict()
method associated with the model class, and
e is determined by the eps
argument.
Warning: Some models are particularly sensitive to eps
, so it is good
practice to try different values of this argument.
Standard errors for the marginal effects are obtained using the Delta method. See the "Standard Errors" vignette on the package website for details (link above).
A data.frame
with one row per observation (per term/group) and several columns:
rowid
: row number of the newdata
data frame
type
: prediction type, as defined by the type
argument
group
: (optional) value of the grouped outcome (e.g., categorical outcome models)
term
: the variable whose marginal effect is computed
dydx
: marginal effect of the term on the outcome for a given combination of regressor values
std.error
: standard errors computed by via the delta method.
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 | ||
mod <- glm(am ~ hp * wt, data = mtcars, family = binomial) mfx <- marginaleffects(mod) head(mfx) # Average Marginal Effect (AME) summary(mfx) tidy(mfx) plot(mfx) # Marginal Effect at the Mean (MEM) marginaleffects(mod, newdata = datagrid()) # Marginal Effect at User-Specified Values # Variables not explicitly included in `datagrid()` are held at their means marginaleffects(mod, newdata = datagrid(hp = c(100, 110))) # Group-Average Marginal Effects (G-AME) # Calculate marginal effects for each observation, and then take the average # marginal effect within each subset of observations with different observed # values for the `cyl` variable: mod2 <- lm(mpg ~ hp * cyl, data = mtcars) mfx2 <- marginaleffects(mod2, variables = "hp", by = "cyl") summary(mfx2) # Marginal Effects at User-Specified Values (counterfactual) # Variables not explicitly included in `datagrid()` are held at their # original values, and the whole dataset is duplicated once for each # combination of the values in `datagrid()` mfx <- marginaleffects(mod, newdata = datagrid(hp = c(100, 110), grid_type = "counterfactual")) head(mfx) # Heteroskedasticity robust standard errors marginaleffects(mod, vcov = sandwich::vcovHC(mod)) # hypothesis test: is the `hp` marginal effect at the mean equal to the `drat` marginal effect mod <- lm(mpg ~ wt + drat, data = mtcars) marginaleffects( mod, newdata = "mean", hypothesis = "wt = drat") # same hypothesis test using row indices marginaleffects( mod, newdata = "mean", hypothesis = "b1 - b2 = 0") # same hypothesis test using numeric vector of weights marginaleffects( mod, newdata = "mean", hypothesis = c(1, -1)) # two custom contrasts using a matrix of weights lc <- matrix(c( 1, -1, 2, 3), ncol = 2) colnames(lc) <- c("Contrast A", "Contrast B") marginaleffects( mod, newdata = "mean", hypothesis = lc)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.