Skip to contents

Computes AMEs for every feature (or a subset of features) of a model.

Source: R/ame.R
ame.Rd

This is a wrapper function for AverageMarginalEffects$new(...)$compute(). It computes Average Marginal Effects (AME) based on Forward Marginal Effects (FME) for a model. The AME is a simple mean FME and computed w.r.t. a feature variable and a model.

Usage

ame(model, data, features = NULL, ep.method = "none")

Arguments

model

The (trained) model, with the ability to predict on new data. This must be a train.formula (tidymodels), Learner (mlr3), train (caret), lm or glm object.

data

The data used for computing AMEs, must be data.frame or data.table.

features

If not NULL, a named list of the names of the feature variables for which AMEs should be computed, together with the desired step sizes. For numeric features, the step size must be a single number. For categorial features, the step size must be a character vector of category names that is a subset of the levels of the factor variable.

ep.method

String specifying the method used for extrapolation detection. One of "none" or "envelope". Defaults to "none".

Value

An AverageMarginalEffects object, with a field results containing a list of summary statistics, including

  • Feature: The name of the feature.

  • step.size: The step.size w.r.t. the specified feature.

  • AME: The Average Marginal Effect for a step of length step.size w.r.t. the specified feature.

  • SD: The standard deviation of FMEs for the specified feature and step.size.

  • 0.25: The 0.25-quantile of FMEs for the specified feature and step.size.

  • 0.75: The 0.75-quantile of FMEs for the specified feature and step.size.

  • n: The number of observations included for the computation of the AME. This can vary for the following reasons: For categorical features, FMEs are only computed for observations where the original category is not the step.size category. For numerical features, FMEs are only computed for observations that are not extrapolation points (if ep.method is set to "envelope").

References

Scholbeck, C.A., Casalicchio, G., Molnar, C. et al. Marginal effects for non-linear prediction functions. Data Min Knowl Disc (2024). https://doi.org/10.1007/s10618-023-00993-x

Examples

# Train a model:

library(mlr3verse)
library(ranger)
data(bikes, package = "fmeffects")
set.seed(123)
task = as_task_regr(x = bikes, id = "bikes", target = "count")
forest = lrn("regr.ranger")$train(task)

# Compute AMEs for all features:
if (FALSE) { # \dontrun{
overview = ame(model = forest, data = bikes)
summary(overview)

# Compute AMEs for a subset of features with non-default step.sizes:
overview = ame(model = forest,
               data = bikes,
               features = list(humidity = 0.1, weather = c("clear", "rain")))
summary(overview)

# Extract results:
overview$results
} # }