v1.3.0 (2025-06-17)

[mmschlk]

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

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

AgnosticExplainer

The shapiq.AgnosticExplainer is a generic explainer that works for any value function or shapiq.Game object, allowing for more flexibility in explainers.

# get your game behavior and pass it to AgnosticExplainer
my_logic = ...

def value_function(coalition: np.ndarray[bool]) -> np.ndarray[float]:
    return my_logic(coalition)

explainer = shapiq.AgnosticExplainer(
    game=value_function,
    index="FSII",
    max_order=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 Relax interaction values #360
• 355 disallow budgetnone in explainer andor other occurrences by @Advueu963 in 355 disallow budgetnone in explainer andor other occurrences #356
• Extends Code Quality Rules by @mmschlk in Extends Code Quality Rules #363
• Enforce "PTH" Linting Rule and Adds UpSet API Example Notebook by @mmschlk in Enforce "PTH" Linting Rule and Adds UpSet API Example Notebook #366
• ⚒️ Extends ruff's formatting ruleset and adds docs dependencies into a uv group by @mmschlk in ⚒️ Extends ruff's formatting ruleset and adds docs dependencies into a uv group #371
• ⚒️ Improves InteractionValues.get_n_order(), Adds Test Fixtures, and new install-import CI Workflow by @mmschlk in ⚒️ Improves InteractionValues.get_n_order(), Adds Test Fixtures, and new install-import CI Workflow #372
• Add extra tree tests by @IsaH57 in Add extra tree tests #373
• Minor Bugfixed for shapiq.waterfall_plot by @Advueu963 in Minor Bugfixed for shapiq.waterfall_plot #377
• Bump astral-sh/setup-uv from 5 to 6 by @dependabot in Bump astral-sh/setup-uv from 5 to 6 #375
• Add the SPEX approximator to shapiq by @justinkang221 in Add the SPEX approximator to shapiq #379
• Docs-update by @mmschlk in Docs-update #383
• Docs-update by @mmschlk in Docs-update #384
• 🛠️ update of ruff-format ruleset to "ALL" by @mmschlk in 🛠️ update of ruff-format ruleset to "ALL" #391
• 📈streamline-network-and-si-grap-plot by @heinzll in 📈streamline-network-and-si-grap-plot #349
• Rename t parameter in SPEX and Sparse by @mmschlk in Rename t parameter in SPEX and Sparse #392
• Add Game.compute function and related test to the Game class by @IsaH57 in Add Game.compute function and related test to the Game class #397
• fixes bug with a TabPFN model not working as intended after explanations by @mmschlk in fixes bug with a TabPFN model not working as intended after explanations #401
• adds AgnosticExplainer and refactors explanation/approximation code by @mmschlk in adds AgnosticExplainer and refactors explanation/approximation code #395
• Add references with sphinxcontrib-bibtex by @pwhofman in Add references with sphinxcontrib-bibtex #394
• shapiq 1.3.0 release by @mmschlk in shapiq 1.3.0 release #402

New Contributors

• @IsaH57 made their first contribution in Add extra tree tests #373
• @justinkang221 made their first contribution in Add the SPEX approximator to shapiq #379

Full Changelog: v.1.2.3...v1.3.0

---

This discussion was created from the release v1.3.0 (2025-06-17).