`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,
contrast = NULL,
outcome = NULL,
type = NULL,
eps = 1e-05,
verbose = TRUE,
cl = NULL
)
# S3 method for clarify_ame
print(x, digits = NULL, max.ests = 6, ...)
```

## Arguments

- sim
a

`clarify_sim`

object; the output of a call to`sim()`

or`misim()`

.- var
either the name of a variable for which marginal effects are to be computed or a named list of length one containing the values the variable should take. If a list is supplied or the named variables is categorical (factor, character, or having two values), categorical calculations will be triggered. Otherwise, continuous calculations will be triggered. 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

`subset()`

, so nonstandard evaluation is allowed.- contrast
a string containing the name of a contrast between the average marginal means when the variable named in

`var`

is categorical and takes on two values. Allowed options include`"diff"`

for the difference in means (also`"rd"`

),`"rr"`

for the risk ratio (also`"irr"`

),`"log(rr):`

for the log risk ratio (also`"log(irr)"`

),`"or"`

for the odds ratio,`"log(or)"`

for the log odds ratio, and`"nnt"`

for the number needed to treat. These options are not case sensitive, but the parentheses must be included if present.- outcome
a string containing the name of the outcome or outcome level for multivariate (multiple outcomes) or multi-category 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

`marginaleffects::get_predict()`

and eventually to`predict()`

in most cases. The default and allowable option depend on the type of model supplied, but almost always corresponds to the response scale (e.g., predicted probabilities for binomial models).- eps
when the variable named in

`var`

is continuous, the value by which to change the variable values to approximate the derivative. See Details.- verbose
`logical`

; whether to display a text progress bar indicating progress and estimated time remaining for the procedure. Default is`TRUE`

.- cl
a cluster object created by

`parallel::makeCluster()`

, or an integer to indicate the number of child-processes (integer values are ignored on Windows) for parallel evaluations. See`pbapply::pblapply()`

for details. If`NULL`

, no parallelization will take place.- x
a

`clarify_ame`

object.- digits
the minimum number of significant digits to be used; passed to

`print.data.frame()`

.- max.ests
the maximum number of estimates to display.

- ...
optional arguments passed to

`FUN`

.

## Value

A `clarify_ame`

object, which inherits from `clarify_est`

and is similar to
the output of `sim_apply()`

, with the additional attribute `"var"`

containing
the variable named in `var`

. The average marginal means will be named
`E[Y({v})]`

, where `{v}`

is replaced with the values the focal variable
(`var`

) takes on. The average marginal effect for a continuous `var`

will be
named `dY/d({x})`

where `{x}`

is replaced with `var`

.

## Details

`sim_ame()`

operates differently depending on whether continuous or categorical calculations are triggered. To trigger categorical calculations, `var`

should be a string naming a factor, character, or binary variable or a named list with specific values given (e.g., `var = list(x1 = c(1, 2 ,3))`

). Otherwise, continuous calculations are triggered.

Categorical calculations involve computing average marginal means at each level of `var`

. The average marginal mean is the average predicted outcome value after setting all units' value of `var`

to one level. (This quantity has several names, including the average potential outcome, average adjusted prediction, and standardized mean). When `var`

only takes on two levels (or it is supplied as a list and only two values are specified), a contrast between the average marginal means can be computed by supplying an argument to `contrast`

. Contrasts can be manually computed using `transform()`

afterward as well.

Continuous calculations involve computing the average of marginal effects of `var`

across units. A marginal effect is the instantaneous rate of change corresponding to changing a unit's observed value of `var`

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 `var`

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.

If unit-level weights are included in the model fit (and discoverable using `insight::get_weights()`

), all means will be computed as weighted means.

### 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` | Formula |

`"diff"` | `E[Y(1)] - E[Y(0)]` |

`"rr"` | `E[Y(1)] / E[Y(0)]` |

`"or"` | `O[Y(1)] / O[Y(0)]` , where `O[Y(.)]` = `E[Y(.)] / (1 - E[Y(.)])` |

`"nnt"` | `1 / (E[Y(1)] - E[Y(0)])` |

The `log(.)`

versions are defined by taking the `log()`

(natural log) of the corresponding effect measure.

## See also

`sim_apply()`

, which provides a general interface to computing any
quantities for simulation-based inference; `plot.clarify_est()`

for plotting the
output of a call to `sim_ame()`

; `summary.clarify_est()`

for computing
p-values and confidence intervals for the estimated quantities.

`marginaleffects::marginaleffects()`

, `marginaleffects::comparisons()`

, and `margins::margins()`

for delta method-based implementations of computing average marginal effects.

## Examples

```
data("lalonde", package = "MatchIt")
# Fit the model
fit <- glm(I(re78 > 0) ~ treat + age + race + 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)
#> Estimate 2.5 % 97.5 %
#> dY/d(age) -0.00678 -0.00981 -0.00403
# Contrast between average marginal means for `treat`
est <- sim_ame(s, var = "treat", contrast = "rr",
verbose = FALSE)
summary(est)
#> Estimate 2.5 % 97.5 %
#> E[Y(0)] 0.744 0.698 0.784
#> E[Y(1)] 0.809 0.758 0.851
#> RR 1.088 0.987 1.198
# Average marginal means 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)
#> Estimate 2.5 % 97.5 %
#> E[Y(black)] 0.704 0.637 0.764
#> E[Y(hispan)] 0.832 0.734 0.899
#> E[Y(white)] 0.800 0.753 0.843
#> RR(h,b) 1.181 1.026 1.360
```