Shapley Interactions for Machine Learning¶
shapiq explains machine learning models with Shapley values and Shapley
interactions. Shapley values split a prediction fairly among the features; Shapley
interactions also credit the groups of features that act together, such as latitude and
longitude that only together locate a house.
Exact algorithms for tree ensembles, nearest neighbors, and kernel methods, more than twenty approximators for any model, and games and benchmarks for research on cooperative game theory in machine learning.
Explaining Vision-Language Models¶
Which words go with which parts of the image? shapiq explains how well SigLIP 2
[Tschannen et al., 2025] and CLIP [Radford et al., 2021] match a photo and its caption by the
interactions of image regions and words, as in FIxLIP [Baniecki et al., 2025a], approximated
with ProxySHAP [Thies et al., 2026]. More about this demo.
Install¶
pip install shapiq
uv add shapiq
pip install git+https://github.com/mmschlk/shapiq
Extras such as shapiq[tree] add a faster tree backend, more approximators, and the
dependencies of the games and the benchmark: see Installation.
Explain a Prediction¶
Train a model, pick an index and an order, and explain a prediction. For a random forest,
Explainer computes the values exactly with the
TreeExplainer.
from sklearn.datasets import fetch_california_housing
from sklearn.ensemble import RandomForestRegressor
import shapiq
X, y = fetch_california_housing(return_X_y=True)
model = RandomForestRegressor(n_estimators=50, max_depth=10, random_state=0).fit(X, y)
# pairwise Shapley interactions (k-SII up to order 2) of the first house
explainer = shapiq.Explainer(model, data=X, index="k-SII", max_order=2)
interaction_values = explainer.explain(X[0])
print(interaction_values)
interaction_values.plot_force()
InteractionValues(
index=k-SII, max_order=2, min_order=0, estimated=False, estimation_budget=None,
n_players=8, baseline_value=2.0674158944573646,
Top 10 interactions:
(0,): 2.266025054354417
(): 2.0674158944573646
(7,): 0.2783641039520189
(0, 1): 0.2572118576963052
(1,): 0.13368765294448415
(1, 7): -0.06216726789294137
(1, 6): -0.06654762058114373
(6,): -0.0890745350881206
(0, 6): -0.1877658520839556
(0, 7): -0.20161040935064278
)
The tuples are the players (features): (0,) is the effect of the median income alone,
(0, 1) the interaction of the median income and the house age. The Quickstart
explains any model, plots the values, and computes values of games.
Why Shapley Interactions?¶
A Shapley value is one number per feature that mixes the feature’s own effect with its joint effects with other features. Shapley interactions separate them. For a house in San Francisco, the Shapley values credit latitude and longitude separately; the interactions of order 2 show that latitude matters only together with longitude, as the location of the house.
The predicted price of a house explained with Shapley values (top) and with Shapley interactions of order 2 (bottom). Read more in What Are Shapley Interactions?.¶
What’s Inside¶
Three packages, installed together:
Explainers for any model, exact algorithms for trees, nearest neighbors, and kernel methods, approximators, imputers, and plots.
Cooperative games to explain, value, and select: synthetic games with known values, model-specific games, and machine learning games.
Benchmarks with exact ground truth: games built from datasets and models, error and ranking metrics, and a runner for approximators.
Explore the Examples¶
Shapley values and interactions of a scikit-learn model, and your own games.
Every index of a small game exactly, with the Möbius transform and the core.
Shapley values and interactions of large games within a budget of evaluations.
Exact values and interactions of scikit-learn, XGBoost, LightGBM, and CatBoost trees.
Exact values and interactions of the nodes of graph neural networks with GraphSHAP-IQ.
Exact data valuation and explanations of nearest-neighbor models.
Exact Shapley values of Gaussian processes and other product-kernel models.
Force, waterfall, bar, beeswarm, scatter, network, SI graph, and UpSet plots.
TabPFN, language models, and causal effects.
The games of shapiq_games and benchmarks of approximators.
More details, such as imputers and parallel computation, are in Technicalities; all groups are listed in Examples & Tutorials.
Learn More¶
What Shapley interactions are, and when they tell more than Shapley values.
Shapley-based methods for machine learning, from the Shapley value to today.
The papers behind the methods of shapiq, and related software.
Cite shapiq¶
If you enjoy using shapiq, please consider citing our NeurIPS paper [Muschalik et al., 2024a].
BibTeX
@inproceedings{muschalik2024shapiq,
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},
booktitle = {The Thirty-eight Conference on Neural Information Processing Systems Datasets and Benchmarks Track},
year = {2024},
url = {https://openreview.net/forum?id=knxGmi6SJi}
}