# shapiq: Shapley Interactions for Machine Learning <img src="https://raw.githubusercontent.com/mmschlk/shapiq/main/docs/source/_static/logo_shapiq_light.svg" alt="shapiq_logo" align="right" height="250px"/>
[](https://opensource.org/licenses/MIT)
[](https://coveralls.io/github/mmschlk/shapiq?branch=main)
[](https://github.com/mmschlk/shapiq/actions/workflows/unit-tests.yml)
[](https://shapiq.readthedocs.io/en/latest/?badge=latest)
[](https://pypi.org/project/shapiq)
[](https://pypi.org/project/shapiq)
[](https://pepy.tech/project/shapiq)
[](https://github.com/psf/black)
> An interaction may speak more than a thousand main effects.
Shapley Interaction Quantification (`shapiq`) is a Python package for (1) approximating any-order Shapley interactions, (2) benchmarking game-theoretical algorithms for machine learning, (3) explaining feature interactions of model predictions. `shapiq` extends the well-known [shap](https://github.com/shap/shap) package for both researchers working on game theory in machine learning, as well as the end-users explaining models. SHAP-IQ extends individual Shapley values by quantifying the **synergy** effect between entities (aka **players** in the jargon of game theory) like explanatory features, data points, or weak learners in ensemble models. Synergies between players give a more comprehensive view of machine learning models.
## 🛠️ Install
`shapiq` is intended to work with **Python 3.9 and above**. Installation can be done via `pip`:
```sh
pip install shapiq
```
## ⭐ Quickstart
You can explain your model with `shapiq.explainer` and visualize Shapley interactions with `shapiq.plot`.
If you are interested in the underlying game theoretic algorithms, then check out the `shapiq.approximator` and `shapiq.games` modules.
### 📈 Compute any-order feature interactions
Explain your models with Shapley interaction values like the k-SII values:
```python
import shapiq
# load data
X, y = shapiq.load_california_housing(to_numpy=True)
# train a model
from sklearn.ensemble import RandomForestRegressor
model = RandomForestRegressor()
model.fit(X, y)
# set up an explainer with k-SII interaction values up to order 4
explainer = shapiq.TabularExplainer(
model=model,
data=X,
index="k-SII",
max_order=4
)
# explain the model's prediction for the first sample
interaction_values = explainer.explain(X[0], budget=256)
# analyse interaction values
print(interaction_values)
>> InteractionValues(
>> index=k-SII, max_order=4, min_order=0, estimated=False,
>> estimation_budget=256, n_players=8, baseline_value=2.07282292,
>> Top 10 interactions:
>> (0,): 1.696969079 # attribution of feature 0
>> (0, 5): 0.4847876
>> (0, 1): 0.4494288 # interaction between features 0 & 1
>> (0, 6): 0.4477677
>> (1, 5): 0.3750034
>> (4, 5): 0.3468325
>> (0, 3, 6): -0.320 # interaction between features 0 & 3 & 6
>> (2, 3, 6): -0.329
>> (0, 1, 5): -0.363
>> (6,): -0.56358890
>> )
```
### 📊 Visualize feature interactions
A handy way of visualizing interaction scores up to order 2 are network plots.
You can see an example of such a plot below.
The nodes represent feature **attributions** and the edges represent the **interactions** between features.
The strength and size of the nodes and edges are proportional to the absolute value of attributions and interactions, respectively.
```python
shapiq.network_plot(
first_order_values=interaction_values.get_n_order_values(1),
second_order_values=interaction_values.get_n_order_values(2)
)
# or use
interaction_values.plot_network()
```
The pseudo-code above can produce the following plot (here also an image is added):
<p align="center">
<img width="500px" src="https://raw.githubusercontent.com/mmschlk/shapiq/main/docs/source/_static/network_example2.png" alt="network_plot_example">
</p>
## 📖 Documentation with tutorials
The documentation of ``shapiq`` can be found at https://shapiq.readthedocs.io
## 💬 Citation
If you enjoy using the `shapiq` package, please consider citing our [NeurIPS paper](https://arxiv.org/abs/2410.01649):
```bibtex
@inproceedings{muschalik2024shapiq,
title = {shapiq: Shapley Interactions for Machine Learning},
author = {Maximilian Muschalik and Hubert Baniecki and Fabian Fumagalli and
Patrick Kolpaczki and Barbara Hammer and Eyke H\"{u}llermeier},
booktitle = {The Thirty-eight Conference on Neural Information Processing Systems Datasets and Benchmarks Track},
year = {2024},
url = {https://openreview.net/forum?id=knxGmi6SJi}
}
```
## Changelog
### v1.1.1 (2024-11-13)
#### Improvements and Ease of Use
- adds a `class_index` parameter to `TabularExplainer` and `Explainer` to specify the class index to be explained for classification models [#271](https://github.com/mmschlk/shapiq/issues/271) (renames `class_label` parameter in TreeExplainer to `class_index`)
- adds support for `PyTorch` models to `Explainer` [#272](https://github.com/mmschlk/shapiq/issues/272)
- adds new tests comparing `shapiq` outputs for SVs with alues computed with `shap`
- adds new tests for checking `shapiq` explainers with different types of models
#### Bug Fixes
- fixes a bug that `RandomForestClassifier` models were not working with the `TreeExplainer` [#273](https://github.com/mmschlk/shapiq/issues/273)
### v1.1.0 (2024-11-07)
#### New Features and Improvements
- adds computation of the Egalitarian Core (`EC`) and Egalitarian Least-Core (`ELC`) to the `ExactComputer` [#182](https://github.com/mmschlk/shapiq/issues/182)
- adds `waterfall_plot` [#34](https://github.com/mmschlk/shapiq/issues/34) that visualizes the contributions of features to the model prediction
- adds `BaselineImputer` [#107](https://github.com/mmschlk/shapiq/issues/107) which is now responsible for handling the `sample_replacements` parameter. Added a DeprecationWarning for the parameter in `MarginalImputer`, which will be removed in the next release.
- adds `joint_marginal_distribution` parameter to `MarginalImputer` with default value `True` [#261](https://github.com/mmschlk/shapiq/issues/261)
- renames explanation graph to `si_graph`
- `get_n_order` now has optional lower/upper limits for the order
- computing metrics for benchmarking now tries to resolve not-matching interaction indices and will throw a warning instead of a ValueError [#179](https://github.com/mmschlk/shapiq/issues/179)
- add a legend to benchmark plots [#170](https://github.com/mmschlk/shapiq/issues/170)
- refactored the `shapiq.games.benchmark` module into a separate `shapiq.benchmark` module by moving all but the benchmark games into the new module. This closes [#169](https://github.com/mmschlk/shapiq/issues/169) and makes benchmarking more flexible and convenient.
- a `shapiq.Game` can now be called more intuitively with coalitions data types (tuples of int or str) and also allows to add `player_names` to the game at initialization [#183](https://github.com/mmschlk/shapiq/issues/183)
- improve tests across the package
#### Documentation
- adds a notebook showing how to use custom tree models with the `TreeExplainer` [#66](https://github.com/mmschlk/shapiq/issues/66)
- adds a notebook show how to use the `shapiq.Game` API to create custom games [#184](https://github.com/mmschlk/shapiq/issues/184)
- adds a notebook showing hot to visualize interactions [#252](https://github.com/mmschlk/shapiq/issues/252)
- adds a notebook showing how to compute Shapley values with `shapiq` [#193](https://github.com/mmschlk/shapiq/issues/197)
- adds a notebook for conducting data valuation [#190](https://github.com/mmschlk/shapiq/issues/190)
- adds a notebook showcasing introducing the Core and how to compute it with `shapiq` [#191](https://github.com/mmschlk/shapiq/issues/191)
#### Bug Fixes
- fixes a bug with SIs not adding up to the model prediction because of wrong values in the empty set [#264](https://github.com/mmschlk/shapiq/issues/264)
- fixes a bug that `TreeExplainer` did not have the correct baseline_value when using XGBoost models [#250](https://github.com/mmschlk/shapiq/issues/250)
- fixes the force plot not showing and its baseline value
### v1.0.1 (2024-06-05)
- add `max_order=1` to `TabularExplainer` and `TreeExplainer`
- fix `TreeExplainer.explain_X(..., n_jobs=2, random_state=0)`
### v1.0.0 (2024-06-04)
Major release of the `shapiq` Python package including (among others):
- `approximator` module implements over 10 approximators of Shapley values and interaction indices.
- `exact` module implements a computer for over 10 game theoretic concepts like interaction indices or generalized values.
- `games` module implements over 10 application benchmarks for the approximators.
- `explainer` module includes a `TabularExplainer` and `TreeExplainer` for any-order feature interactions of machine learning model predictions.
- `interaction_values` module implements a data class to store and analyze interaction values.
- `plot` module allows visualizing interaction values.
- `datasets` module loads datasets for testing and examples.
Documentation of `shapiq` with tutorials and API reference is available at https://shapiq.readthedocs.io
Raw data
{
"_id": null,
"home_page": "https://github.com/mmschlk/shapiq",
"name": "shapiq",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9.0",
"maintainer_email": null,
"keywords": "python, machine learning, interpretable machine learning, shap, xai, explainable ai, interaction, shapley interactions, shapley values, feature interaction",
"author": "Maximilian Muschalik et al.",
"author_email": "maximilian.muschalik@ifi.lmu.de",
"download_url": "https://files.pythonhosted.org/packages/49/f6/2ff07243e1e49385fb1ba9b7cd31bb44f8d8c1dddd01f1115c98b8f98faf/shapiq-1.1.1.tar.gz",
"platform": null,
"description": "# shapiq: Shapley Interactions for Machine Learning <img src=\"https://raw.githubusercontent.com/mmschlk/shapiq/main/docs/source/_static/logo_shapiq_light.svg\" alt=\"shapiq_logo\" align=\"right\" height=\"250px\"/>\n\n[](https://opensource.org/licenses/MIT)\n[](https://coveralls.io/github/mmschlk/shapiq?branch=main)\n[](https://github.com/mmschlk/shapiq/actions/workflows/unit-tests.yml)\n[](https://shapiq.readthedocs.io/en/latest/?badge=latest)\n\n[](https://pypi.org/project/shapiq)\n[](https://pypi.org/project/shapiq)\n[](https://pepy.tech/project/shapiq)\n\n[](https://github.com/psf/black)\n\n> An interaction may speak more than a thousand main effects.\n\nShapley Interaction Quantification (`shapiq`) is a Python package for (1) approximating any-order Shapley interactions, (2) benchmarking game-theoretical algorithms for machine learning, (3) explaining feature interactions of model predictions. `shapiq` extends the well-known [shap](https://github.com/shap/shap) package for both researchers working on game theory in machine learning, as well as the end-users explaining models. SHAP-IQ extends individual Shapley values by quantifying the **synergy** effect between entities (aka **players** in the jargon of game theory) like explanatory features, data points, or weak learners in ensemble models. Synergies between players give a more comprehensive view of machine learning models.\n\n## \ud83d\udee0\ufe0f Install\n`shapiq` is intended to work with **Python 3.9 and above**. Installation can be done via `pip`:\n\n```sh\npip install shapiq\n```\n\n## \u2b50 Quickstart\n\nYou can explain your model with `shapiq.explainer` and visualize Shapley interactions with `shapiq.plot`.\nIf you are interested in the underlying game theoretic algorithms, then check out the `shapiq.approximator` and `shapiq.games` modules.\n\n### \ud83d\udcc8 Compute any-order feature interactions\n\nExplain your models with Shapley interaction values like the k-SII values:\n\n```python\nimport shapiq\n# load data\nX, y = shapiq.load_california_housing(to_numpy=True)\n# train a model\nfrom sklearn.ensemble import RandomForestRegressor\nmodel = RandomForestRegressor()\nmodel.fit(X, y)\n# set up an explainer with k-SII interaction values up to order 4\nexplainer = shapiq.TabularExplainer(\n model=model,\n data=X,\n index=\"k-SII\",\n max_order=4\n)\n# explain the model's prediction for the first sample\ninteraction_values = explainer.explain(X[0], budget=256)\n# analyse interaction values\nprint(interaction_values)\n\n>> InteractionValues(\n>> index=k-SII, max_order=4, min_order=0, estimated=False,\n>> estimation_budget=256, n_players=8, baseline_value=2.07282292,\n>> Top 10 interactions:\n>> (0,): 1.696969079 # attribution of feature 0\n>> (0, 5): 0.4847876\n>> (0, 1): 0.4494288 # interaction between features 0 & 1\n>> (0, 6): 0.4477677\n>> (1, 5): 0.3750034\n>> (4, 5): 0.3468325\n>> (0, 3, 6): -0.320 # interaction between features 0 & 3 & 6\n>> (2, 3, 6): -0.329\n>> (0, 1, 5): -0.363\n>> (6,): -0.56358890\n>> )\n```\n\n### \ud83d\udcca Visualize feature interactions\n\nA handy way of visualizing interaction scores up to order 2 are network plots.\nYou can see an example of such a plot below.\nThe nodes represent feature **attributions** and the edges represent the **interactions** between features.\nThe strength and size of the nodes and edges are proportional to the absolute value of attributions and interactions, respectively.\n\n```python\nshapiq.network_plot(\n first_order_values=interaction_values.get_n_order_values(1),\n second_order_values=interaction_values.get_n_order_values(2)\n)\n# or use\ninteraction_values.plot_network()\n```\n\nThe pseudo-code above can produce the following plot (here also an image is added):\n\n<p align=\"center\">\n <img width=\"500px\" src=\"https://raw.githubusercontent.com/mmschlk/shapiq/main/docs/source/_static/network_example2.png\" alt=\"network_plot_example\">\n</p>\n\n## \ud83d\udcd6 Documentation with tutorials\nThe documentation of ``shapiq`` can be found at https://shapiq.readthedocs.io\n\n## \ud83d\udcac Citation\n\nIf you enjoy using the `shapiq` package, please consider citing our [NeurIPS paper](https://arxiv.org/abs/2410.01649):\n\n```bibtex\n@inproceedings{muschalik2024shapiq,\n title = {shapiq: Shapley Interactions for Machine Learning},\n author = {Maximilian Muschalik and Hubert Baniecki and Fabian Fumagalli and\n Patrick Kolpaczki and Barbara Hammer and Eyke H\\\"{u}llermeier},\n booktitle = {The Thirty-eight Conference on Neural Information Processing Systems Datasets and Benchmarks Track},\n year = {2024},\n url = {https://openreview.net/forum?id=knxGmi6SJi}\n}\n```\n\n\n## Changelog\n\n### v1.1.1 (2024-11-13)\n\n#### Improvements and Ease of Use\n- adds a `class_index` parameter to `TabularExplainer` and `Explainer` to specify the class index to be explained for classification models [#271](https://github.com/mmschlk/shapiq/issues/271) (renames `class_label` parameter in TreeExplainer to `class_index`)\n- adds support for `PyTorch` models to `Explainer` [#272](https://github.com/mmschlk/shapiq/issues/272)\n- adds new tests comparing `shapiq` outputs for SVs with alues computed with `shap`\n- adds new tests for checking `shapiq` explainers with different types of models\n\n#### Bug Fixes\n- fixes a bug that `RandomForestClassifier` models were not working with the `TreeExplainer` [#273](https://github.com/mmschlk/shapiq/issues/273)\n\n### v1.1.0 (2024-11-07)\n\n#### New Features and Improvements\n- adds computation of the Egalitarian Core (`EC`) and Egalitarian Least-Core (`ELC`) to the `ExactComputer` [#182](https://github.com/mmschlk/shapiq/issues/182)\n- adds `waterfall_plot` [#34](https://github.com/mmschlk/shapiq/issues/34) that visualizes the contributions of features to the model prediction\n- adds `BaselineImputer` [#107](https://github.com/mmschlk/shapiq/issues/107) which is now responsible for handling the `sample_replacements` parameter. Added a DeprecationWarning for the parameter in `MarginalImputer`, which will be removed in the next release.\n- adds `joint_marginal_distribution` parameter to `MarginalImputer` with default value `True` [#261](https://github.com/mmschlk/shapiq/issues/261)\n- renames explanation graph to `si_graph`\n- `get_n_order` now has optional lower/upper limits for the order\n- computing metrics for benchmarking now tries to resolve not-matching interaction indices and will throw a warning instead of a ValueError [#179](https://github.com/mmschlk/shapiq/issues/179)\n- add a legend to benchmark plots [#170](https://github.com/mmschlk/shapiq/issues/170)\n- refactored the `shapiq.games.benchmark` module into a separate `shapiq.benchmark` module by moving all but the benchmark games into the new module. This closes [#169](https://github.com/mmschlk/shapiq/issues/169) and makes benchmarking more flexible and convenient.\n- a `shapiq.Game` can now be called more intuitively with coalitions data types (tuples of int or str) and also allows to add `player_names` to the game at initialization [#183](https://github.com/mmschlk/shapiq/issues/183)\n- improve tests across the package\n\n#### Documentation\n- adds a notebook showing how to use custom tree models with the `TreeExplainer` [#66](https://github.com/mmschlk/shapiq/issues/66)\n- adds a notebook show how to use the `shapiq.Game` API to create custom games [#184](https://github.com/mmschlk/shapiq/issues/184)\n- adds a notebook showing hot to visualize interactions [#252](https://github.com/mmschlk/shapiq/issues/252)\n- adds a notebook showing how to compute Shapley values with `shapiq` [#193](https://github.com/mmschlk/shapiq/issues/197)\n- adds a notebook for conducting data valuation [#190](https://github.com/mmschlk/shapiq/issues/190)\n- adds a notebook showcasing introducing the Core and how to compute it with `shapiq` [#191](https://github.com/mmschlk/shapiq/issues/191)\n\n#### Bug Fixes\n- fixes a bug with SIs not adding up to the model prediction because of wrong values in the empty set [#264](https://github.com/mmschlk/shapiq/issues/264)\n- fixes a bug that `TreeExplainer` did not have the correct baseline_value when using XGBoost models [#250](https://github.com/mmschlk/shapiq/issues/250)\n- fixes the force plot not showing and its baseline value\n\n### v1.0.1 (2024-06-05)\n\n- add `max_order=1` to `TabularExplainer` and `TreeExplainer`\n- fix `TreeExplainer.explain_X(..., n_jobs=2, random_state=0)`\n\n### v1.0.0 (2024-06-04)\n\nMajor release of the `shapiq` Python package including (among others):\n\n- `approximator` module implements over 10 approximators of Shapley values and interaction indices.\n- `exact` module implements a computer for over 10 game theoretic concepts like interaction indices or generalized values.\n- `games` module implements over 10 application benchmarks for the approximators.\n- `explainer` module includes a `TabularExplainer` and `TreeExplainer` for any-order feature interactions of machine learning model predictions.\n- `interaction_values` module implements a data class to store and analyze interaction values.\n- `plot` module allows visualizing interaction values.\n- `datasets` module loads datasets for testing and examples.\n\nDocumentation of `shapiq` with tutorials and API reference is available at https://shapiq.readthedocs.io\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Shapley Interactions for Machine Learning",
"version": "1.1.1",
"project_urls": {
"Documentation": "https://shapiq.readthedocs.io",
"Homepage": "https://github.com/mmschlk/shapiq",
"Source": "https://github.com/mmschlk/shapiq",
"Tracker": "https://github.com/mmschlk/shapiq/issues"
},
"split_keywords": [
"python",
" machine learning",
" interpretable machine learning",
" shap",
" xai",
" explainable ai",
" interaction",
" shapley interactions",
" shapley values",
" feature interaction"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f20f174147dd61241e478291006e66e96a512da32161659591fe4f52f3b4bc0a",
"md5": "7f978d7f2d28f01ce8b07f66d1f6e866",
"sha256": "6db684a5b0d5739920856c8228a98ff05654418b3df89f5944c87be7b6a1e575"
},
"downloads": -1,
"filename": "shapiq-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7f978d7f2d28f01ce8b07f66d1f6e866",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.0",
"size": 212985,
"upload_time": "2024-11-13T11:36:23",
"upload_time_iso_8601": "2024-11-13T11:36:23.049938Z",
"url": "https://files.pythonhosted.org/packages/f2/0f/174147dd61241e478291006e66e96a512da32161659591fe4f52f3b4bc0a/shapiq-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "49f62ff07243e1e49385fb1ba9b7cd31bb44f8d8c1dddd01f1115c98b8f98faf",
"md5": "1f257c4cabae8c8a9e2261b739e5b23d",
"sha256": "c387ac43578f615fcdce78a483c9878687948935969b8b4467c95c454435cfe5"
},
"downloads": -1,
"filename": "shapiq-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "1f257c4cabae8c8a9e2261b739e5b23d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.0",
"size": 167465,
"upload_time": "2024-11-13T11:36:24",
"upload_time_iso_8601": "2024-11-13T11:36:24.550024Z",
"url": "https://files.pythonhosted.org/packages/49/f6/2ff07243e1e49385fb1ba9b7cd31bb44f8d8c1dddd01f1115c98b8f98faf/shapiq-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-13 11:36:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mmschlk",
"github_project": "shapiq",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "shapiq"
}
JSON
