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 modelspecific 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 groupwise 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 nonlinear 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)
GroupAverage Marginal Effects (GAME)
Marginal Effects at the Mean (MEM) or
Marginal Effects at UserSpecified values (aka Marginal Effects at Representative values, MER).
See the marginaleffects vignette for workedout 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 modelspecific 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 UserSpecified Values # Variables not explicitly included in `datagrid()` are held at their means marginaleffects(mod, newdata = datagrid(hp = c(100, 110))) # GroupAverage Marginal Effects (GAME) # 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 UserSpecified 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.