Skip to contents

Computes FMEs.

Source: R/FME.R
fme.Rd

This is a wrapper function for FME$new(...)$compute(). It computes forward marginal effects (FMEs) for a specified change in feature values.

Usage

fme(
  model,
  data,
  features,
  ep.method = "none",
  compute.nlm = FALSE,
  nlm.intervals = 1
)

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 FMEs, must be data.frame or data.table.

features

A named list with the feature name(s) and step size(s). The list names should correspond to the names of the feature variables affected by the step. The list must exclusively contain either numeric or categorical features, but not a combination of both. Numeric features must have a number as step size, categorical features the name of the reference category.

ep.method

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

compute.nlm

Compute NLMs for FMEs for numerical steps. Defaults to FALSE.

nlm.intervals

Number of intervals for computing NLMs. Results in longer computing time but more accurate approximation of NLMs. Defaults to 1.

Value

ForwardsMarginalEffect object with the following fields:

  • ame average marginal effect (AME).

  • anlm average non-linearity measure (NLM).

  • extrapolation.ids observations that have been identified as extrapolation points and not included in the analysis.

  • data.step, a data.table of the feature matrix after the step has been applied.

  • results, a data.table of the individual FMEs (and NLMs, if applicable) for all observations that are not extrapolation points.

Details

If one or more numeric features are passed to the features argument, FMEs are computed as $$FME_{x, h_{S}} = f(x + h_{S}, x_{-S}) - f(x)$$ where \(h_{S}\) is the step size vector and \(x_{-S}\) the other features. If one or more categorical features are passed to features, $$FME_{x, c_{J}} = f(c_{J}, x_{-J}) - f(x)$$ where \(c_{J}\) is the set of selected reference categories in features and \(x_{-J}\) the other features.

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")
forest = lrn("regr.ranger")$train(as_task_regr(x = bikes, target = "count"))

# Compute FMEs for a numerical feature:
effects = fme(model = forest, data = bikes, features = list("temp" = 1), ep.method = "envelope")

# Analyze results:
summary(effects)
#> 
#> Forward Marginal Effects Object
#> 
#> Step type:
#>   numerical
#> 
#> Features & step lengths:
#>   temp, 1
#> 
#> Extrapolation point detection:
#>   envelope, EPs: 3 of 731 obs. (0 %)
#> 
#> Average Marginal Effect (AME):
#>   56.4042
plot(effects)
#> `geom_smooth()` using method = 'loess' and formula = 'y ~ x'


# Extract results:
effects$results
#> Key: <obs.id>
#>      obs.id          fme
#>       <int>        <num>
#>   1:      1 158.72019394
#>   2:      2 253.46725238
#>   3:      3  58.70801567
#>   4:      4  87.22350480
#>   5:      5 218.24698054
#>  ---                    
#> 724:    727 304.61168137
#> 725:    728 222.42089939
#> 726:    729 383.51970424
#> 727:    730 434.09039495
#> 728:    731  -0.09944615

# Compute the AME for a categorial feature:
fme(model = forest, data = bikes, features = list("weather" = "rain"))$ame
#> [1] -786.9927