fastshap - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #llm #android #linux #docker #nodejs #macos #awesome #cli #kubernetes #awesome-list #pytorch #mcp

fastshap

(★ 106)

An amortized approach for calculating local Shapley value explanations

File Explorer

Download Latest Version (.zip)

- __init__.py
- fastshap.py
- image_imputers.py
- image_surrogate.py
- surrogate.py
- tabular_imputers.py
- utils.py
- census.ipynb
- cifar single model.ipynb
- cifar.ipynb
- resnet.py
- unet.py
.gitattributes
.gitignore
LICENSE
README.md
setup.py

# Installation Guide

1. Get the code

git clone https://github.com/iancovert/fastshap

Downloads the entire project code from GitHub to your computer.

cd fastshap

Moves into the project folder you just downloaded.

2. Official Install Script

Easy Recommended

Prerequisites

Python 3 Python is required to use pip.

pip install .

Installs the package published on PyPI directly — no need to clone the source.

✅ After installing, open a new terminal and run the program's version command (e.g. --version) to confirm it worked.

Pulled directly from this repo's README.

3. Python

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Python 3 On Windows, be sure to check 'Add Python to PATH' during installation.

pip install .

Installs the package published on PyPI directly — no need to clone the source.

✅ If it runs without errors and prints output in the terminal, it worked.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# FastSHAP

FastSHAP is an amortized approach for calculating Shapley value estimates for many examples. It involves training an explainer model to output Shapley value estimates in a single forward pass, using an objective function inspired by KernelSHAP.

FastSHAP was introduced in [this](https://arxiv.org/abs/2107.07436) paper [1]. This repository provides a PyTorch implementation, and see [here](https://github.com/neiljethani/fastshap) for a similar TensorFlow implementation (also provided by the paper authors).

# Installation

The easiest way to get started is to clone this repository and install the package in your Python environment:

```bash
pip install .
```

# More details

We often want to explain how a model makes its predictions. Given a convention for removing subsets of features (e.g., marginalizing them out), one of the most popular ways of generating explanations is Shapley values. Shapley values essentially consider every possible subset of features, as well as the corresponding predictions when different features are made available to the model, and they summarize the contribution that each feature makes to the prediction. (See this [blog post](https://iancovert.com/blog/understanding-shap-sage/) for an introduction to Shapley values.)

The challenge with Shapley values is that they are computationally costly to calculate. Several approximations exist, such as KernelSHAP for the model-agnostic case and TreeSHAP for the case of tree-based models. FastSHAP provides a different kind of approximation: rather than running an algorithm separately for each example to be explained, FastSHAP trains a model (a neural network) to output Shapley value estimates in a single forward pass.

To run FastSHAP, you need the following ingredients:

1. **A predictive model to explain.** The original model can be anything, including a simple model for tabular data (e.g., XGBoost) or a large CNN for image data (e.g., ResNet).
2. **A convention for holding out features.** Shapley values require holding out different groups of features to observe how the predictions change (see [2] for a discussion of many approaches). Our experiments typically use a surrogate model trained to replicate the original model's predictions; this approach was introduced by [3] and is also discussed in [2, 4]. An alternative approach is to train a model that directly accommodates missing features (discussed in [2] and demonstrated in [this](https://github.com/iancovert/fastshap/blob/main/notebooks/cifar%20single%20model.ipynb) notebook).
3. **An explainer model architecture.** The explanations are generated by a model (a neural network) rather than a Monte Carlo estimation algorithm (e.g., KernelSHAP), so an appropriate architecture must be chosen. The explainer should generally be a MLP for tabular data and a CNN for image data, and the output must be the same size as the input. Our experiments use an explainer that outputs explanations for all classes simultaneously, but the class variable can alternatively be provided as a model input.

For more details about the method, see the [paper](https://arxiv.org/abs/2107.07436) [1].

# Examples

For usage examples, see the following notebooks:

- [Census](https://github.com/iancovert/fastshap/blob/main/notebooks/census.ipynb): this notebook shows how to train FastSHAP using the census income (or adult) dataset, a common tabular dataset. The original model is LGBM, and explanations are generated by first training a surrogate model (MLP), and then training a FastSHAP explainer model (MLP).
- [CIFAR-10](https://github.com/iancovert/fastshap/blob/main/notebooks/cifar.ipynb): this notebook shows how to train FastSHAP for image models using CIFAR-10. The original model are the surrogate are both ResNet18's, and the FastSHAP explainer model is a UNet (because its outputs must be image-sized). Similarly, [this notebook](https://github.com/iancovert/fastshap/blob/main/notebooks/cifar%20single%20model.ipynb) shows how to train FastSHAP using a single model trained to accommodate missing features.

# Authors

- Neil Jethani (<nj594@nyu.edu>)
- Mukund Sudarshan (<ms7490@nyu.edu>)
- Ian Covert (<icovert@cs.washington.edu>)
- Su-In Lee
- Rajesh Ranganath

# References

[1] Neil Jethani\*, Mukund Sudarshan\*, Ian Covert\*, Su-In Lee, Rajesh Ranganath. "FastSHAP: Real-Time Shapley Value Estimation."

[2] Ian Covert, Scott Lundberg, Su-In Lee. "Explaining by Removing: A Unified Framework For Model Explanation." *arXiv preprint:2011.14878*

[3] Christopher Frye, Damien de Mijolla, Tom Begley, Laurence Cowton, Megan Stanley, Ilya Feige. "Shapley Explainability on the Data Manifold." ICLR 2021

[4] Neil Jethani, Mukund Sudarshan, Yindalon Aphinyanaphongs, Rajesh Ranganath. "Have We Learned to Explain?: How Interpretability Methods Can Learn to Encode Predictions in their Interpretations." AISTATS 2021