This is a wrapper function for `FME$new(...)$compute()`

.
It computes forward marginal effects (FMEs) for a specified change in feature values.

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