Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

explain

Fast approximate Shapley values

Description

Compute fast (approximate) Shapley values for a set of features.

Usage

explain(object, ...)

## Default S3 method:
explain(
  object,
  feature_names = NULL,
  X = NULL,
  nsim = 1,
  pred_wrapper = NULL,
  newdata = NULL,
  adjust = FALSE,
  ...
)

## S3 method for class 'lm'
explain(
  object,
  feature_names = NULL,
  X,
  nsim = 1,
  pred_wrapper,
  newdata = NULL,
  exact = FALSE,
  ...
)

## S3 method for class 'xgb.Booster'
explain(
  object,
  feature_names = NULL,
  X = NULL,
  nsim = 1,
  pred_wrapper,
  newdata = NULL,
  exact = FALSE,
  ...
)

Arguments

object

A fitted model object (e.g., a ranger or an xgboost object).
...

Additional optional arguments to be passed on to laply.
feature_names

Character string giving the names of the predictor variables (i.e., features) of interest. If NULL (default) they will be taken from the column names of X.
X

A matrix-like R object (e.g., a data frame or matrix) containing ONLY the feature columns from the training data. NOTE: This argument is required whenever exact = FALSE.
nsim

The number of Monte Carlo repetitions to use for estimating each Shapley value (only used when exact = FALSE). Default is 1. NOTE: To obtain the most accurate results, nsim should be set as large as feasibly possible.
pred_wrapper

Prediction function that requires two arguments, object and newdata. NOTE: This argument is required whenever exact = FALSE. The output of this function should be determined according to:

Regression

A numeric vector of predicted outcomes.

Binary classification

A vector of predicted class probabilities for the reference class.

Multiclass classification

A vector of predicted class probabilities for the reference class.
newdata

A matrix-like R object (e.g., a data frame or matrix) containing ONLY the feature columns for the observation(s) of interest; that is, the observation(s) you want to compute explanations for. Default is NULL which will produce approximate Shapley values for all the rows in X (i.e., the training data).
adjust

Logical indicating whether or not to adjust the sum of the estimated Shapley values to satisfy the additivity (or local accuracy) property; that is, to equal the difference between the model's prediction for that sample and the average prediction over all the training data (i.e., X).
exact

Logical indicating whether to compute exact Shapley values. Currently only available for lm and xgboost objects. Default is FALSE. Note that setting exact = TRUE will return explanations for each of the terms in an lm object.

Value

A tibble with one column for each feature specified in feature_names (if feature_names = NULL, the default, there will be one column for each feature in X) and one row for each observation in newdata (if newdata = NULL, the default, there will be one row for each observation in X).

Note

Setting exact = TRUE with a linear model (i.e., an lm or glm object) assumes that the input features are independent. Also, setting adjust = TRUE is experimental and we follow the same approach as in shap.

See Also

You can find more examples (with larger and more realistic data sets) on the fastshap GitHub repository: https://github.com/bgreenwell/fastshap.

Examples

#
# A projection pursuit regression (PPR) example
#

# Load the sample data; see ?datasets::mtcars for details
data(mtcars)

# Fit a projection pursuit regression model
fit <- lm(mpg ~ ., data = mtcars)

# Compute approximate Shapley values using 10 Monte Carlo simulations
set.seed(101)  # for reproducibility
shap <- explain(fit, X = subset(mtcars, select = -mpg), nsim = 10, 
                pred_wrapper = predict)
shap

# Compute exact Shapley (i.e., LinearSHAP) values
shap <- explain(fit, exact = TRUE)
shap

# Shapley-based plots
library(ggplot2)
autoplot(shap)  # Shapley-based importance plot
autoplot(shap, type = "dependence", feature = "wt", X = mtcars)
autoplot(shap, type = "contribution", row_num = 1)  # explain first row of X
fastshap

Fast Approximate Shapley Values

v0.0.5
GPL (>= 2)
Authors
Brandon Greenwell [aut, cre] (<https://orcid.org/0000-0002-8120-0084>)
Initial release

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.