Permutation SHAP algorithm with respect to a background dataset, see Strumbelj and Kononenko (2014) for the basic idea.
By default, for up to p=8 features, exact SHAP values are returned (exact with respect to the selected background data). Otherwise, the sampling process iterates until the resulting values are sufficiently precise, and standard errors are provided.
permshap(object, ...)
# Default S3 method
permshap(
object,
X,
bg_X = NULL,
pred_fun = stats::predict,
feature_names = colnames(X),
bg_w = NULL,
bg_n = 200L,
exact = length(feature_names) <= 8L,
low_memory = length(feature_names) > 15L,
tol = 0.01,
max_iter = 10L * length(feature_names),
parallel = FALSE,
parallel_args = NULL,
verbose = TRUE,
seed = NULL,
...
)
# S3 method for class 'ranger'
permshap(
object,
X,
bg_X = NULL,
pred_fun = NULL,
feature_names = colnames(X),
bg_w = NULL,
bg_n = 200L,
exact = length(feature_names) <= 8L,
low_memory = length(feature_names) > 15L,
tol = 0.01,
max_iter = 10L * length(feature_names),
parallel = FALSE,
parallel_args = NULL,
verbose = TRUE,
seed = NULL,
survival = c("chf", "prob"),
...
)Fitted model object.
Additional arguments passed to pred_fun(object, X, ...).
\((n \times p)\) matrix or data.frame with rows to be explained.
The columns should only represent model features, not the response
(but see feature_names on how to overrule this).
Background data used to integrate out "switched off" features,
often a subset of the training data (typically 50 to 500 rows).
In cases with a natural "off" value (like MNIST digits),
this can also be a single row with all values set to the off value.
If no bg_X is passed (the default) and if X is sufficiently large,
a random sample of bg_n rows from X serves as background data.
Prediction function of the form function(object, X, ...),
providing \(K \ge 1\) predictions per row. Its first argument
represents the model object, its second argument a data structure like X.
Additional (named) arguments are passed via ....
The default, stats::predict(), will work in most cases.
Optional vector of column names in X used to calculate
SHAP values. By default, this equals colnames(X).
Optional vector of case weights for each row of bg_X.
If bg_X = NULL, must be of same length as X. Set to NULL for no weights.
If bg_X = NULL: Size of background data to be sampled from X.
If TRUE, the algorithm will produce exact SHAP values
with respect to the background data.
The default is TRUE for up to eight features, and FALSE otherwise.
If FALSE (default up to p = 15), the algorithm does p
iterations in one chunk, evaluating Shapley's formula 2p^2 times.
For models with interactions up to order two, you can set this to TRUE
to save time.
Tolerance determining when to stop. As in CL21, the algorithm keeps
iterating until \(\textrm{max}(\sigma_n)/(\textrm{max}(\beta_n) - \textrm{min}(\beta_n)) < \textrm{tol}\),
where the \(\beta_n\) are the SHAP values of a given observation,
and \(\sigma_n\) their standard errors.
For multidimensional predictions, the criterion must be satisfied for each
dimension separately. The stopping criterion uses the fact that standard errors
and SHAP values are all on the same scale. Ignored if exact = TRUE.
For permshap(), the default is 0.01, while for kernelshap() it is set to 0.005.
If the stopping criterion (see tol) is not reached after
max_iter iterations, the algorithm stops. Ignored if exact = TRUE.
If TRUE, use foreach::foreach() and %dofuture% to loop over rows
to be explained. Must register backend beforehand, e.g., plan(multisession),
see README for an example. Currently disables the progress bar.
Named list of arguments passed to
foreach::foreach(.options.future = ...), ideally NULL (default).
Only relevant if parallel = TRUE.
Example on Windows: if object is a GAM fitted with package 'mgcv',
then one might need to set parallel_args = list(packages = "mgcv").
Similarly, if the model has been fitted with ranger(), then it might be necessary
to pass parallel_args = list(packages = "ranger").
Set to FALSE to suppress messages and the progress bar.
Optional integer random seed. Note that it changes the global seed.
Should cumulative hazards ("chf", default) or survival
probabilities ("prob") per time be predicted? Only in ranger() survival models.
An object of class "kernelshap" with the following components:
S: \((n \times p)\) matrix with SHAP values or, if the model output has
dimension \(K > 1\), a list of \(K\) such matrices.
X: Same as input argument X.
baseline: Vector of length K representing the average prediction on the
background data.
bg_X: The background data.
bg_w: The background case weights.
m_exact: Number of on-off vectors evaluated once per row of X.
exact: Logical flag indicating whether calculations are exact or not.
txt: Summary text.
predictions: \((n \times K)\) matrix with predictions of X.
algorithm: "permshap".
m: Number of sampled on-off vectors evaluated per iteration (if not exact).
SE: Standard errors corresponding to S (if not exact).
n_iter: Integer vector of length n providing the number of iterations
per row of X (if not exact).
converged: Logical vector of length n indicating convergence per row of X
(if not exact).
During each iteration, the algorithm cycles twice through a random permutation: It starts with all feature components "turned on" (i.e., taking them from the observation to be explained), then gradually turning off components according to the permutation. When all components are turned off, the algorithm - one by one - turns the components back on, until all components are turned on again. This antithetic scheme allows to evaluate Shapley's formula twice per feature using a single permutation and a total of 2p disjoint evaluations of the contribution function.
For models with interactions up to order two, one can show that even a single iteration provides exact SHAP values for all features (with respect to the given background dataset).
The Python implementation "shap" uses a similar approach, but without providing standard errors, and without early stopping.
For faster convergence, we use balanced permutations in the sense that
p subsequent permutations each start with a different feature.
Furthermore, the 2p on-off vectors with sum <=1 or >=p-1 are evaluated only once,
similar to the degree 1 hybrid in kernelshap().
permshap(default): Default permutation SHAP method.
permshap(ranger): Permutation SHAP method for "ranger" models, see Readme for an example.
Erik Strumbelj and Igor Kononenko. Explaining prediction models and individual predictions with feature contributions. Knowledge and Information Systems 41, 2014.
# MODEL ONE: Linear regression
fit <- lm(Sepal.Length ~ ., data = iris)
# Select rows to explain (only feature columns)
X_explain <- iris[-1]
# Calculate SHAP values
s <- permshap(fit, X_explain)
#> Exact permutation SHAP
#>
|
| | 0%
|
| | 1%
|
|= | 1%
|
|= | 2%
|
|== | 3%
|
|=== | 4%
|
|=== | 5%
|
|==== | 5%
|
|==== | 6%
|
|===== | 7%
|
|====== | 8%
|
|====== | 9%
|
|======= | 9%
|
|======= | 10%
|
|======= | 11%
|
|======== | 11%
|
|======== | 12%
|
|========= | 13%
|
|========== | 14%
|
|========== | 15%
|
|=========== | 15%
|
|=========== | 16%
|
|============ | 17%
|
|============= | 18%
|
|============= | 19%
|
|============== | 19%
|
|============== | 20%
|
|============== | 21%
|
|=============== | 21%
|
|=============== | 22%
|
|================ | 23%
|
|================= | 24%
|
|================= | 25%
|
|================== | 25%
|
|================== | 26%
|
|=================== | 27%
|
|==================== | 28%
|
|==================== | 29%
|
|===================== | 29%
|
|===================== | 30%
|
|===================== | 31%
|
|====================== | 31%
|
|====================== | 32%
|
|======================= | 33%
|
|======================== | 34%
|
|======================== | 35%
|
|========================= | 35%
|
|========================= | 36%
|
|========================== | 37%
|
|=========================== | 38%
|
|=========================== | 39%
|
|============================ | 39%
|
|============================ | 40%
|
|============================ | 41%
|
|============================= | 41%
|
|============================= | 42%
|
|============================== | 43%
|
|=============================== | 44%
|
|=============================== | 45%
|
|================================ | 45%
|
|================================ | 46%
|
|================================= | 47%
|
|================================== | 48%
|
|================================== | 49%
|
|=================================== | 49%
|
|=================================== | 50%
|
|=================================== | 51%
|
|==================================== | 51%
|
|==================================== | 52%
|
|===================================== | 53%
|
|====================================== | 54%
|
|====================================== | 55%
|
|======================================= | 55%
|
|======================================= | 56%
|
|======================================== | 57%
|
|========================================= | 58%
|
|========================================= | 59%
|
|========================================== | 59%
|
|========================================== | 60%
|
|========================================== | 61%
|
|=========================================== | 61%
|
|=========================================== | 62%
|
|============================================ | 63%
|
|============================================= | 64%
|
|============================================= | 65%
|
|============================================== | 65%
|
|============================================== | 66%
|
|=============================================== | 67%
|
|================================================ | 68%
|
|================================================ | 69%
|
|================================================= | 69%
|
|================================================= | 70%
|
|================================================= | 71%
|
|================================================== | 71%
|
|================================================== | 72%
|
|=================================================== | 73%
|
|==================================================== | 74%
|
|==================================================== | 75%
|
|===================================================== | 75%
|
|===================================================== | 76%
|
|====================================================== | 77%
|
|======================================================= | 78%
|
|======================================================= | 79%
|
|======================================================== | 79%
|
|======================================================== | 80%
|
|======================================================== | 81%
|
|========================================================= | 81%
|
|========================================================= | 82%
|
|========================================================== | 83%
|
|=========================================================== | 84%
|
|=========================================================== | 85%
|
|============================================================ | 85%
|
|============================================================ | 86%
|
|============================================================= | 87%
|
|============================================================== | 88%
|
|============================================================== | 89%
|
|=============================================================== | 89%
|
|=============================================================== | 90%
|
|=============================================================== | 91%
|
|================================================================ | 91%
|
|================================================================ | 92%
|
|================================================================= | 93%
|
|================================================================== | 94%
|
|================================================================== | 95%
|
|=================================================================== | 95%
|
|=================================================================== | 96%
|
|==================================================================== | 97%
|
|===================================================================== | 98%
|
|===================================================================== | 99%
|
|======================================================================| 99%
|
|======================================================================| 100%
s
#> SHAP values of first observations:
#> Sepal.Width Petal.Length Petal.Width Species
#> [1,] 0.21951350 -1.955357 0.3149451 0.5823533
#> [2,] -0.02843097 -1.955357 0.3149451 0.5823533
# MODEL TWO: Multi-response linear regression
fit <- lm(as.matrix(iris[, 1:2]) ~ Petal.Length + Petal.Width + Species, data = iris)
s <- permshap(fit, iris[3:5])
#> Exact permutation SHAP
#>
|
| | 0%
|
| | 1%
|
|= | 1%
|
|= | 2%
|
|== | 3%
|
|=== | 4%
|
|=== | 5%
|
|==== | 5%
|
|==== | 6%
|
|===== | 7%
|
|====== | 8%
|
|====== | 9%
|
|======= | 9%
|
|======= | 10%
|
|======= | 11%
|
|======== | 11%
|
|======== | 12%
|
|========= | 13%
|
|========== | 14%
|
|========== | 15%
|
|=========== | 15%
|
|=========== | 16%
|
|============ | 17%
|
|============= | 18%
|
|============= | 19%
|
|============== | 19%
|
|============== | 20%
|
|============== | 21%
|
|=============== | 21%
|
|=============== | 22%
|
|================ | 23%
|
|================= | 24%
|
|================= | 25%
|
|================== | 25%
|
|================== | 26%
|
|=================== | 27%
|
|==================== | 28%
|
|==================== | 29%
|
|===================== | 29%
|
|===================== | 30%
|
|===================== | 31%
|
|====================== | 31%
|
|====================== | 32%
|
|======================= | 33%
|
|======================== | 34%
|
|======================== | 35%
|
|========================= | 35%
|
|========================= | 36%
|
|========================== | 37%
|
|=========================== | 38%
|
|=========================== | 39%
|
|============================ | 39%
|
|============================ | 40%
|
|============================ | 41%
|
|============================= | 41%
|
|============================= | 42%
|
|============================== | 43%
|
|=============================== | 44%
|
|=============================== | 45%
|
|================================ | 45%
|
|================================ | 46%
|
|================================= | 47%
|
|================================== | 48%
|
|================================== | 49%
|
|=================================== | 49%
|
|=================================== | 50%
|
|=================================== | 51%
|
|==================================== | 51%
|
|==================================== | 52%
|
|===================================== | 53%
|
|====================================== | 54%
|
|====================================== | 55%
|
|======================================= | 55%
|
|======================================= | 56%
|
|======================================== | 57%
|
|========================================= | 58%
|
|========================================= | 59%
|
|========================================== | 59%
|
|========================================== | 60%
|
|========================================== | 61%
|
|=========================================== | 61%
|
|=========================================== | 62%
|
|============================================ | 63%
|
|============================================= | 64%
|
|============================================= | 65%
|
|============================================== | 65%
|
|============================================== | 66%
|
|=============================================== | 67%
|
|================================================ | 68%
|
|================================================ | 69%
|
|================================================= | 69%
|
|================================================= | 70%
|
|================================================= | 71%
|
|================================================== | 71%
|
|================================================== | 72%
|
|=================================================== | 73%
|
|==================================================== | 74%
|
|==================================================== | 75%
|
|===================================================== | 75%
|
|===================================================== | 76%
|
|====================================================== | 77%
|
|======================================================= | 78%
|
|======================================================= | 79%
|
|======================================================== | 79%
|
|======================================================== | 80%
|
|======================================================== | 81%
|
|========================================================= | 81%
|
|========================================================= | 82%
|
|========================================================== | 83%
|
|=========================================================== | 84%
|
|=========================================================== | 85%
|
|============================================================ | 85%
|
|============================================================ | 86%
|
|============================================================= | 87%
|
|============================================================== | 88%
|
|============================================================== | 89%
|
|=============================================================== | 89%
|
|=============================================================== | 90%
|
|=============================================================== | 91%
|
|================================================================ | 91%
|
|================================================================ | 92%
|
|================================================================= | 93%
|
|================================================================== | 94%
|
|================================================================== | 95%
|
|=================================================================== | 95%
|
|=================================================================== | 96%
|
|==================================================================== | 97%
|
|===================================================================== | 98%
|
|===================================================================== | 99%
|
|======================================================================| 99%
|
|======================================================================| 100%
s
#> SHAP values of first observations:
#> $Sepal.Length
#> Petal.Length Petal.Width Species
#> [1,] -2.13622 0.005991405 1.237003
#> [2,] -2.13622 0.005991405 1.237003
#>
#> $Sepal.Width
#> Petal.Length Petal.Width Species
#> [1,] -0.3647252 -0.62303 1.320153
#> [2,] -0.3647252 -0.62303 1.320153
#>
# Note 1: Feature columns can also be selected 'feature_names'
# Note 2: Especially when X is small, pass a sufficiently large background data bg_X
s <- permshap(
fit,
iris[1:4, ],
bg_X = iris,
feature_names = c("Petal.Length", "Petal.Width", "Species")
)
#> Exact permutation SHAP
#>
|
| | 0%
|
|================== | 25%
|
|=================================== | 50%
|
|==================================================== | 75%
|
|======================================================================| 100%
s
#> SHAP values of first observations:
#> $Sepal.Length
#> Petal.Length Petal.Width Species
#> [1,] -2.13622 0.005991405 1.237003
#> [2,] -2.13622 0.005991405 1.237003
#>
#> $Sepal.Width
#> Petal.Length Petal.Width Species
#> [1,] -0.3647252 -0.62303 1.320153
#> [2,] -0.3647252 -0.62303 1.320153
#>