SHAP Feature Importance and Dependence Plots

Computes approximate SHAP (SHapley Additive exPlanations) values using a built-in permutation algorithm and returns either a feature importance chart (signed mean SHAP per feature - purple = increases prediction, blue = decreases prediction, sorted by magnitude) or a dependence plot (mean SHAP per bin alongside exposure bars). Both plots use the same dual-axis Plotly style as one_way() and pdp().

Usage

shap(data, ...)

# Default S3 method
shap(
  data,
  model,
  vars,
  exposure = "exposure",
  type = c("importance", "dependence"),
  nsim = 50L,
  sample_size = 500L,
  bins = 10L,
  type_agg = c("equal_exposure", "equal_range"),
  ret = c("plot", "data"),
  model_name = "model",
  pre_process_fun = function(df) df,
  feat_eng_fun = function(df) df,
  post_process_fun = function(preds, df_raw) preds,
  seed = 2024L,
  ...
)

Arguments

data: A data.frame or data.table. Must contain the columns named in vars and, optionally, exposure.
...: Unused.
model: A fitted model object.
vars: [character] Feature column names for which SHAP values are computed.
exposure: [character(1)] Exposure weight column. If the column is absent, every row is given weight 1. Default "exposure". Used only in the dependence plot (exposure bars and weighted mean SHAP line).
type: [character(1)] Plot type: "importance" (default) returns a signed horizontal bar chart of mean SHAP per feature (purple = positive effect, blue = negative effect, sorted by |SHAP| magnitude); "dependence" returns a dual-axis chart (exposure bars + mean SHAP per bin) for each variable in vars.
nsim: [integer(1)] Number of random permutations per observation. Higher values give more stable SHAP estimates at the cost of compute time. Default 50L.
sample_size: [integer(1)] Rows sampled from data for SHAP computation. Default 500L. Seeded at 2024 for reproducibility.
bins: [integer(1)] Number of bins for the dependence plot x-axis. Default 10L.
type_agg: [character(1)] Binning strategy for the dependence plot: "equal_exposure" (default) or "equal_range".
ret: [character(1)] "plot" (default) or "data". "data" returns a data.table with one SHAP column per feature in vars.
model_name: [character(1)] Label shown in plot titles. Default "model".
pre_process_fun: function(df) -> df applied before feat_eng_fun. Default is the identity function.
feat_eng_fun: function(df) -> df (or matrix) that produces the model input. Default is the identity function.
post_process_fun: function(preds, df_raw) -> numeric applied to raw model predictions. Default is the identity function.
seed: [integer(1)] Seed for the row sample and the internal SHAP permutations, applied via withr::with_seed() so the global RNG stream is left undisturbed and results are reproducible. Default 2024L.

Value

A plotly object, a data.table (when ret = "data"), or a named list of plotly objects when type = "dependence" and vars has more than one element.

Details

The algorithm is model-agnostic: it works with any model that has a predict() method, including GLMs, XGBoost, randomForest, and H2O models. No external packages beyond the modelblueprint dependencies are required.

Examples

# \donttest{
m <- lm(mpg ~ wt + hp + cyl + am, data = mtcars)

# Feature importance (mean |SHAP|)
shap(mtcars, model = m, vars = c("wt", "hp", "cyl", "am"),
     type = "importance", nsim = 10L, sample_size = 32L)
#> ℹ Computing SHAP values: 4 feature(s), 32 row(s), 10 permutation(s) each.


# Dependence plot for one feature
shap(mtcars, model = m, vars = "wt",
     type = "dependence", nsim = 10L, sample_size = 32L)
#> ℹ Computing SHAP values: 1 feature(s), 32 row(s), 10 permutation(s) each.

# }