Recent Releases of shapiq
shapiq - v1.3.1 (2025-07-11)
Overview
Beesvarm Plot
This release adds the beewarm_plot plot to shapiq and extends it to also visualize interactions.
Beeswarm plots are useful in visualizing dependencies between feature values and feature importance. The beeswarm plot was adapted from the SHAP library by sub-dividing the y-axis for each interaction term: - An interaction term (e.g., "Feature A x Feature B") will occupy a "block" on the y-axis. - This block will be subdivided into multiple rows: one for each feature within the interaction. - For the interaction (A, B): * There will be a sub-row for Feature A. The x-position of every dot in this row will be the interaction value for that sample, but the color of the dot will be determined by the value of Feature A. * There will be another sub-row for Feature B. The x-position of the dots is the same, but the color will be determined by the value of Feature B
Example of such plot looks like this:
JSON Support
This release also adds JSON support for serializing objects. This is important for saving and loading files which are human-readable also in raw format to improve safety of the library. This also allows us to refactor some data structures in the future with a fallback version (this version) to store older value objects in the new file format.
New Contributors
- @annprzy made their first contribution in https://github.com/mmschlk/shapiq/pull/406
Full Changelog: https://github.com/mmschlk/shapiq/compare/v1.3.0...v1.3.1
- Python
Published by mmschlk 8 months ago
shapiq - v1.3.0 (2025-06-17)
Below you find the reals notes for shapiq version 1.3.0.
✨Highlights
SPEX (SParse EXplainer) by @justinkang221 and @landonbutler 
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
```python
load your data and model with large number of features
data, model, n_features = ...
use the SPEX approximator directly
approximator = shapiq.SPEX(n=nfeatures, index="FBII", maxorder=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]) ```
AgnosticExplainer
The shapiq.AgnosticExplainer is a generic explainer that works for any value function or shapiq.Game object, allowing for more flexibility in explainers.
```python
get your game behavior and pass it to AgnosticExplainer
my_logic = ...
def valuefunction(coalition: np.ndarray[bool]) -> np.ndarray[float]: return mylogic(coalition)
explainer = shapiq.AgnosticExplainer( game=valuefunction, index="FSII", maxorder=2, approximator="auto" ) explanation = explainer.explain(budget=100) ```
Full Changelog
New Features
- adds the SPEX (Sparse Exact) module in
approximator.sparsefor efficient computation of sparse interaction values #379 - adds
shapiq.AgnosticExplainerwhich is a generic explainer that can be used for any value function orshapiq.Gameobject. This allows for more flexibility in the explainers. #100, #395 - changes
budgetto be a mandatory parameter given to theTabularExplainer.explain()method #355 - changes logic of
InteractionValues.get_n_order()function to be callable with either theorder: intparameter and optional assignment ofmin_order: intandmax_order: intparameters or with the min/max order parameters #372 - renamed
min_percentageparameter in the force plot tocontribution_thresholdto better reflect its purpose #391 - adds
verboseparameter to theExplainer'sexplain_X()method to control weather a progress bar is shown or not which is defaulted toFalse. #391 - made
InteractionValues.get_n_order()andInteractionValues.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 fromTreeExplainer). Note, this change does not really helpget_n_order_values()as it still needs to create a numpy array of shapen_playerstimesorder#372 - streamlined the
network_plot()plot function to use thesi_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, thesi_graph_plotwas modified to make plotting more easy and allow for more flexibility with new parameters. #349 - adds
Game.compute()method to theshapiq.Gameclass to compute game values without changing the state of the game object. The compute method also introduces ashapiq.utils.sets.generate_interaction_lookup_from_coalitions()utility method which creates an interaction lookup dict from an array of coalitions. #397 - streamlines the creation of network plots and graph plots which now uses the same backend. The network plot via
shapiq.network_plot()orInteractionValues.plot_network()is now a special case of theshapiq.si_graph_plot()andInteractionValues.plot_si_graph(). This allows to create more beautiful plots and easier maintenance in the future. #349
Testing, Code-Quality and Documentation
- activates
"ALL"rules inruff-formatconfiguration to enforce stricter code quality checks and addressed around 500 (not automatically solvable) issues in the code base. #391 - improved the testing environment by adding a new fixture module containing mock
InteractionValuesobjects to be used in the tests. This allows for more efficient and cleaner tests, as well as easier debugging of the tests #372 - removed check and error message if the
indexparameter is not in the list of available indices in theTabularExplainersince the type hints were replaced by Literals #391 - removed multiple instances where
shapiqtests 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 - 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
- suppress a
RuntimeWarninginRegressionapproximatorssolve_regression()method when the solver is not able to find good interim solutions for the regression problem. - refactors the tests into
tests_unit/andtests_integration/to better separate unit tests from integration tests. #395 - adds new integration tests in
tests/tests_integration/test_explainer_california_housingwhich compares the different explainers against ground-truth interaction values computed byshapiq.ExactComputerand interaction values stored on disk 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
Bug Fixes
- fixed a bug in the
shapiq.waterfall_plotfunction that caused the plot to not display correctly resulting in cutoff y_ticks. Additionally, the file was renamed fromwatefall.pytowaterfall.pyto match the function name #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 theTabPFNImputer.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. - fixed a bug in computing
BIIorBVindices withshapiq.approximator.MonteCarloapproximators (affectingSHAP-IQ,SVARMandSVARM-IQ). All orders of BII should now be computed correctly. #395
Autogenerated Notes
- Relax interaction values by @hbaniecki in https://github.com/mmschlk/shapiq/pull/360
- 355 disallow budgetnone in explainer andor other occurrences by @Advueu963 in https://github.com/mmschlk/shapiq/pull/356
- Extends Code Quality Rules by @mmschlk in https://github.com/mmschlk/shapiq/pull/363
- Enforce "PTH" Linting Rule and Adds UpSet API Example Notebook by @mmschlk in https://github.com/mmschlk/shapiq/pull/366
- ⚒️ Extends ruff's formatting ruleset and adds docs dependencies into a uv group by @mmschlk in https://github.com/mmschlk/shapiq/pull/371
- ⚒️ Improves
InteractionValues.get_n_order(), Adds Test Fixtures, and new install-import CI Workflow by @mmschlk in https://github.com/mmschlk/shapiq/pull/372 - Add extra tree tests by @IsaH57 in https://github.com/mmschlk/shapiq/pull/373
- Minor Bugfixed for shapiq.waterfall_plot by @Advueu963 in https://github.com/mmschlk/shapiq/pull/377
- Bump astral-sh/setup-uv from 5 to 6 by @dependabot in https://github.com/mmschlk/shapiq/pull/375
- Add the SPEX approximator to shapiq by @justinkang221 in https://github.com/mmschlk/shapiq/pull/379
- Docs-update by @mmschlk in https://github.com/mmschlk/shapiq/pull/383
- Docs-update by @mmschlk in https://github.com/mmschlk/shapiq/pull/384
- 🛠️ update of ruff-format ruleset to
"ALL"by @mmschlk in https://github.com/mmschlk/shapiq/pull/391 - 📈streamline-network-and-si-grap-plot by @heinzll in https://github.com/mmschlk/shapiq/pull/349
- Rename
tparameter in SPEX and Sparse by @mmschlk in https://github.com/mmschlk/shapiq/pull/392 - Add
Game.computefunction and related test to the Game class by @IsaH57 in https://github.com/mmschlk/shapiq/pull/397 - fixes bug with a TabPFN model not working as intended after explanations by @mmschlk in https://github.com/mmschlk/shapiq/pull/401
- adds
AgnosticExplainerand refactors explanation/approximation code by @mmschlk in https://github.com/mmschlk/shapiq/pull/395 - Add references with sphinxcontrib-bibtex by @pwhofman in https://github.com/mmschlk/shapiq/pull/394
- shapiq 1.3.0 release by @mmschlk in https://github.com/mmschlk/shapiq/pull/402
New Contributors
- @IsaH57 made their first contribution in https://github.com/mmschlk/shapiq/pull/373
- @justinkang221 made their first contribution in https://github.com/mmschlk/shapiq/pull/379
Full Changelog: https://github.com/mmschlk/shapiq/compare/v.1.2.3...v1.3.0
- Python
Published by mmschlk 8 months ago
shapiq - v1.2.3
Coolest Things
- Much quicker regression (we basically did something very slow before but now its cool, see https://github.com/mmschlk/shapiq/issues/340)
- RegresseionFBII approximation, you can now also compute values for FBII scores through the
Regressionapproximator
What's Changed
- Improve testing by @mmschlk in https://github.com/mmschlk/shapiq/pull/332
- Adds trivial TreeExplainer computation and fixes a Bug in parsing xgboost models. by @mmschlk in https://github.com/mmschlk/shapiq/pull/334
- bug fix for stacked_bar plot by @Advueu963 in https://github.com/mmschlk/shapiq/pull/335
- fixes #336 by @mmschlk in https://github.com/mmschlk/shapiq/pull/337
- 331 adding faith banzhaf approximator by @Advueu963 in https://github.com/mmschlk/shapiq/pull/333
- 🚀 Optimizes Regression Estimator Runtime by @mmschlk in https://github.com/mmschlk/shapiq/pull/341
- fix missing import for regressionfbii by @hbaniecki in https://github.com/mmschlk/shapiq/pull/342
- Bump numpy from 1.26.4 to 2.1.2 by @dependabot in https://github.com/mmschlk/shapiq/pull/246
- ⚒️ Reduce package clutter and adds uv by @mmschlk in https://github.com/mmschlk/shapiq/pull/348
- Update Test Structure to use uv by @mmschlk in https://github.com/mmschlk/shapiq/pull/350
- 🏷️ Create v1.2.3 Release by @mmschlk in https://github.com/mmschlk/shapiq/pull/351
Full Changelog: https://github.com/mmschlk/shapiq/compare/v1.2.2...v.1.2.3
- Python
Published by mmschlk 11 months ago
shapiq - v1.2.2
What's Changed
- Fix Package Import without Write Access by @mmschlk in https://github.com/mmschlk/shapiq/pull/327
- 291 Change the Supported Python Versions to 3.10-3.13 by @Advueu963 in https://github.com/mmschlk/shapiq/pull/318
- Adding Scikit-Learn ExtraTreesRegressor to allowed models for TreeExplainer by @Deathn0t in https://github.com/mmschlk/shapiq/pull/309
- Moved legends in network plot to not coincide by @chenhao20241224 in https://github.com/mmschlk/shapiq/pull/329
- Bump the pip-all-updates group with 8 updates by @dependabot in https://github.com/mmschlk/shapiq/pull/328
New Contributors
- @Deathn0t made their first contribution in https://github.com/mmschlk/shapiq/pull/309
- @chenhao20241224 made their first contribution in https://github.com/mmschlk/shapiq/pull/329
Full Changelog: https://github.com/mmschlk/shapiq/compare/v1.2.1...v1.2.2
- Python
Published by mmschlk 12 months ago
shapiq - v1.2.1 (2024-02-17)
This Release contains a couple of bug fixes and little improvements.
What's Changed
- Fix TreeExplainer instanciation when a tree in LightGBM Classifier model has nfeaturesin_tree = 1 by @CharlesCousyn in https://github.com/mmschlk/shapiq/pull/310
- Bump the pip-all-updates group with 9 updates by @dependabot in https://github.com/mmschlk/shapiq/pull/312
- 316 fix bar and force plotting by @Advueu963 in https://github.com/mmschlk/shapiq/pull/317
- Bump pypa/gh-action-pypi-publish from 1.12.3 to 1.12.4 by @dependabot in https://github.com/mmschlk/shapiq/pull/311
- fixes for #324, #322, #319 by @hbaniecki in https://github.com/mmschlk/shapiq/pull/323
New Contributors
- @CharlesCousyn made their first contribution in https://github.com/mmschlk/shapiq/pull/310
Full Changelog: https://github.com/mmschlk/shapiq/compare/v1.2.0...v1.2.1
- Python
Published by mmschlk about 1 year ago
shapiq - v1.2.0 (2024-11-15)
New Features
- adds
shapiq.TabPFNExplaineras a specialized version of theshapiq.TabularExplainerwhich offers a streamlined variant of the explainer for the TabPFN model #301 - adds a TabPFN example notebook to the documentation
- adds the
sentence_plotfunction to theplotmodule to visualize the contributions of words to a language model prediction in a sentence-like format - adds support for IsoForest models to explainer and tree explainer #278
- adds the
upset_plotfunction to theplotmodule to visualize the interactions of higher-order #290
API Enhancements
- handles
explainer.explain()now through a common interface for all explainer classes which now need to implement aexplain_function()method - adds the baselinevalue into the InteractionValues object's value storage for the
()interaction if ``minorder=0(default usually) for all indices that are notSII```(SII has another baseline value) such that the values are efficient (sum up to the model prediction) without the awkward handling of the baseline_value attribute - renames
game_funparameter inshapiq.ExactComputertogame#297 - refactors game theory computations like
ExactComputer,MoebiusConverter,core, among others to be more modular and flexible into thegame_theorymodule #258 - removes warning when class_index is not provided in explainers #298
- makes abbreviations in the
plotmodule optional #281 - adds support for sub-selection of players in the interaction values data class #276 which allows retrieving interaction values for a subset of players
Tests Enhancements
- improves quality of the tests by adding many more semantic tests to the different interaction indices and computations #285
New Contributors
- @JuliaHerbinger made their first contribution in https://github.com/mmschlk/shapiq/pull/287
- @r-visser made their first contribution in https://github.com/mmschlk/shapiq/pull/289
- @heinzll made their first contribution in https://github.com/mmschlk/shapiq/pull/285
Full Changelog: https://github.com/mmschlk/shapiq/compare/v1.1.1...v1.2.0
- Python
Published by mmschlk about 1 year ago
shapiq - v1.1.1 (2024-11-13)
Improvements and Ease of Use
- adds a
class_indexparameter toTabularExplainerandExplainerto specify the class index to be explained for classification models #271 (renamesclass_labelparameter in TreeExplainer toclass_index) - adds support for
PyTorchmodels toExplainer#272 - adds new tests comparing
shapiqoutputs for SVs with alues computed withshap - adds new tests for checking
shapiqexplainers with different types of models
Bug Fixes
- fixes a bug that
RandomForestClassifiermodels were not working with theTreeExplainer#273
- Python
Published by mmschlk over 1 year ago
shapiq - v1.1.0 (2024-11-07)
New Features and Improvements
- adds computation of the Egalitarian Core (
EC) and Egalitarian Least-Core (ELC) to theExactComputer#182 - adds
waterfall_plot#34 that visualizes the contributions of features to the model prediction - adds
BaselineImputer#107 which is now responsible for handling thesample_replacementsparameter. Added a DeprecationWarning for the parameter inMarginalImputer, which will be removed in the next release. - adds
joint_marginal_distributionparameter toMarginalImputerwith default valueTrue#261 - renames explanation graph to
si_graph get_n_ordernow 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
- add a legend to benchmark plots #170
- refactored the
shapiq.games.benchmarkmodule into a separateshapiq.benchmarkmodule by moving all but the benchmark games into the new module. This closes #169 and makes benchmarking more flexible and convenient. - a
shapiq.Gamecan now be called more intuitively with coalitions data types (tuples of int or str) and also allows to addplayer_namesto the game at initialization #183 - improve tests across the package
Documentation
- adds a notebook showing how to use custom tree models with the
TreeExplainer#66 - adds a notebook show how to use the
shapiq.GameAPI to create custom games #184 - adds a notebook showing hot to visualize interactions #252
- adds a notebook showing how to compute Shapley values with
shapiq#193 - adds a notebook for conducting data valuation #190
- adds a notebook showcasing introducing the Core and how to compute it with
shapiq#191
Bug Fixes
- fixes a bug with SIs not adding up to the model prediction because of wrong values in the empty set #264
- fixes a bug that
TreeExplainerdid not have the correct baseline_value when using XGBoost models #250 - fixes the force plot not showing and its baseline value
New Contributors
- @Advueu963 made their first contribution in https://github.com/mmschlk/shapiq/pull/185
- @dependabot made their first contribution in https://github.com/mmschlk/shapiq/pull/200
Full Changelog: https://github.com/mmschlk/shapiq/compare/v1.0.1...v1.1.0
- Python
Published by mmschlk over 1 year ago
shapiq - v1.0.1 (2024-06-05)
- add
max_order=1toTabularExplainerandTreeExplainer - fix
TreeExplainer.explain_X(..., n_jobs=2, random_state=0)
- Python
Published by hbaniecki over 1 year ago
shapiq - shapiq v1.0.0 (2024-06-04)
Major release of the shapiq Python package including (among others):
approximatormodule implements over 10 approximators of Shapley values and interaction indices.exactmodule implements a computer for over 10 game theoretic concepts like interaction indices or generalized values.gamesmodule implements over 10 application benchmarks for the approximators.explainermodule includes aTabularExplainerandTreeExplainerfor any-order feature interactions of machine learning model predictions.interaction_valuesmodule implements a data class to store and analyze interaction values.plotmodule allows visualizing interaction values.datasetsmodule loads datasets for testing and examples.
Documentation of shapiq with tutorials and API reference is available at https://shapiq.readthedocs.io
- Python
Published by hbaniecki over 1 year ago
shapiq - Update v.0.0.6-alpha
Highlights
The highlights of this release are as follows.
Random Forest Support for TreeExplainer
We add support for RandomForestClassifier and RandomForestRegressor as provided by sklearn.ensemble in the TreeExplainer. This is discussed in #55.
TreeExplainer Bugfix
We fix a package-breaking bug that made it impossible to use the TreeExplainer class.
Additional Unittests
We add additional unittests that fully covers the TreeExplainer in its current form.
What's Changed
- Bugfix and Support for Random Forests in TreeExplainer by @mmschlk in https://github.com/mmschlk/shapiq/pull/59
Full Changelog: https://github.com/mmschlk/shapiq/compare/v.0.0.5-alpha...v.0.0.6-alpha
- Python
Published by mmschlk almost 2 years ago
shapiq - Update v.0.0.5-alpha
Highlights
Since the last release already is some time back, lot's has changed. The highlights are as follows:
TreeExplainer based on TreeSHAP-IQ
shapiq now is equipped with a TreeExplainer. The TreeExplainer is based on the TreeSHAP-IQ algorithm proposed in this paper. It is a model-specific method to compute Shapley interactions of all kinds and any-order. Since it is based on the linear TreeSHAP algorithm it is quite fast. The work is not yet finished on the TreeExplainer, since it only accepts very basic tree models from sklearn as input. More to follow on this front.
The first visualizations are added.
We added a new plot to the visualizations: the stacked bar chart (underwhelming name). This plot is illustrated in the TreeSHAP-IQ paper and Sebastian Bordt and Ulrike von Luxburg's AISTATS paper. The stacked bar charts shows how much interaction is present in a specific instance and is based on the k-SII values.
Major Refactoring
The codebase has changed quite drastically and many objects have been renamed (e.g. InteractionExplainer has been renamed to Tabular Explainer to better fit the more specific intend of this class). The InteractionValues (the main data structure of the package) has become much more powerful. You can now multiply scalar values to the interaction scores and even add two objects together.
Welcoming new Collaborators
We still are looking for all the help that we can get! If you want to contribute please check out the tutorial and our project.
What's Changed
- Add nSII and SII Regression Estimator by @mmschlk in https://github.com/mmschlk/shapiq/pull/22
- Merge Dev by @mmschlk in https://github.com/mmschlk/shapiq/pull/23
- Add initial explainer. by @mmschlk in https://github.com/mmschlk/shapiq/pull/25
- Development by @mmschlk in https://github.com/mmschlk/shapiq/pull/27
- Merge by @mmschlk in https://github.com/mmschlk/shapiq/pull/28
- Add additional Tests by @mmschlk in https://github.com/mmschlk/shapiq/pull/29
- Adds Stacked Bar Plot and tidyies up Network Plot. by @mmschlk in https://github.com/mmschlk/shapiq/pull/41
- Renamed nSII to k-SII and refactors base approximators by @mmschlk in https://github.com/mmschlk/shapiq/pull/42
- Add Collaborator Tutorial and Code of Conduct by @mmschlk in https://github.com/mmschlk/shapiq/pull/46
- adds code-quality check and closes #45 by @mmschlk in https://github.com/mmschlk/shapiq/pull/47
- adds TreeExplainer with TreeSHAP-IQ by @mmschlk in https://github.com/mmschlk/shapiq/pull/51
Full Changelog: https://github.com/mmschlk/shapiq/compare/v.0.0.4-alpha...v.0.0.5-alpha
- Python
Published by mmschlk almost 2 years ago
shapiq - Update v.0.0.4-alpha
New Approximators
This release adds new approximation methods to shapiq and makes all interaction calculations faster and more memory efficient.
ShapIQ approximator
This release adds the shapiq.approximator.ShapIQ approximator as proposed in this paper (NeurIPS'23).
ShapIQ can approximate any cardinal interaction index (CII) like the Shapley Interaction Index (SII), the Shapley Taylor Index (STI), or the Faithful Shapley Interaction index (FSI).
Regression Estimator for FSI
The shapiq.approximator.RegressionFSI regression estimator, which is only available for FSI, was proposed in this paper (JMLR'23). It is similar to KernelSHAP in that it leverages a weighted least squares representation for the interaction index and solves this by estimating this regression problem.
Permutation Sampling for STI
The permutation sampling currently implemented for the SII (shapiq.approximator.PermutationSamplingSII) can also be extended to the STI. The new shapiq.approximator.PermutationSamplingSTI uses the traditional permutation sampling approach to compute STI scores.
List of PRs
- Add FSI and STI approximation methods by @mmschlk in https://github.com/mmschlk/shapiq/pull/7
- Add SHAP-IQ approximator by @mmschlk in https://github.com/mmschlk/shapiq/pull/10
- Tests and Efficiency by @mmschlk in https://github.com/mmschlk/shapiq/pull/18
- Updates docs. by @mmschlk in https://github.com/mmschlk/shapiq/pull/20
Full Changelog: https://github.com/mmschlk/shapiq/compare/v0.0.3-alpha...v.0.0.4-alpha
- Python
Published by mmschlk about 2 years ago
shapiq - Update v.0.0.3-alpha
What's Changed
- Development by @mmschlk in https://github.com/mmschlk/shapiq/pull/6
- Development by @FFmgll in 7e5bc062a91b3a12b45d262761ffb663353a4bf4
New Contributors
- @mmschlk made their first contribution in https://github.com/mmschlk/shapiq/pull/6
- @FFmgll made their first contribution in 7e5bc062a91b3a12b45d262761ffb663353a4bf4
Full Changelog: https://github.com/mmschlk/shapiq/compare/v0.0.2-alpha...v0.0.3-alpha
- Python
Published by mmschlk over 2 years ago