This repository provides a linear regression-based estimator for the Shapley values of any cooperative game. The methods implemented here are described in this paper. Although the code can be used for arbitrary cooperative games, our focus is model explanation methods such SHAP, SAGE, and Shapley Effects.
Shapley values are already supported by several other repositories, so the goal of this package is to provide a fast linear regression-based estimator with the following features:
-
Convergence detection. The estimator will stop automatically when it is approximately converged, so you don't need to specify the number of samples.
-
Convergence forecasting. For use cases that take a long time to run, the estimator will forecast the amount of time required to reach convergence (displayed with a progress bar).
-
Uncertainty estimates. Shapley values are often estimated rather than calculated exactly, and our method provides confidence intervals for the results.
To install the code, please clone this repository and install the module into your Python environment:
pip install .Next, to run the code you only need to do two things: (i) specify a cooperative game, and (ii) run the Shapley value estimator. For example, you can calculate SHAP values as follows:
from shapreg import removal, games, shapley
# Get data
x, y = ...
feature_names = ...
# Get model (callable)
model = ...
# Set up cooperative game (SHAP)
extension = removal.MarginalExtension(x[:128], model)
instance = x[0]
game = games.PredictionGame(extension, instance)
# Estimate Shapley values
values = shapley.ShapleyRegression(game)
values.plot(feature_names)For usage examples, see the following notebooks:
- Census shows how to explain individual predictions (SHAP)
- Credit shows how to explain the model's loss (SAGE)
- Bank shows how to explain the model's global sensitivity (Shapley Effects)
- Ian Covert (icovert@cs.washington.edu)
- Su-In Lee
Ian Covert and Su-In Lee. "Improving KernelSHAP: Practical Shapley Value Estimation via Linear Regression." arxiv preprint:2012.01536