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

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:
overview = ame(model = forest, data = bikes)
summary(overview)
#> 
#> Model Summary Using Average Marginal Effects:
#> 
#>       Feature step.size       AME      SD      0.25      0.75   n
#> 1      season    spring   -29.472 31.5101   -39.955   -5.5139 548
#> 2      season    summer    0.4772 22.5212   -9.0235   11.6321 543
#> 3      season      fall   11.7452 28.5851   -2.4282   34.1763 539
#> 4      season    winter   15.5793 24.6394    1.6525   26.2254 551
#> 5        year         0   -99.038 67.1788 -157.0608  -20.0628 364
#> 6        year         1   97.0566  60.521   21.9401  148.0847 363
#> 7       month         1    4.0814 13.3513   -1.2566     7.459 727
#> 8     holiday     False   -1.2178 21.6103   -9.1095    9.8232  21
#> 9     holiday      True   -13.738 25.3496  -32.6323    6.2019 706
#> 10    weekday       Sat  -55.0908 49.6534  -87.6489  -15.8843 622
#> 11    weekday       Sun  -85.1527 57.7791 -122.1504  -31.8105 622
#> 12    weekday       Mon   10.7224 29.2179   -8.4101   30.4207 623
#> 13    weekday       Tue   17.9396  25.728    1.1959   32.5073 625
#> 14    weekday       Wed   20.4025 23.1599    1.3386   32.8358 623
#> 15    weekday       Thu   19.4455 24.1105   -0.3097   33.4997 624
#> 16    weekday       Fri    1.7712 35.3088  -24.8956   29.5147 623
#> 17 workingday     False -204.1875 89.3882  -257.144 -142.4332 496
#> 18 workingday      True  161.0619 62.5733  118.9398  209.6916 231
#> 19    weather     clear   26.1983 41.7886    3.5991   25.9257 284
#> 20    weather     misty     3.023 32.8661   -9.1498     0.973 513
#> 21    weather      rain  -55.3083 53.0127  -94.4096    -5.481 657
#> 22       temp         1    2.3426  7.1269   -0.4294    4.5534 727
#> 23   humidity      0.01   -0.2749   2.626   -0.3249    0.3504 727
#> 24  windspeed         1    0.0052  2.4318   -0.1823    0.2318 727

# 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)
#> 
#> Model Summary Using Average Marginal Effects:
#> 
#>    Feature step.size      AME       SD      0.25     0.75   n
#> 1  weather     clear 26.19828 41.78861   3.59911 25.92567 284
#> 2  weather      rain -55.3083 53.01272 -94.40958 -5.48097 657
#> 3 humidity       0.1 -7.38328 16.35698   -8.5513  1.07549 727

# Extract results:
overview$results
#>    Feature step.size      AME       SD      0.25     0.75   n
#> 1  weather     clear 26.19828 41.78861   3.59911 25.92567 284
#> 2  weather      rain -55.3083 53.01272 -94.40958 -5.48097 657
#> 3 humidity       0.1 -7.38328 16.35698   -8.5513  1.07549 727