comparisons | R Documentation |
Difference, ratio, or function of adjusted predictions, calculated for
meaningfully different predictor values. The tidy()
and summary()
functions can be used to aggregate and summarize the output of
comparisons()
. To learn more, read the contrasts vignette, visit the
package website, or scroll down this page for a full list of vignettes:
comparisons( model, newdata = NULL, variables = NULL, type = NULL, vcov = TRUE, conf_level = 0.95, transform_pre = "difference", transform_post = NULL, cross = FALSE, by = NULL, wts = NULL, hypothesis = NULL, eps = NULL, ... )
model |
Model object |
newdata |
|
variables |
|
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 |
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. |
transform_pre |
string or function. How should pairs of adjusted predictions be contrasted?
|
transform_post |
string or function. Transformation applied to unit-level estimates and confidence intervals just before the function returns results. Functions must accept a vector and return a vector of the same length. Support string shortcuts: "exp", "ln" |
cross |
TRUE or FALSE
|
by |
Compute group-wise average estimates. Valid inputs:
|
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 "contrast" is a difference, ratio of function of adjusted predictions, calculated for meaningfully different predictor values (e.g., College graduates vs. Others). Uncertainty estimates are computed using the delta method.
The newdata
argument can be used to control the kind of contrasts to report:
Average Contrasts
Adjusted Risk Ratios
Adjusted Risk Differences
Group-Average Contrasts
Contrasts at the Mean
Contrasts at User-Specified values (aka Contrasts at Representative values, MER).
Custom contrasts using arbitrary functions
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 | ||
The following transformations can be applied by supplying one of the shortcut strings to the
transform_pre
argument.
hi
is a vector of adjusted predictions for the "high" side of the
contrast. lo
is a vector of adjusted predictions for the "low" side of the
contrast. y
is a vector of adjusted predictions for the original data. x
is the predictor in the original data. eps
is the step size to use to
compute derivatives and elasticities.
Shortcut | Function |
difference | \(hi, lo) hi - lo |
differenceavg | \(hi, lo) mean(hi) - mean(lo) |
differenceavgwts | \(hi, lo, w) wmean(hi, w) - wmean(lo, w) |
dydx | \(hi, lo, eps) (hi - lo)/eps |
eyex | \(hi, lo, eps, y, x) (hi - lo)/eps * (x/y) |
eydx | \(hi, lo, eps, y, x) ((hi - lo)/eps)/y |
dyex | \(hi, lo, eps, x) ((hi - lo)/eps) * x |
dydxavg | \(hi, lo, eps) mean((hi - lo)/eps) |
eyexavg | \(hi, lo, eps, y, x) mean((hi - lo)/eps * (x/y)) |
eydxavg | \(hi, lo, eps, y, x) mean(((hi - lo)/eps)/y) |
dyexavg | \(hi, lo, eps, x) mean(((hi - lo)/eps) * x) |
dydxavgwts | \(hi, lo, eps, w) wmean((hi - lo)/eps, w) |
eyexavgwts | \(hi, lo, eps, y, x, w) wmean((hi - lo)/eps * (x/y), w) |
eydxavgwts | \(hi, lo, eps, y, x, w) wmean(((hi - lo)/eps)/y, w) |
dyexavgwts | \(hi, lo, eps, x, w) wmean(((hi - lo)/eps) * x, w) |
ratio | \(hi, lo) hi/lo |
ratioavg | \(hi, lo) mean(hi)/mean(lo) |
ratioavgwts | \(hi, lo) wmean(hi)/wmean(lo) |
lnratio | \(hi, lo) log(hi/lo) |
lnratioavg | \(hi, lo) log(mean(hi)/mean(lo)) |
lnratioavgwts | \(hi, lo) log(wmean(hi)/wmean(lo)) |
lnor | \(hi, lo) log((hi/(1 - hi))/(lo/(1 - lo))) |
lnoravg | \(hi, lo) log((mean(hi)/(1 - mean(hi)))/(mean(lo)/(1 - mean(lo)))) |
lnoravgwts | \(hi, lo, w) log((wmean(hi, w)/(1 - wmean(hi, w)))/(wmean(lo, w)/(1 - wmean(lo, w)))) |
expdydx | \(hi, lo, eps) ((exp(hi) - exp(lo))/exp(eps))/eps |
expdydxavg | \(hi, lo, eps) mean(((exp(hi) - exp(lo))/exp(eps))/eps) |
expdydxavgwts | \(hi, lo, eps, w) wmean(((exp(hi) - exp(lo))/exp(eps))/eps, w) |
library(marginaleffects) library(magrittr) # Linear model tmp <- mtcars tmp$am <- as.logical(tmp$am) mod <- lm(mpg ~ am + factor(cyl), tmp) comparisons(mod, variables = list(cyl = "reference")) %>% tidy() comparisons(mod, variables = list(cyl = "sequential")) %>% tidy() comparisons(mod, variables = list(cyl = "pairwise")) %>% tidy() # GLM with different scale types mod <- glm(am ~ factor(gear), data = mtcars) comparisons(mod, type = "response") %>% tidy() comparisons(mod, type = "link") %>% tidy() # Contrasts at the mean comparisons(mod, newdata = "mean") # Contrasts between marginal means comparisons(mod, newdata = "marginalmeans") # Contrasts at user-specified values comparisons(mod, newdata = datagrid(am = 0, gear = tmp$gear)) comparisons(mod, newdata = datagrid(am = unique, gear = max)) m <- lm(mpg ~ hp + drat + factor(cyl) + factor(am), data = mtcars) comparisons(m, variables = "hp", newdata = datagrid(FUN_factor = unique, FUN_numeric = median)) # Numeric contrasts mod <- lm(mpg ~ hp, data = mtcars) comparisons(mod, variables = list(hp = 1)) %>% tidy() comparisons(mod, variables = list(hp = 5)) %>% tidy() comparisons(mod, variables = list(hp = c(90, 100))) %>% tidy() comparisons(mod, variables = list(hp = "iqr")) %>% tidy() comparisons(mod, variables = list(hp = "sd")) %>% tidy() comparisons(mod, variables = list(hp = "minmax")) %>% tidy() # using a function to specify a custom difference in one regressor dat <- mtcars dat$new_hp <- 49 * (dat$hp - min(dat$hp)) / (max(dat$hp) - min(dat$hp)) + 1 modlog <- lm(mpg ~ log(new_hp) + factor(cyl), data = dat) fdiff <- \(x) data.frame(x, x + 10) comparisons(modlog, variables = list(new_hp = fdiff)) %>% summary() # Adjusted Risk Ratio: see the contrasts vignette mod <- glm(vs ~ mpg, data = mtcars, family = binomial) cmp <- comparisons(mod, transform_pre = "lnratioavg") summary(cmp, transform_avg = exp) # Adjusted Risk Ratio: Manual specification of the `transform_pre` cmp <- comparisons(mod, transform_pre = function(hi, lo) log(mean(hi) / mean(lo))) summary(cmp, transform_avg = exp) # cross contrasts mod <- lm(mpg ~ factor(cyl) * factor(gear) + hp, data = mtcars) cmp <- comparisons(mod, variables = c("cyl", "gear"), cross = TRUE) summary(cmp) # variable-specific contrasts cmp <- comparisons(mod, variables = list(gear = "sequential", hp = 10)) summary(cmp) # hypothesis test: is the `hp` marginal effect at the mean equal to the `drat` marginal effect mod <- lm(mpg ~ wt + drat, data = mtcars) comparisons( mod, newdata = "mean", hypothesis = "wt = drat") # same hypothesis test using row indices comparisons( mod, newdata = "mean", hypothesis = "b1 - b2 = 0") # same hypothesis test using numeric vector of weights comparisons( mod, newdata = "mean", hypothesis = c(1, -1)) # two custom contrasts using a matrix of weights lc <- matrix(c( 1, -1, 2, 3), ncol = 2) comparisons( mod, newdata = "mean", hypothesis = lc) # `by` argument mod <- lm(mpg ~ hp * am * vs, data = mtcars) cmp <- comparisons(mod, variables = "hp", by = c("vs", "am")) summary(cmp) library(nnet) mod <- multinom(factor(gear) ~ mpg + am * vs, data = mtcars, trace = FALSE) by <- data.frame( group = c("3", "4", "5"), by = c("3,4", "3,4", "5")) comparisons(mod, type = "probs", by = by)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.