LightSHAP

Package
CI/CD
Quality
Meta

Lightweight Python implementation of SHAP (SHapley Additive exPlanations).

📖 Documentation | 🚀 Examples | 📋 API Reference

Key Features

• Tree Models: TreeSHAP wrappers for XGBoost, LightGBM, and CatBoost via explain_tree()
• Model-Agnostic: Permutation SHAP and Kernel SHAP via explain_any()
• Visualization: Flexible plots

Highlights of the agnostic explainer:

1. Exact and sampling versions of permutation SHAP and Kernel SHAP
2. Sampling versions iterate until convergence, and provide standard errors
3. Parallel processing via joblib
4. Supports multi-output models
5. Supports case weights
6. Accepts numpy, pandas, and polars input, and categorical features

Some methods of the explanation object:

• plot.bar(): Feature importance bar plot
• plot.beeswarm(): Summary beeswarm plot
• plot.scatter(): Dependence plots
• plot.waterfall(): Waterfall plot for individual explanations
• importance(): Returns feature importance values
• set_X(): Update explanation data, e.g., to replace a numpy array with a DataFrame
• set_feature_names(): Set or update feature names
• select_output(): Select a specific output for multi-output models
• filter(): Subset explanations by condition or indices
• ...

Usage

from lightshap import explain_any, explain_tree

# For any model
explanation = explain_any(model.predict, X)

# For tree models (XGBoost, LightGBM, CatBoost)
explanation = explain_tree(model, X)
# explanation.set_X(df)  # Optional: replace array with DataFrame for better plots

# Create plots
explanation.plot.bar()       # Feature importance
explanation.plot.beeswarm()  # Summary plot
explanation.plot.scatter()   # Dependence plots
explanation.plot.waterfall() # Individual explanation

Gallery

Installation

# From PyPI
pip install lightshap

# With all optional dependencies
pip install lightshap[all]

# From GitHub
pip install git+https://github.com/mayer79/LightSHAP.git

Contributions are highly appreciated! When contributing, you agree that your contributions will be subject to the MIT License.

Please feel free to open an issue for bug reports, feature requests, or general discussions.

License

MIT License - see LICENSE file for details.

Acknowledgements

LightSHAP builds on top of wonderful packages like numpy, pandas, and matplotlib.

It is heavily influenced by these projects:

shap | shapley-regression | kernelshap | shapviz

References

"A Unified Approach to Interpreting Model Predictions" (S. M. Lundberg and S.-I. Lee 2017)

@incollection{lundberglee2017,
 title = {A Unified Approach to Interpreting Model Predictions},
 author = {Lundberg, Scott M and Lee, Su-In},
 booktitle = {Advances in Neural Information Processing Systems 30},
 editor = {I. Guyon and U. V. Luxburg and S. Bengio and H. Wallach and R. Fergus and S. Vishwanathan and R. Garnett},
 pages = {4765--4774},
 year = {2017},
 publisher = {Curran Associates, Inc.},
 url = {https://papers.nips.cc/paper/7062-a-unified-approach-to-interpreting-model-predictions.pdf}
}

Paper link

"Improving KernelSHAP: Practical Shapley Value Estimation via Linear Regression" (I. Covert and S.-I. Lee 2020)

@inproceedings{covertlee2020,
  title={Improving KernelSHAP: Practical Shapley Value Estimation via Linear Regression},
  author={Ian Covert and Su-In Lee},
  booktitle={International Conference on Artificial Intelligence and Statistics},
  year={2020},
  url={https://proceedings.mlr.press/v130/covert21a/covert21a.pdf}
}

Paper link