<p align="center">
<img height="250px" src="docs/source/_static/logo_shapiq_light.svg" alt="shapiq_logo">
</p>
<p align="center">
<!-- Tests -->
<a href="https://github.com/mmschlk/shapiq/actions/workflows/unit-tests.yml">
<img src="https://github.com/mmschlk/shapiq/actions/workflows/unit-tests.yml/badge.svg" alt="unit-tests">
</a>
<!-- Coverage Test -->
<a href='https://coveralls.io/github/mmschlk/shapiq?branch=main'>
<img src='https://coveralls.io/repos/github/mmschlk/shapiq/badge.svg?branch=main' alt='Coverage Status' />
</a>
<!-- Read the Docs -->
<a href='https://shapiq.readthedocs.io/en/latest/?badge=latest'>
<img src='https://readthedocs.org/projects/shapiq/badge/?version=latest' alt='Documentation Status' />
</a>
<!-- PyPI Version -->
<a href="https://pypi.org/project/shapiq">
<img src="https://img.shields.io/pypi/v/shapiq.svg?color=blue" alt="PyPi">
</a>
<!-- PyPI status -->
<a href="https://pypi.org/project/shapiq">
<img src="https://img.shields.io/pypi/status/shapiq.svg?color=blue" alt="PyPi_status
</a>
<!-- PePy -->
<a href="https://pepy.tech/project/shapiq">
<img src="https://static.pepy.tech/badge/shapiq?style=flat-square" alt="pepy">
</a>
<!-- License -->
<a href="https://opensource.org/licenses/MIT">
<img src="https://img.shields.io/badge/License-MIT-brightgreen.svg" alt="mit_license">
</a>
<!-- Codestyle -->
<a href="https://github.com/psf/black">
<img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="black_codestyle">
</a>
</p>
# SHAP-IQ: SHAP Interaction Quantification
> An interaction may speak more than a thousand main effects.
SHAP Interaction Quantification (short SHAP-IQ) is an **XAI framework** extending on the well-known [`shap`](https://github.com/shap/shap) explanations by introducing interactions to the equation.
Shapley interactions extend on indivdual Shapley values by quantifying the **synergy** effect between machine learning entities such as features, data points, or weak learners in ensemble models.
Synergies between these entities (also called players in game theory jargon) allows for a more intricate evaluation of your **black-box** 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 use `shapiq` in different ways. If you have a trained model you can rely on the `shapiq.explainer` classes.
If you are interested in the underlying game theoretic algorithms, then check out the `shapiq.approximator` modules.
You can also plot and visualize your interaction scores with `shapiq.plot`.
## 📈 Compute k-SII values
Explain your models with Shapley interaction values like the k-SII values:
```python
# train a model
from sklearn.ensemble import RandomForestRegressor
model = RandomForestRegressor(n_estimators=50, random_state=42)
model.fit(x_train, y_train)
# explain with k-SII interaction scores
from shapiq import TabularExplainer
explainer = TabularExplainer(
model=model.predict,
background_data=x_train,
index="k-SII",
max_order=2
)
interaction_values = explainer.explain(x_explain, budget=2000)
print(interaction_values)
>> > InteractionValues(
>> > index = k - SII, max_order = 2, min_order = 1, estimated = True, estimation_budget = 2000,
>> > values = {
>> > (0,): -91.0403, # main effect for feature 0
>> > (1,): 4.1264, # main effect for feature 1
>> > (2,): -0.4724, # main effect for feature 2
>> > ...
>> > (0, 1): -0.8073, # 2-way interaction for feature 0 and 1
>> > (0, 2): 2.469, # 2-way interaction for feature 0 and 2
>> > ...
>> > (10, 11): 0.4057 # 2-way interaction for feature 10 and 11
>> >}
>> > )
```
## 📊 Visualize your Interactions
One 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 **attribution** scores and the edges represent the **interactions**.
The strength and size of the nodes and edges are proportional to the absolute value of the
attribution scores and interaction scores, respectively.
```python
from shapiq.plot import network_plot
network_plot(
first_order_values=k_sii_first_order, # first order k-SII values
second_order_values=k_sii_second_order # second order k-SII values
)
```
The pseudo-code above can produce the following plot (here also an image is added):
<p align="center">
<img width="400px" src="docs/source/_static/network_example.png" alt="network_plot_example">
</p>
## 📖 Documentation
The documentation for ``shapiq`` can be found [here](https://shapiq.readthedocs.io/en/latest/).
## 💬 Citation
If you **ejnoy** `shapiq` consider starring ⭐ the repository. If you **really enjoy** the package or it has been useful to you, and you would like to cite it in a scientific publication, please refer to the [paper](https://openreview.net/forum?id=IEMLNF4gK4) accepted at NeurIPS'23:
```bibtex
@article{shapiq,
author = {Fabian Fumagalli and
Maximilian Muschalik and
Patrick Kolpaczki and
Eyke H{\"{u}}llermeier and
Barbara Hammer},
title = {{SHAP-IQ:} Unified Approximation of any-order Shapley Interactions},
journal = {CoRR},
volume = {abs/2303.01179},
year = {2023},
doi = {10.48550/ARXIV.2303.01179},
eprinttype = {arXiv}
}
```
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, shap, xai, interaction, shapley interactions, shapley values, feature interaction",
"author": "Maximilian Muschalik Fabian Fumagalli",
"author_email": "maximilian.muschalik@ifi.lmu.de",
"download_url": "https://files.pythonhosted.org/packages/0a/97/cf8f6acd70e3ca0965c37fd4c01932d2fb522e16f84e3c19e7fdc456e197/shapiq-0.0.6.tar.gz",
"platform": null,
"description": "\n<p align=\"center\">\n <img height=\"250px\" src=\"docs/source/_static/logo_shapiq_light.svg\" alt=\"shapiq_logo\">\n</p>\n\n<p align=\"center\">\n <!-- Tests -->\n <a href=\"https://github.com/mmschlk/shapiq/actions/workflows/unit-tests.yml\">\n <img src=\"https://github.com/mmschlk/shapiq/actions/workflows/unit-tests.yml/badge.svg\" alt=\"unit-tests\">\n </a>\n\n <!-- Coverage Test -->\n <a href='https://coveralls.io/github/mmschlk/shapiq?branch=main'>\n <img src='https://coveralls.io/repos/github/mmschlk/shapiq/badge.svg?branch=main' alt='Coverage Status' />\n </a>\n\n <!-- Read the Docs -->\n <a href='https://shapiq.readthedocs.io/en/latest/?badge=latest'>\n <img src='https://readthedocs.org/projects/shapiq/badge/?version=latest' alt='Documentation Status' />\n </a>\n \n <!-- PyPI Version -->\n <a href=\"https://pypi.org/project/shapiq\">\n <img src=\"https://img.shields.io/pypi/v/shapiq.svg?color=blue\" alt=\"PyPi\">\n </a>\n \n <!-- PyPI status -->\n <a href=\"https://pypi.org/project/shapiq\">\n <img src=\"https://img.shields.io/pypi/status/shapiq.svg?color=blue\" alt=\"PyPi_status\n </a>\n \n <!-- PePy -->\n <a href=\"https://pepy.tech/project/shapiq\">\n <img src=\"https://static.pepy.tech/badge/shapiq?style=flat-square\" alt=\"pepy\">\n </a>\n \n <!-- License -->\n <a href=\"https://opensource.org/licenses/MIT\">\n <img src=\"https://img.shields.io/badge/License-MIT-brightgreen.svg\" alt=\"mit_license\">\n </a>\n\n <!-- Codestyle -->\n <a href=\"https://github.com/psf/black\">\n <img src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" alt=\"black_codestyle\">\n </a>\n</p>\n\n\n# SHAP-IQ: SHAP Interaction Quantification\n> An interaction may speak more than a thousand main effects.\n\nSHAP Interaction Quantification (short SHAP-IQ) is an **XAI framework** extending on the well-known [`shap`](https://github.com/shap/shap) explanations by introducing interactions to the equation.\nShapley interactions extend on indivdual Shapley values by quantifying the **synergy** effect between machine learning entities such as features, data points, or weak learners in ensemble models.\nSynergies between these entities (also called players in game theory jargon) allows for a more intricate evaluation of your **black-box** 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\nYou can use `shapiq` in different ways. If you have a trained model you can rely on the `shapiq.explainer` classes.\nIf you are interested in the underlying game theoretic algorithms, then check out the `shapiq.approximator` modules.\nYou can also plot and visualize your interaction scores with `shapiq.plot`.\n\n## \ud83d\udcc8 Compute k-SII values\n\nExplain your models with Shapley interaction values like the k-SII values:\n\n```python\n# train a model\nfrom sklearn.ensemble import RandomForestRegressor\n\nmodel = RandomForestRegressor(n_estimators=50, random_state=42)\nmodel.fit(x_train, y_train)\n\n# explain with k-SII interaction scores\nfrom shapiq import TabularExplainer\n\nexplainer = TabularExplainer(\n model=model.predict,\n background_data=x_train,\n index=\"k-SII\",\n max_order=2\n)\ninteraction_values = explainer.explain(x_explain, budget=2000)\nprint(interaction_values)\n\n>> > InteractionValues(\n >> > index = k - SII, max_order = 2, min_order = 1, estimated = True, estimation_budget = 2000,\n>> > values = {\n >> > (0,): -91.0403, # main effect for feature 0\n>> > (1,): 4.1264, # main effect for feature 1\n>> > (2,): -0.4724, # main effect for feature 2\n>> > ...\n >> > (0, 1): -0.8073, # 2-way interaction for feature 0 and 1\n>> > (0, 2): 2.469, # 2-way interaction for feature 0 and 2\n>> > ...\n >> > (10, 11): 0.4057 # 2-way interaction for feature 10 and 11\n >> >}\n>> > )\n```\n\n## \ud83d\udcca Visualize your Interactions\n\nOne 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 **attribution** scores and the edges represent the **interactions**.\nThe strength and size of the nodes and edges are proportional to the absolute value of the\nattribution scores and interaction scores, respectively.\n\n```python\nfrom shapiq.plot import network_plot\n\nnetwork_plot(\n first_order_values=k_sii_first_order, # first order k-SII values\n second_order_values=k_sii_second_order # second order k-SII values\n)\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=\"400px\" src=\"docs/source/_static/network_example.png\" alt=\"network_plot_example\">\n</p>\n\n## \ud83d\udcd6 Documentation\nThe documentation for ``shapiq`` can be found [here](https://shapiq.readthedocs.io/en/latest/).\n\n## \ud83d\udcac Citation\n\nIf you **ejnoy** `shapiq` consider starring \u2b50 the repository. If you **really enjoy** the package or it has been useful to you, and you would like to cite it in a scientific publication, please refer to the [paper](https://openreview.net/forum?id=IEMLNF4gK4) accepted at NeurIPS'23:\n\n```bibtex\n@article{shapiq,\n author = {Fabian Fumagalli and\n Maximilian Muschalik and\n Patrick Kolpaczki and\n Eyke H{\\\"{u}}llermeier and\n Barbara Hammer},\n title = {{SHAP-IQ:} Unified Approximation of any-order Shapley Interactions},\n journal = {CoRR},\n volume = {abs/2303.01179},\n year = {2023},\n doi = {10.48550/ARXIV.2303.01179},\n eprinttype = {arXiv}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "SHAPley Interaction Quantification (SHAP-IQ) for Explainable AI",
"version": "0.0.6",
"project_urls": {
"Homepage": "https://github.com/mmschlk/shapiq",
"Source": "https://github.com/mmschlk/shapiq",
"Tracker": "https://github.com/mmschlk/shapiq/issues?q=is%3Aissue+label%3Abug"
},
"split_keywords": [
"python",
" machine learning",
" shap",
" xai",
" interaction",
" shapley interactions",
" shapley values",
" feature interaction"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2a33439604e00ec06f14610513362a6b3ae02ca534ffe99171871683c0e6bc6f",
"md5": "79fe9e8a14f1411c37f1b7b7e2cb7363",
"sha256": "2b2741b071f49f8935cb54dc7b26a5dd55a59c49bf3779e148099e8f0e8f7afc"
},
"downloads": -1,
"filename": "shapiq-0.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "79fe9e8a14f1411c37f1b7b7e2cb7363",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.0",
"size": 62502,
"upload_time": "2024-03-20T15:38:22",
"upload_time_iso_8601": "2024-03-20T15:38:22.722280Z",
"url": "https://files.pythonhosted.org/packages/2a/33/439604e00ec06f14610513362a6b3ae02ca534ffe99171871683c0e6bc6f/shapiq-0.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0a97cf8f6acd70e3ca0965c37fd4c01932d2fb522e16f84e3c19e7fdc456e197",
"md5": "b5fc6846baf22193eec68c2a511933d5",
"sha256": "4afe1c2986d286a6c45d7b3898403e3bdab8d5b5ae12c42f150e880e4d0e7a24"
},
"downloads": -1,
"filename": "shapiq-0.0.6.tar.gz",
"has_sig": false,
"md5_digest": "b5fc6846baf22193eec68c2a511933d5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.0",
"size": 59562,
"upload_time": "2024-03-20T15:38:24",
"upload_time_iso_8601": "2024-03-20T15:38:24.672243Z",
"url": "https://files.pythonhosted.org/packages/0a/97/cf8f6acd70e3ca0965c37fd4c01932d2fb522e16f84e3c19e7fdc456e197/shapiq-0.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-20 15:38: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
