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:

image

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 spex_logo

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]) ```

spec_results

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.sparse for efficient computation of sparse interaction values #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, #395
  • changes budget to be a mandatory parameter given to the TabularExplainer.explain() method #355
  • 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
  • renamed min_percentage parameter in the force plot to contribution_threshold to better reflect its purpose #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
  • 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
  • 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
  • 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
  • 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

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
  • 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
  • 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
  • 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
  • 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 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
  • 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 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_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
  • 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.
  • 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

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 t parameter in SPEX and Sparse by @mmschlk in https://github.com/mmschlk/shapiq/pull/392
  • Add Game.compute function 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 AgnosticExplainer and 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 Regression approximator

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.TabPFNExplainer as a specialized version of the shapiq.TabularExplainer which offers a streamlined variant of the explainer for the TabPFN model #301
  • adds a TabPFN example notebook to the documentation
  • adds the sentence_plot function to the plot module 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_plot function to the plot module 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 a explain_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_fun parameter in shapiq.ExactComputer to game #297
  • refactors game theory computations like ExactComputer, MoebiusConverter, core, among others to be more modular and flexible into the game_theory module #258
  • removes warning when class_index is not provided in explainers #298
  • makes abbreviations in the plot module 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_index parameter to TabularExplainer and Explainer to specify the class index to be explained for classification models #271 (renames class_label parameter in TreeExplainer to class_index)
  • adds support for PyTorch models to Explainer #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

- 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 the ExactComputer #182
  • adds waterfall_plot #34 that visualizes the contributions of features to the model prediction
  • adds BaselineImputer #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
  • 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
  • add a legend to benchmark plots #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 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
  • 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.Game API 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 TreeExplainer did 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=1 to TabularExplainer and TreeExplainer
  • 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):

  • 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

- 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

shapiq - 0.0.2

Adds network plot functionality and updates docs. This release is mainly used to test the workflows and publish of docs and automatic update to pypi.

- Python
Published by mmschlk over 2 years ago