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 setting x1 to 0 and to 1
list(x2 = NULL), list("x2"), "x2" -- the average marginal effect of x2
list(x2 = c(5, 10)) -- the average adjusted predictions setting x2 to 5 and to 10
list(x1 = 0:1, x2 = c(5, 10)), list("x1", x2 = c(5, 10)) -- the average adjusted predictions setting x1 and x2 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 of x2 setting x1 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.