shapiq 1.2.3__tar.gz → 1.3.0__tar.gz

{shapiq-1.2.3 → shapiq-1.3.0}/CHANGELOG.md

@@ -1,6 +1,38 @@
 ## Changelog
 
-### Development
+### v1.3.0 (2025-06-17)
+
+#### Highlights
+- `shapiq.SPEX` (Sparse Exact) approximator for efficient computation of sparse interaction values for really large models and games. Paper: [SPEX: Scaling Feature Interaction Explanations for LLMs](https://arxiv.org/abs/2502.13870)
+- `shapiq.AgnosticExplainer` a generic explainer that works for any value function or `shapiq.Game` object, allowing for more flexibility in explainers.
+- prettier graph-based plots via `shapiq.si_graph_plot()` and `shapiq.network_plot()`, which now use the same backend for more flexibility and easier maintenance.
+
+#### New Features
+- adds the SPEX (Sparse Exact) module in `approximator.sparse` for efficient computation of sparse interaction values [#379](https://github.com/mmschlk/shapiq/pull/379)
+- adds `shapiq.AgnosticExplainer` which is a generic explainer that can be used for any value function or `shapiq.Game` object. This allows for more flexibility in the explainers. [#100](https://github.com/mmschlk/shapiq/issues/100), [#395](https://github.com/mmschlk/shapiq/pull/395)
+- changes `budget` to be a mandatory parameter given to the `TabularExplainer.explain()` method [#355](https://github.com/mmschlk/shapiq/pull/356)
+- changes logic of `InteractionValues.get_n_order()` function to be callable with **either** the `order: int` parameter and optional assignment of `min_order: int` and `max_order: int` parameters **or** with the min/max order parameters [#372](https://github.com/mmschlk/shapiq/pull/372)
+- renamed `min_percentage` parameter in the force plot to `contribution_threshold` to better reflect its purpose [#391](https://github.com/mmschlk/shapiq/pull/391)
+- adds ``verbose`` parameter to the ``Explainer``'s ``explain_X()`` method to control weather a progress bar is shown or not which is defaulted to ``False``. [#391](https://github.com/mmschlk/shapiq/pull/391)
+- made `InteractionValues.get_n_order()` and `InteractionValues.get_n_order_values()` function more efficient by iterating over the stored interactions and not over the powerset of all potential interactions, which made the function not usable for higher player counts (models with many features, and results obtained from `TreeExplainer`). Note, this change does not really help `get_n_order_values()` as it still needs to create a numpy array of shape `n_players` times `order` [#372](https://github.com/mmschlk/shapiq/pull/372)
+- streamlined the ``network_plot()`` plot function to use the ``si_graph_plot()`` as its backend function. This allows for more flexibility in the plot function and makes it easier to use the same code for different purposes. In addition, the ``si_graph_plot`` was modified to make plotting more easy and allow for more flexibility with new parameters. [#349](https://github.com/mmschlk/shapiq/pull/349)
+- adds `Game.compute()` method to the `shapiq.Game` class to compute game values without changing the state of the game object. The compute method also introduces a `shapiq.utils.sets.generate_interaction_lookup_from_coalitions()` utility method which creates an interaction lookup dict from an array of coalitions. [#397](https://github.com/mmschlk/shapiq/pull/397)
+- streamlines the creation of network plots and graph plots which now uses the same backend. The network plot via `shapiq.network_plot()` or `InteractionValues.plot_network()` is now a special case of the `shapiq.si_graph_plot()` and `InteractionValues.plot_si_graph()`. This allows to create more beautiful plots and easier maintenance in the future. [#349](https://github.com/mmschlk/shapiq/pull/349)
+
+#### Testing, Code-Quality and Documentation
+- activates ``"ALL"`` rules in ``ruff-format`` configuration to enforce stricter code quality checks and addressed around 500 (not automatically solvable) issues in the code base. [#391](https://github.com/mmschlk/shapiq/pull/391)
+- improved the testing environment by adding a new fixture module containing mock `InteractionValues` objects to be used in the tests. This allows for more efficient and cleaner tests, as well as easier debugging of the tests  [#372](https://github.com/mmschlk/shapiq/pull/372)
+- removed check and error message if the ``index`` parameter is not in the list of available indices in the ``TabularExplainer`` since the type hints were replaced by Literals [#391](https://github.com/mmschlk/shapiq/pull/391)
+- removed multiple instances where ``shapiq`` tests if some approximators/explainers can be instantiated with certain indices or not in favor of using Literals in the ``__init__`` method of the approximator classes. This allows for better type hinting and IDE support, as well as cleaner code. [#391](https://github.com/mmschlk/shapiq/pull/391)
+- Added documentation for all public modules, classes, and functions in the code base to improve the documentation quality and make it easier to understand how to use the package. [#391](https://github.com/mmschlk/shapiq/pull/391)
+- suppress a ``RuntimeWarning`` in ``Regression`` approximators ``solve_regression()``method when the solver is not able to find good interim solutions for the regression problem.
+- refactors the tests into ``tests_unit/`` and ``tests_integration/`` to better separate unit tests from integration tests. [#395](https://github.com/mmschlk/shapiq/pull/395)
+- adds new integration tests in ``tests/tests_integration/test_explainer_california_housing`` which compares the different explainers against ground-truth interaction values computed by ``shapiq.ExactComputer`` and interaction values stored on [disk](https://github.com/mmschlk/shapiq/tree/main/tests/data/interaction_values/california_housing) as a form of regression test. This test should help finding bugs in the future when the approximators, explainers, or exact computation are changed. [#395](https://github.com/mmschlk/shapiq/pull/395)
+
+#### Bug Fixes
+- fixed a bug in the `shapiq.waterfall_plot` function that caused the plot to not display correctly resulting in cutoff y_ticks. Additionally, the file was renamed from `watefall.py` to `waterfall.py` to match the function name [#377](https://github.com/mmschlk/shapiq/pull/377)
+- fixes a bug with `TabPFNExplainer`, where the model was not able to be used for predictions after it was explained. This was due to the model being fitted on a subset of features, which caused inconsistencies in the model's predictions after explanation. The fix includes that after each call to the `TabPFNImputer.value_function`, the tabpfn model is fitted on the whole dataset (without omitting features). This means that the original model can be used for predictions after it has been explained. [#396](https://github.com/mmschlk/shapiq/issues/396).
+- fixed a bug in computing `BII` or `BV` indices with `shapiq.approximator.MonteCarlo` approximators (affecting `SHAP-IQ`, `SVARM` and `SVARM-IQ`). All orders of BII should now be computed correctly. [#395](https://github.com/mmschlk/shapiq/pull/395)
 
 ### v1.2.3 (2025-03-24)
 - substantially improves the runtime of all `Regression` approximators by a) a faster pre-computation of the regression matrices and b) a faster computation of the weighted least squares regression [#340](https://github.com/mmschlk/shapiq/issues/340)

{shapiq-1.2.3/shapiq.egg-info → shapiq-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shapiq
-Version: 1.2.3
+Version: 1.3.0
 Summary: Shapley Interactions for Machine Learning
 Author: Hubert Baniecki, Fabian Fumagalli
 Author-email: Maximilian Muschalik <Maximilian.Muschalik@lmu.de>
@@ -33,9 +33,12 @@ Requires-Dist: pandas
 Requires-Dist: scikit-learn
 Requires-Dist: tqdm
 Requires-Dist: requests
+Requires-Dist: sparse-transform
+Requires-Dist: galois
 Requires-Dist: matplotlib
 Requires-Dist: networkx
 Requires-Dist: colour
+Requires-Dist: pillow
 Provides-Extra: ml
 Requires-Dist: tabpfn; extra == "ml"
 Requires-Dist: torchvision; extra == "ml"
@@ -62,15 +65,21 @@ Dynamic: license-file
 [![PePy](https://static.pepy.tech/badge/shapiq?style=flat-square)](https://pepy.tech/project/shapiq)
 
 [![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen)
-![Last Commit](https://img.shields.io/github/last-commit/mmschlk/shapiq)
+[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen)](https://github.com/mmschlk/shapiq/issues)
+[![Last Commit](https://img.shields.io/github/last-commit/mmschlk/shapiq)](https://github.com/mmschlk/shapiq/commits/main)
 
 > 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.10 and above**. Installation can be done via `pip`:
+`shapiq` is intended to work with **Python 3.10 and above**.
+Installation can be done via `uv` :
+```sh
+uv add shapiq
+```
+
+or via `pip`:
 
 ```sh
 pip install shapiq
@@ -84,6 +93,7 @@ If you are interested in the underlying game theoretic algorithms, then check ou
 ### Compute any-order feature interactions
 
 Explain your models with Shapley interactions:
+Just load your data and model, and then use a `shapiq.Explainer` to compute Shapley interactions.
 
 ```python
 import shapiq
@@ -182,7 +192,7 @@ The pseudo-code above can produce the following plot (here also an image is adde
 
 ### Explain TabPFN
 
-With ``shapiq`` you can also [``TabPFN``](https://github.com/PriorLabs/TabPFN) by making use of the _remove-and-recontextualize_ explanation paradigm implemented in ``shapiq.TabPFNExplainer``.
+With ``shapiq`` you can also explain [``TabPFN``](https://github.com/PriorLabs/TabPFN) by making use of the _remove-and-recontextualize_ explanation paradigm implemented in ``shapiq.TabPFNExplainer``.
 
 ```python
 import tabpfn, shapiq
@@ -195,7 +205,7 @@ explainer = shapiq.TabPFNExplainer(   # setup the explainer
     labels=labels,
     index="FSII"
 )
-fsii_values = explainer.explain(X[0])  # explain with Faithful Shapley values
+fsii_values = explainer.explain(data[0])  # explain with Faithful Shapley values
 fsii_values.plot_force()               # plot the force plot
 ```
 
@@ -203,6 +213,28 @@ fsii_values.plot_force()               # plot the force plot
   <img width="800px" src="https://raw.githubusercontent.com/mmschlk/shapiq/main/docs/source/_static/images/fsii_tabpfn_force_plot_example.png" alt="Force Plot of FSII values as derived from the example tabpfn notebook">
 </p>
 
+### Use SPEX (SParse EXplainer) <img src="https://raw.githubusercontent.com/mmschlk/shapiq/main/docs/source/_static/images/spex_logo.png" alt="spex_logo" align="right" height="75px"/>
+For large-scale use-cases you can also check out the [👓``SPEX``](https://shapiq.readthedocs.io/en/latest/api/shapiq.approximator.sparse.html#shapiq.approximator.sparse.SPEX) approximator.
+
+```python
+# load your data and model with large number of features
+data, model, n_features = ...
+
+# use the SPEX approximator directly
+approximator = shapiq.SPEX(n=n_features, index="FBII", max_order=2)
+fbii_scores = approximator.approximate(budget=2000, game=model.predict)
+
+# or use SPEX with an explainer
+explainer = shapiq.Explainer(
+    model=model,
+    data=data,
+    index="FBII",
+    max_order=2,
+    approximator="spex"  # specify SPEX as approximator
+)
+explanation = explainer.explain(data[0])
+```
+
 
 ## 📖 Documentation with tutorials
 The documentation of ``shapiq`` can be found at https://shapiq.readthedocs.io.
@@ -214,7 +246,7 @@ There is a lot of great resources available to get you started with Shapley valu
 If you use ``shapiq`` and enjoy it, please consider citing our [NeurIPS paper](https://arxiv.org/abs/2410.01649) or consider starring this repository.
 
 ```bibtex
-@inproceedings{muschalik2024shapiq,
+@inproceedings{Muschalik.2024b,
   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},
@@ -243,7 +275,39 @@ Built with ❤️ by the shapiq team.
 
 ## Changelog
 
-### Development
+### v1.3.0 (2025-06-17)
+
+#### Highlights
+- `shapiq.SPEX` (Sparse Exact) approximator for efficient computation of sparse interaction values for really large models and games. Paper: [SPEX: Scaling Feature Interaction Explanations for LLMs](https://arxiv.org/abs/2502.13870)
+- `shapiq.AgnosticExplainer` a generic explainer that works for any value function or `shapiq.Game` object, allowing for more flexibility in explainers.
+- prettier graph-based plots via `shapiq.si_graph_plot()` and `shapiq.network_plot()`, which now use the same backend for more flexibility and easier maintenance.
+
+#### New Features
+- adds the SPEX (Sparse Exact) module in `approximator.sparse` for efficient computation of sparse interaction values [#379](https://github.com/mmschlk/shapiq/pull/379)
+- adds `shapiq.AgnosticExplainer` which is a generic explainer that can be used for any value function or `shapiq.Game` object. This allows for more flexibility in the explainers. [#100](https://github.com/mmschlk/shapiq/issues/100), [#395](https://github.com/mmschlk/shapiq/pull/395)
+- changes `budget` to be a mandatory parameter given to the `TabularExplainer.explain()` method [#355](https://github.com/mmschlk/shapiq/pull/356)
+- changes logic of `InteractionValues.get_n_order()` function to be callable with **either** the `order: int` parameter and optional assignment of `min_order: int` and `max_order: int` parameters **or** with the min/max order parameters [#372](https://github.com/mmschlk/shapiq/pull/372)
+- renamed `min_percentage` parameter in the force plot to `contribution_threshold` to better reflect its purpose [#391](https://github.com/mmschlk/shapiq/pull/391)
+- adds ``verbose`` parameter to the ``Explainer``'s ``explain_X()`` method to control weather a progress bar is shown or not which is defaulted to ``False``. [#391](https://github.com/mmschlk/shapiq/pull/391)
+- made `InteractionValues.get_n_order()` and `InteractionValues.get_n_order_values()` function more efficient by iterating over the stored interactions and not over the powerset of all potential interactions, which made the function not usable for higher player counts (models with many features, and results obtained from `TreeExplainer`). Note, this change does not really help `get_n_order_values()` as it still needs to create a numpy array of shape `n_players` times `order` [#372](https://github.com/mmschlk/shapiq/pull/372)
+- streamlined the ``network_plot()`` plot function to use the ``si_graph_plot()`` as its backend function. This allows for more flexibility in the plot function and makes it easier to use the same code for different purposes. In addition, the ``si_graph_plot`` was modified to make plotting more easy and allow for more flexibility with new parameters. [#349](https://github.com/mmschlk/shapiq/pull/349)
+- adds `Game.compute()` method to the `shapiq.Game` class to compute game values without changing the state of the game object. The compute method also introduces a `shapiq.utils.sets.generate_interaction_lookup_from_coalitions()` utility method which creates an interaction lookup dict from an array of coalitions. [#397](https://github.com/mmschlk/shapiq/pull/397)
+- streamlines the creation of network plots and graph plots which now uses the same backend. The network plot via `shapiq.network_plot()` or `InteractionValues.plot_network()` is now a special case of the `shapiq.si_graph_plot()` and `InteractionValues.plot_si_graph()`. This allows to create more beautiful plots and easier maintenance in the future. [#349](https://github.com/mmschlk/shapiq/pull/349)
+
+#### Testing, Code-Quality and Documentation
+- activates ``"ALL"`` rules in ``ruff-format`` configuration to enforce stricter code quality checks and addressed around 500 (not automatically solvable) issues in the code base. [#391](https://github.com/mmschlk/shapiq/pull/391)
+- improved the testing environment by adding a new fixture module containing mock `InteractionValues` objects to be used in the tests. This allows for more efficient and cleaner tests, as well as easier debugging of the tests  [#372](https://github.com/mmschlk/shapiq/pull/372)
+- removed check and error message if the ``index`` parameter is not in the list of available indices in the ``TabularExplainer`` since the type hints were replaced by Literals [#391](https://github.com/mmschlk/shapiq/pull/391)
+- removed multiple instances where ``shapiq`` tests if some approximators/explainers can be instantiated with certain indices or not in favor of using Literals in the ``__init__`` method of the approximator classes. This allows for better type hinting and IDE support, as well as cleaner code. [#391](https://github.com/mmschlk/shapiq/pull/391)
+- Added documentation for all public modules, classes, and functions in the code base to improve the documentation quality and make it easier to understand how to use the package. [#391](https://github.com/mmschlk/shapiq/pull/391)
+- suppress a ``RuntimeWarning`` in ``Regression`` approximators ``solve_regression()``method when the solver is not able to find good interim solutions for the regression problem.
+- refactors the tests into ``tests_unit/`` and ``tests_integration/`` to better separate unit tests from integration tests. [#395](https://github.com/mmschlk/shapiq/pull/395)
+- adds new integration tests in ``tests/tests_integration/test_explainer_california_housing`` which compares the different explainers against ground-truth interaction values computed by ``shapiq.ExactComputer`` and interaction values stored on [disk](https://github.com/mmschlk/shapiq/tree/main/tests/data/interaction_values/california_housing) as a form of regression test. This test should help finding bugs in the future when the approximators, explainers, or exact computation are changed. [#395](https://github.com/mmschlk/shapiq/pull/395)
+
+#### Bug Fixes
+- fixed a bug in the `shapiq.waterfall_plot` function that caused the plot to not display correctly resulting in cutoff y_ticks. Additionally, the file was renamed from `watefall.py` to `waterfall.py` to match the function name [#377](https://github.com/mmschlk/shapiq/pull/377)
+- fixes a bug with `TabPFNExplainer`, where the model was not able to be used for predictions after it was explained. This was due to the model being fitted on a subset of features, which caused inconsistencies in the model's predictions after explanation. The fix includes that after each call to the `TabPFNImputer.value_function`, the tabpfn model is fitted on the whole dataset (without omitting features). This means that the original model can be used for predictions after it has been explained. [#396](https://github.com/mmschlk/shapiq/issues/396).
+- fixed a bug in computing `BII` or `BV` indices with `shapiq.approximator.MonteCarlo` approximators (affecting `SHAP-IQ`, `SVARM` and `SVARM-IQ`). All orders of BII should now be computed correctly. [#395](https://github.com/mmschlk/shapiq/pull/395)
 
 ### v1.2.3 (2025-03-24)
 - substantially improves the runtime of all `Regression` approximators by a) a faster pre-computation of the regression matrices and b) a faster computation of the weighted least squares regression [#340](https://github.com/mmschlk/shapiq/issues/340)

{shapiq-1.2.3 → shapiq-1.3.0}/README.md

@@ -11,15 +11,21 @@
 [![PePy](https://static.pepy.tech/badge/shapiq?style=flat-square)](https://pepy.tech/project/shapiq)
 
 [![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen)
-![Last Commit](https://img.shields.io/github/last-commit/mmschlk/shapiq)
+[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen)](https://github.com/mmschlk/shapiq/issues)
+[![Last Commit](https://img.shields.io/github/last-commit/mmschlk/shapiq)](https://github.com/mmschlk/shapiq/commits/main)
 
 > 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.10 and above**. Installation can be done via `pip`:
+`shapiq` is intended to work with **Python 3.10 and above**.
+Installation can be done via `uv` :
+```sh
+uv add shapiq
+```
+
+or via `pip`:
 
 ```sh
 pip install shapiq
@@ -33,6 +39,7 @@ If you are interested in the underlying game theoretic algorithms, then check ou
 ### Compute any-order feature interactions
 
 Explain your models with Shapley interactions:
+Just load your data and model, and then use a `shapiq.Explainer` to compute Shapley interactions.
 
 ```python
 import shapiq
@@ -131,7 +138,7 @@ The pseudo-code above can produce the following plot (here also an image is adde
 
 ### Explain TabPFN
 
-With ``shapiq`` you can also [``TabPFN``](https://github.com/PriorLabs/TabPFN) by making use of the _remove-and-recontextualize_ explanation paradigm implemented in ``shapiq.TabPFNExplainer``.
+With ``shapiq`` you can also explain [``TabPFN``](https://github.com/PriorLabs/TabPFN) by making use of the _remove-and-recontextualize_ explanation paradigm implemented in ``shapiq.TabPFNExplainer``.
 
 ```python
 import tabpfn, shapiq
@@ -144,7 +151,7 @@ explainer = shapiq.TabPFNExplainer(   # setup the explainer
     labels=labels,
     index="FSII"
 )
-fsii_values = explainer.explain(X[0])  # explain with Faithful Shapley values
+fsii_values = explainer.explain(data[0])  # explain with Faithful Shapley values
 fsii_values.plot_force()               # plot the force plot
 ```
 
@@ -152,6 +159,28 @@ fsii_values.plot_force()               # plot the force plot
   <img width="800px" src="https://raw.githubusercontent.com/mmschlk/shapiq/main/docs/source/_static/images/fsii_tabpfn_force_plot_example.png" alt="Force Plot of FSII values as derived from the example tabpfn notebook">
 </p>
 
+### Use SPEX (SParse EXplainer) <img src="https://raw.githubusercontent.com/mmschlk/shapiq/main/docs/source/_static/images/spex_logo.png" alt="spex_logo" align="right" height="75px"/>
+For large-scale use-cases you can also check out the [👓``SPEX``](https://shapiq.readthedocs.io/en/latest/api/shapiq.approximator.sparse.html#shapiq.approximator.sparse.SPEX) approximator.
+
+```python
+# load your data and model with large number of features
+data, model, n_features = ...
+
+# use the SPEX approximator directly
+approximator = shapiq.SPEX(n=n_features, index="FBII", max_order=2)
+fbii_scores = approximator.approximate(budget=2000, game=model.predict)
+
+# or use SPEX with an explainer
+explainer = shapiq.Explainer(
+    model=model,
+    data=data,
+    index="FBII",
+    max_order=2,
+    approximator="spex"  # specify SPEX as approximator
+)
+explanation = explainer.explain(data[0])
+```
+
 
 ## 📖 Documentation with tutorials
 The documentation of ``shapiq`` can be found at https://shapiq.readthedocs.io.
@@ -163,7 +192,7 @@ There is a lot of great resources available to get you started with Shapley valu
 If you use ``shapiq`` and enjoy it, please consider citing our [NeurIPS paper](https://arxiv.org/abs/2410.01649) or consider starring this repository.
 
 ```bibtex
-@inproceedings{muschalik2024shapiq,
+@inproceedings{Muschalik.2024b,
   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},

shapiq-1.3.0/pyproject.toml

@@ -0,0 +1,245 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shapiq"
+dynamic = ["version", "readme"]
+description = "Shapley Interactions for Machine Learning"
+requires-python = ">=3.10"
+dependencies = [
+    # core
+    "numpy",
+    "scipy",
+    "pandas",
+    "scikit-learn",
+    "tqdm",
+    "requests",
+    "sparse-transform",
+    "galois",
+    # plotting
+    "matplotlib",
+    "networkx",
+    "colour",
+    "pillow",
+]
+authors = [
+    {name = "Maximilian Muschalik", email = "Maximilian.Muschalik@lmu.de"},
+    {name = "Hubert Baniecki"},
+    {name = "Fabian Fumagalli"},
+]
+maintainers = [
+    {name = "Maximilian Muschalik", email = "Maximilian.Muschalik@lmu.de"},
+]
+license = "MIT"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    'Operating System :: Microsoft :: Windows',
+    'Operating System :: Unix',
+    'Operating System :: MacOS',
+    'Programming Language :: Python :: 3',
+    'Programming Language :: Python :: 3.10',
+    'Programming Language :: Python :: 3.11',
+    'Programming Language :: Python :: 3.12',
+    'Programming Language :: Python :: 3.13',
+]
+keywords = [
+    "python",
+    "machine learning",
+    "interpretable machine learning",
+    "shap",
+    "xai",
+    "explainable ai",
+    "interaction",
+    "shapley interactions",
+    "shapley values",
+    "feature interaction",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["shapiq*"]
+
+[tool.setuptools.dynamic]
+version = {attr = "shapiq.__version__"}
+readme = {file = ["README.md", "CHANGELOG.md"], content-type = "text/markdown"}
+
+[project.urls]
+documentation = "https://shapiq.readthedocs.io"
+source = "https://github.com/mmschlk/shapiq"
+tracker = "https://github.com/mmschlk/shapiq/issues"
+changelog = "https://github.com/mmschlk/shapiq/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+ml = [
+    "tabpfn",
+    "torchvision",
+    "torch",
+    "xgboost",
+    "lightgbm",
+    "transformers",
+    "scikit-image",
+    "joblib",
+    "tensorflow; python_version < '3.13'",
+    "tf-keras; python_version < '3.13'",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+minversion = "8.0"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["tests", "shapiq", "docs"]
+
+
+[tool.ruff.lint]
+# we allow star arguments to be of type Any e.g. def func(*args: Any, **kwargs: Any) -> None: is ok
+flake8-annotations.allow-star-arg-any = true
+select = ["ALL"]
+ignore = [
+    "E501",  # Line too long
+    "N803",  # Variable X in function should be lowercase
+    "N806",  # Variable X in function should be lowercase
+    "S301",  # exclude pickle restriction, atm. games are unpickled this will need to be fixed # TODO: must be fixed in the future
+    "COM812",  # this is redundant with the formatter which anyways does this (must be excluded) in the future # TODO: add remove pickle calls and remove this exclusion
+    "FIX002",  # we use TODOs atm to track potential code improvements  # TODO: add this in the future
+    "PLR0913",  # Too many arguments are passed to function
+    "PLR0915", # Too many statements in function
+    "PLR0912",  # Too many branches in function
+    "PLR2004",  # Magic values in comparison ... this gets flaged with all checks for two-way interactions
+    "C901",  # Too complex functions
+    "PLR0911",  # too many return statements in function
+    "N802",  # Function name should be lowercase
+]
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+    "docs/build",
+]
+
+# Exclude a variety of commonly ignored directories.
+# Note to developers: If you add a new ignore at least put a comment next to it why it is ignored
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = [
+    # "ALL",
+    "S101", # we need asserts in tests
+    "D",    # test docstrings don't matter too much
+    "E501", # line too long
+    "ANN",  # type annotations
+    "ARG",  # some functions are not used
+    "INP",  # inports can be different
+    "N",  # type hints are excludes in tests
+    "PTH",  # we can use os for now
+    "S",  # in tests we can use some security issues for now
+    "PT", # we can use print statements in tests
+    "NPY",
+    "SLF",  # private members are okay in tests
+    "TRY",
+]
+"*.ipynb" = [
+    "E402",  # Module level import not at top of file (its .ipynb)
+    "T20",  # notebooks can have print statements
+    "I002",  # notebooks do not have to import required modules
+    "D",  # docstrings are not required in notebooks
+    "SLF001",  # private members are okay in notebooks
+    "ANN001",  # type annotations are not required in notebooks
+]
+"docs/source/*.py" = [
+    "A001",  # some conf.py variables shadow builtins which is okay here
+    "ANN001",  # some magic functions I don't want to annotate
+    "INP",  # docs can be an implicit package (does not need to be imported)
+    "I002",  # benchmark code does not have to import required modules
+]
+"benchmark/*.py" = [
+    "INP", # imports can be different here
+    "I002",  # benchmark code does not have to import required modules
+    "PTH"  # in benchmark code we use a lot of os, which is okay
+]
+"docs/copy_notebooks.py" = [
+    "PTH",  # the script uses os, which is not cirtical for shapiq so it's fine
+    "I002",  # benchmark code does not have to import required modules
+]
+"__init__.py" = [
+    "I002", # __init__.py does not have to import required modules
+    "RUF022",  # we can have unsorted imports in __init__.py
+    "FA",
+]
+"scripts/*.py" = [
+    "INP", # imports can be different here
+    "I002",  # script code does not have to import required modules
+    "PTH"  # in script code we use a lot of os, which is okay
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = ["shapiq"]
+extra-standard-library = ["typing_extensions"]
+combine-as-imports = true
+force-wrap-aliases = true
+no-lines-before = ["future"]
+required-imports = ["from __future__ import annotations"]
+
+[dependency-groups]
+test = [
+    "pytest>=8.3.5",
+    "pytest-cov>=6.0.0",
+    "pytest-xdist>=3.6.1",
+    "pytest-randomly",
+]
+lint = [
+    "ruff>=0.11.2",
+    "pre-commit>=4.2.0",
+]
+docs = [
+    "sphinx>=8.0.0",
+    "furo",
+    "myst-parser",
+    "sphinx-copybutton",
+    "sphinx-autodoc-typehints",
+    "sphinx_toolbox",
+    "sphinxcontrib-bibtex", # references based on bibtex
+    "nbconvert",
+    "nbsphinx",
+    "commonmark",  # Markdown parser and renderer
+]
+dev = [
+    "build>=1.2.2.post1",
+    "twine>=6.1.0",
+    "notebook>=7.3.3",
+    "ipywidgets",
+    {include-group = "test"},
+    {include-group = "lint"},
+    {include-group = "docs"},
+]

{shapiq-1.2.3 → shapiq-1.3.0}/shapiq/__init__.py

@@ -1,12 +1,15 @@
-"""shapiq is a library creating explanations for machine learning models based on
+"""shapiq: Shapley Interactions for Machine Learning.
+
+shapiq is a library creating explanations for machine learning models based on
 the well established Shapley value and its generalization to interaction.
 """
 
-__version__ = "1.2.3"
+__version__ = "1.3.0"
 
 # approximator classes
 from .approximator import (
     SHAPIQ,
+    SPEX,
     SVARM,
     SVARMIQ,
     InconsistentKernelSHAPIQ,
@@ -40,7 +43,13 @@ from .benchmark import (
 from .datasets import load_adult_census, load_bike_sharing, load_california_housing
 
 # explainer classes
-from .explainer import Explainer, TabPFNExplainer, TabularExplainer, TreeExplainer
+from .explainer import (
+    AgnosticExplainer,
+    Explainer,
+    TabPFNExplainer,
+    TabularExplainer,
+    TreeExplainer,
+)
 
 # exact computer classes
 from .game_theory.exact import ExactComputer
@@ -95,11 +104,13 @@ __all__ = [
     "SVARMIQ",
     "kADDSHAP",
     "UnbiasedKernelSHAP",
+    "SPEX",
     # explainers
     "Explainer",
     "TabularExplainer",
     "TreeExplainer",
     "TabPFNExplainer",
+    "AgnosticExplainer",
     # imputers
     "MarginalImputer",
     "BaselineImputer",

{shapiq-1.2.3 → shapiq-1.3.0}/shapiq/approximator/__init__.py

@@ -1,6 +1,6 @@
 """Approximators to estimate the Shapley interaction values."""
 
-from ._base import Approximator
+from .base import Approximator
 from .marginals import OwenSamplingSV, StratifiedSamplingSV
 from .montecarlo import SHAPIQ, SVARM, SVARMIQ, UnbiasedKernelSHAP
 from .permutation.sii import PermutationSamplingSII
@@ -14,6 +14,7 @@ from .regression import (
     RegressionFSII,
     kADDSHAP,
 )
+from .sparse import SPEX
 
 # contains all SV approximators
 SV_APPROXIMATORS: list[Approximator.__class__] = [
@@ -24,6 +25,7 @@ SV_APPROXIMATORS: list[Approximator.__class__] = [
     PermutationSamplingSV,
     KernelSHAP,
     kADDSHAP,
+    SPEX,
 ]
 
 # contains all SI approximators
@@ -44,6 +46,7 @@ SII_APPROXIMATORS: list[Approximator.__class__] = [
     InconsistentKernelSHAPIQ,
     SVARMIQ,
     SHAPIQ,
+    SPEX,
 ]
 
 # contains all approximators that can be used for STII
@@ -53,6 +56,7 @@ STII_APPROXIMATORS: list[Approximator.__class__] = [
     InconsistentKernelSHAPIQ,
     SVARMIQ,
     SHAPIQ,
+    SPEX,
 ]
 
 # contains all approximators that can be used for FSII
@@ -62,11 +66,13 @@ FSII_APPROXIMATORS: list[Approximator.__class__] = [
     InconsistentKernelSHAPIQ,
     SVARMIQ,
     SHAPIQ,
+    SPEX,
 ]
 
 # contains all approximators that can be used for FBII
 FBII_APPROXIMATORS: list[Approximator.__class__] = [
     RegressionFBII,
+    SPEX,
 ]
 
 __all__ = [
@@ -84,6 +90,7 @@ __all__ = [
     "SVARM",
     "SVARMIQ",
     "kADDSHAP",
+    "SPEX",
     "UnbiasedKernelSHAP",
     "SV_APPROXIMATORS",
     "SI_APPROXIMATORS",
@@ -92,5 +99,3 @@ __all__ = [
     "FSII_APPROXIMATORS",
     "FBII_APPROXIMATORS",
 ]
-
-# Path: shapiq/approximator/__init__.py