sim_ame {clarify}  R Documentation 
Compute average marginal effects
Description
sim_ame()
is a wrapper for sim_apply()
that computes average
marginal effects, the average effect of changing a single variable from one
value to another (i.e., from one category to another for categorical
variables or a tiny change for continuous variables).
Usage
sim_ame(
sim,
var,
subset = NULL,
by = NULL,
contrast = NULL,
outcome = NULL,
type = NULL,
eps = 1e05,
verbose = TRUE,
cl = NULL
)
## S3 method for class 'clarify_ame'
print(x, digits = NULL, max.ests = 6, ...)
Arguments
sim 
a 
var 
either the names of the variables for which marginal effects are to be computed or a named list containing the values the variables should take. See Details. 
subset 
optional; a vector used to subset the data used to compute the
marginal effects. This will be evaluated within the original dataset used
to fit the model using 
by 
a onesided formula or character vector containing the names of
variables for which to stratify the estimates. Each quantity will be
computed within each level of the complete cross of the variables specified
in 
contrast 
a string containing the name of a contrast between the
average marginal means when the variable named in 
outcome 
a string containing the name of the outcome or outcome level for multivariate (multiple outcomes) or multicategory outcomes. Ignored for univariate (single outcome) and binary outcomes. 
type 
a string containing the type of predicted values (e.g., the link
or the response). Passed to 
eps 
when the variable named in 
verbose 

cl 
a cluster object created by 
x 
a 
digits 
the minimum number of significant digits to be used; passed to 
max.ests 
the maximum number of estimates to display. 
... 
optional arguments passed to 
Details
sim_ame()
computes average adjusted predictions or average marginal effects depending on which variables are named in var
and how they are specified. Canonically, var
should be specified as a named list with the value(s) each variable should be set to. For example, specifying var = list(x1 = 0:1)
computes average adjusted predictions setting x1
to 0 and 1. Specifying a variable's values as NULL
, e.g., list(x1 = NULL)
, is equivalent to requesting average adjusted predictions at each unique value of the variable when that variable is binary or a factor or character and requests the average marginal effect of that variable otherwise. Specifying an unnamed entry in the list with a string containing the value of that variable, e.g., list("x1")
is equivalent to specifying list(x1 = NULL)
. Similarly, supplying a vector with the names of the variables is equivalent to specifying a list, e.g., var = "x1"
is equivalent to var = list(x1 = NULL)
.
Multiple variables can be supplied to var
at the same time to set the corresponding variables to those values. If all values are specified directly or the variables are categorical, e.g., list(x1 = 0:1, x2 = c(5, 10))
, this computes average adjusted predictions at each combination of the supplied variables. If any one variable's values is specified as NULL
and the variable is continuous, the average marginal effect of that variable will be computed with the other variables set to their corresponding combinations. For example, if x2
is a continuous variable, specifying var = list(x1 = 0:1, x2 = NULL)
requests the average marginal effect of x2
computed first setting x1
to 0 and then setting x1
to 1. The average marginal effect can only be computed for one variable at a time.
Below are some examples of specifications and what they request, assuming x1
is a binary variable taking on values of 0 and 1 and x2
is a continuous variable:

list(x1 = 0:1)
,list(x1 = NULL)
,list("x1")
,"x1"
– the average adjusted predictions settingx1
to 0 and to 1 
list(x2 = NULL)
,list("x2")
,"x2"
– the average marginal effect ofx2

list(x2 = c(5, 10))
– the average adjusted predictions settingx2
to 5 and to 10 
list(x1 = 0:1, x2 = c(5, 10))
,list("x1", x2 = c(5, 10))
– the average adjusted predictions settingx1
andx2
in a full cross of 0, 1 and 5, 10, respectively (e.g., (0, 5), (0, 10), (1, 5), and (1, 10)) 
list(x1 = 0:1, "x2")
,list("x1", "x2")
,c("x1", "x2")
– the average marginal effects ofx2
settingx1
to 0 and to 1
The average adjusted prediction is the average predicted outcome
value after setting all units' value of a variable to a specified level. (This quantity
has several names, including the average potential outcome, average marginal mean, and standardized mean). When exactly two average adjusted predictions are requested, a contrast
between them can be requested by supplying an argument
to contrast
(see Effect Measures section below). Contrasts can be manually computed using transform()
afterward as well; this is required when multiple average adjusted predictions are requested (i.e., because a single variable was supplied to var
with more than two levels or a combination of multiple variables was supplied).
A marginal effect is the instantaneous rate of change
corresponding to changing a unit's observed value of a variable by a tiny amount
and considering to what degree the predicted outcome changes. The ratio of
the change in the predicted outcome to the change in the value of the variable is
the marginal effect; these are averaged across the sample to arrive at an
average marginal effect. The "tiny amount" used is eps
times the standard
deviation of the focal variable.
The difference between using by
or subset
vs. var
is that by
and subset
subset the data when computing the requested quantity, whereas var
sets the corresponding variable to given a value for all units. For example, using by = ~v
computes the quantity of interest separately for each subset of the data defined by v
, whereas setting var = list(., "v")
computes the quantity of interest for all units setting their value of v
to its unique values. The resulting quantities have different interpretations. Both by
and var
can be used simultaneously.
Effect measures
The effect measures specified in contrast
are defined below. Typically only
"diff"
is appropriate for continuous outcomes and "diff"
or "irr"
are
appropriate for count outcomes; the rest are appropriate for binary outcomes.
For a focal variable with two levels, 0
and 1
, and an outcome Y
, the
average marginal means will be denoted in the below formulas as E[Y(0)]
and
E[Y(1)]
, respectively.
contrast  Description  Formula 
"diff" /"rd"  Mean/risk difference  E[Y(1)]  E[Y(0)] 
"rr" /"irr"  Risk ratio/incidence rate ratio  E[Y(1)] / E[Y(0)] 
"sr"  Survival ratio  (1  E[Y(1)]) / (1  E[Y(0)]) 
"srr" /"grrr"  Switch risk ratio  1  sr if E[Y(1)] > E[Y(0)] 
rr  1 if E[Y(1)] < E[Y(0)] 

0 otherwise 

"or"  Odds ratio  O[Y(1)] / O[Y(0)] 
where O[Y(.)] = E[Y(.)] / (1  E[Y(.)]) 

"nnt"  Number needed to treat  1 / rd 
The log(.)
versions are defined by taking the log()
(natural log) of the
corresponding effect measure.
Value
A clarify_ame
object, which inherits from clarify_est
and is
similar to the output of sim_apply()
, with the additional attributes
"var"
containing the variable values specified in var
and "by"
containing the
names of the variables specified in by
(if any). The average adjusted
predictions will be named E[Y({v})]
, where {v}
is replaced with the
values the variables named in var
take on. The average marginal effect for a
continuous var
will be named E[dY/d({x})]
where {x}
is replaced with
var
. When by
is specified, the average adjusted predictions will be named
E[Y({v}){b}]
and the average marginal effect E[dY/d({x}){b}]
where
{b}
is a commaseparated list of of values of the by
variables at which
the quantity is computed. See examples.
See Also
sim_apply()
, which provides a general interface to computing any
quantities for simulationbased inference; plot.clarify_est()
for plotting the
output of a call to sim_ame()
; summary.clarify_est()
for computing
pvalues and confidence intervals for the estimated quantities.
marginaleffects::avg_predictions()
, marginaleffects::avg_comparisons()
and marginaleffects::avg_slopes()
for delta methodbased implementations of computing average marginal effects.
Examples
data("lalonde", package = "MatchIt")
# Fit the model
fit < glm(I(re78 > 0) ~ treat + age + race +
married + re74,
data = lalonde, family = binomial)
# Simulate coefficients
set.seed(123)
s < sim(fit, n = 100)
# Average marginal effect of `age`
est < sim_ame(s, var = "age", verbose = FALSE)
summary(est)
# Contrast between average adjusted predictions
# for `treat`
est < sim_ame(s, var = "treat", contrast = "rr",
verbose = FALSE)
summary(est)
# Average adjusted predictions for `race`; need to follow up
# with contrasts for specific levels
est < sim_ame(s, var = "race", verbose = FALSE)
est < transform(est,
`RR(h,b)` = `E[Y(hispan)]` / `E[Y(black)]`)
summary(est)
# Average adjusted predictions for `treat` within levels of
# `married`, first using `subset` and then using `by`
est0 < sim_ame(s, var = "treat", subset = married == 0,
contrast = "rd", verbose = FALSE)
names(est0) < paste0(names(est0), "married=0")
est1 < sim_ame(s, var = "treat", subset = married == 1,
contrast = "rd", verbose = FALSE)
names(est1) < paste0(names(est1), "married=1")
summary(cbind(est0, est1))
est < sim_ame(s, var = "treat", by = ~married,
contrast = "rd", verbose = FALSE)
est
summary(est)
# Average marginal effect of `age` within levels of
# married*race
est < sim_ame(s, var = "age", by = ~married + race,
verbose = FALSE)
est
summary(est, null = 0)
# Comparing AMEs between married and unmarried for
# each level of `race`
est_diff < est[4:6]  est[1:3]
names(est_diff) < paste0("AME_diff", levels(lalonde$race))
summary(est_diff)
# Average adjusted predictions at a combination of `treat`
# and `married`
est < sim_ame(s, var = c("treat", "married"),
verbose = FALSE)
est
# Average marginal effect of `age` setting `married` to 1
est < sim_ame(s, var = list("age", married = 1),
verbose = FALSE)