Shapley Interaction Quantification (shapiq): Extending SHAP with Interaction Effects
shapiq is a Python library designed to compute Shapley values and Shapley interactions, providing a deeper understanding of how features jointly influence predictions in machine learning models. Unlike traditional SHAP (SHapley Additive exPlanations), which focuses on individual feature contributions, shapiq extends this framework to quantify interaction effects between features, data points, or weak learners in ensemble models. This capability is particularly valuable for models where feature interactions play a critical role in decision-making, such as tree-based models, neural networks, or ensemble methods.
The library is built on game-theoretic foundations, where features or entities are treated as players in a cooperative game. Shapley interactions measure the synergy or redundancy between these players, offering a more comprehensive explanation of model behavior. For example, while SHAP might attribute a prediction to individual features like 'age' or 'income,' shapiq can reveal how 'age' and 'income' interact to jointly influence the outcome, such as a negative interaction where higher income reduces the impact of age on a prediction.
shapiq is developed by Maximilian Muschalik and collaborators at LMU Munich and is openly available under the MIT License, ensuring accessibility for both researchers and practitioners. The library is actively maintained, with recent updates introducing optimizations for tree-based models, new approximators for large-scale datasets, and enhanced visualization tools.
How It Works
shapiq operates by approximating Shapley interactions of any order, meaning it can capture interactions between two features (second-order), three features (third-order), and so on.
Core Components
- For instance, TabularExplainer is designed for tabular data, while TreeExplainer optimizes explanations for tree-based models like Random Forests, XGBoost, LightGBM, or CatBoost.
- Approximation Algorithms: Computing exact Shapley interactions is computationally expensive, especially for high-order interactions or large feature sets. shapiq addresses this with approximation algorithms such as ProxySPEX, ShaplEIG, and OddSHAP. These methods use techniques like Bayesian experimental design, sparse interaction screening, and Fourier regression to efficiently estimate interactions without exhaustive computation.
- Game-Theoretic Benchmarking: The library includes modules for benchmarking game-theoretic algorithms, allowing researchers to compare the performance of different Shapley value approximation methods.
- Visualization Tools: shapiq offers visualization methods like networkplot and plotforce to represent interaction effects. For example, networkplot displays features as nodes and interactions as edges, with node and edge sizes proportional to the magnitude of attributions and interactions, respectively.
Key Algorithms and Approximators
Recent versions of shapiq have introduced several advanced algorithms to improve performance and scalability:
- Woodelf-IQ Integration: This integration leverages the Woodelf algorithm, which computes explanations in a fully vectorized manner over all explained instances and reference rows. It scales favorably with large datasets and supports Shapley values, interaction indices (SII, k-SII), and Banzhaf values (BV, BII). The algorithm is automatically selected based on the size of the input, with a fallback to shapiq’s native implementation if Woodelf is unavailable.
- QuadratureTreeSHAP: This algorithm replaces older polynomial-based methods for tree-based models, offering numerical stability at any tree depth and improved speed. It is used in mode='pathdependent' for computing explanations by tracing the decision paths through the tree.
- ShaplEIG: A Bayesian experimental design approximator that uses Gaussian process surrogates to estimate Shapley values efficiently. It avoids enumerating the full coalition space by leveraging elementary-symmetric-polynomial identities, making it suitable for high-dimensional feature sets.
- It combines paired sampling, sparse interaction screening via surrogate tree models, and constrained Fourier regression to enforce efficiency axioms exactly.
- They use proxy models (e.g., LightGBM, XGBoost, or scikit-learn decision trees) to approximate Shapley interactions, with support for hyperparameter optimization to improve accuracy.
Installation and Compatibility
shapiq is compatible with Python 3.12 and above. It can be installed via pip or uv using the following commands:
- pip install shapiq for basic functionality.
- pip install shapiq[tree] to enable Woodelf-IQ integration for tree-based models.
- pip install shapiq[shapleig] to use the ShaplEIG approximator, which requires additional dependencies like torch, gpytorch, and botorch.
The library is designed to work seamlessly with existing machine learning workflows, particularly those using scikit-learn, XGBoost, LightGBM, or CatBoost. It also supports custom models and ensemble methods, making it versatile for a wide range of applications.
Use Cases
shapiq is particularly useful in scenarios where understanding feature interactions is critical for model interpretability and decision-making.
Model Explainability for Tabular Data
For tabular datasets, shapiq can explain predictions by computing Shapley interactions up to any specified order. This is demonstrated in the quickstart example provided in the documentation, where a TabularExplainer is used to compute interactions up to the fourth order for a California housing dataset.
The output includes both individual Shapley values and interaction values, such as the attribution of feature 0 (e.g., 'MedInc') and interactions like (0, 5) or (0, 1, 5). Negative interactions, such as (0, 3, 6), indicate that the combined effect of these features reduces the prediction compared to their individual contributions. This level of detail helps stakeholders identify synergistic or antagonistic relationships between features.
Tree-Based Model Interpretability
Tree-based models, such as Random Forests or Gradient Boosting Machines, are widely used due to their interpretability and performance. However, their explanations often focus on individual feature importance rather than interactions. shapiq addresses this by providing specialized explainers like TreeExplainer, which supports both path-dependent and interventional modes.
In path-dependent mode, explanations are computed using the QuadratureTreeSHAP algorithm, which traces the decision paths through the tree to compute Shapley values and interactions. This method is numerically stable and efficient, even for deep trees. In interventional mode, smaller inputs use InterventionalTreeSHAPIQ, while larger inputs leverage the vectorized Woodelf algorithm for scalability.
Large-Scale and High-Dimensional Data
For datasets with a large number of features (e.g., genomics, NLP, or recommendation systems), exact computation of Shapley interactions is often infeasible due to combinatorial explosion. shapiq provides approximators like ProxySPEX and ShaplEIG to handle such cases efficiently.
Similarly, ShaplEIG uses Bayesian experimental design to iteratively refine Shapley value estimates, balancing accuracy and computational cost.
Explaining TabPFN Models
This is particularly useful for biologists or researchers who need to understand the complex relationships in high-dimensional biological data.
Benchmarking Game-Theoretic Algorithms
Researchers working on game theory in machine learning can use shapiq to benchmark the performance of different Shapley value approximation algorithms. The library includes modules for setting up benchmark games and comparing algorithms based on metrics like computational efficiency, accuracy, and scalability.
Key Features and Capabilities
shapiq offers a range of features that distinguish it from other explainability tools, particularly in its ability to quantify interaction effects and scale to large datasets.
Support for Any-Order Shapley Interactions
Unlike traditional SHAP, which is limited to first-order effects, shapiq can compute interactions of any order. This means it can capture complex relationships between features, such as three-way or four-way interactions, which are often critical in real-world datasets.
Integration with Popular Machine Learning Libraries
shapiq is designed to work seamlessly with widely used machine learning libraries, including scikit-learn, XGBoost, LightGBM, and CatBoost.
For tree-based models, shapiq provides optimized explainers like TreeExplainer, which automatically selects the most efficient algorithm based on the model type and input size. This includes support for both path-dependent and interventional explanation modes, catering to different interpretability needs.
Advanced Approximation Methods
Given the computational challenges of exact Shapley interaction computation, shapiq offers several approximation methods tailored to different scenarios:
- They support configurable proxy models, including LightGBM, XGBoost, or scikit-learn decision trees, and can be optimized using hyperparameter tuning.
- ShaplEIG: This Bayesian experimental design approach efficiently estimates Shapley values by iteratively querying coalitions and updating a Gaussian process surrogate. It is particularly useful for high-dimensional feature spaces where exact computation is prohibitive.
- OddSHAP: Focused on first-order Shapley value estimation, this method exploits the 'odd' structure of Shapley values to achieve fast and accurate approximations. It is ideal for scenarios where computational efficiency is prioritized over capturing higher-order interactions.
- Woodelf-IQ: This vectorized algorithm computes explanations for all instances in a dataset simultaneously, scaling efficiently with large numbers of explained instances or reference rows. It supports Shapley values, interaction indices, and Banzhaf values, making it versatile for various explainability tasks.
Visualization of Feature Interactions
- Network Plots: These plots display features as nodes and interactions as edges, with node and edge sizes proportional to the magnitude of attributions and interactions.
Benchmarking and Reproducibility
shapiq includes tools for benchmarking game-theoretic algorithms, allowing researchers to compare the performance of different approximation methods. This is facilitated by modules like shapiq.games, which provide benchmark games for evaluating algorithms based on metrics such as accuracy, speed, and memory usage.
Log-Space Support for Large Feature Counts
For datasets with more than 1,000 features, exact computation of Shapley values becomes impractical due to the exponential growth in the number of possible coalitions. shapiq addresses this by introducing log-space weight computation for regression-based and Monte Carlo approximators.
Compatibility with Custom Models
This flexibility allows users to explain predictions from proprietary or bespoke models, expanding its applicability beyond standard machine learning workflows.
Practical Example: Explaining a Random Forest Model
The following steps outline how to compute and visualize Shapley interactions using shapiq:
- Load Data and Train Model:
from sklearn.ensemble import RandomForestRegressor
X, y = shapiq.loadcaliforniahousing(tonumpy=True)
model = RandomForestRegressor()
Explain the model's prediction for the first sample with a budget of 256 iterations:
interactionvalues = explainer.explain(X[0], budget=256)
The output includes individual Shapley values and interaction values, such as:
- (0, 5): Interaction between features 0 and 5, indicating their combined effect.
- (0, 1, 5): Third-order interaction between features 0, 1, and 5.
- Visualize Interactions:
Use networkplot to visualize the interactions:
firstordervalues=interactionvalues.getnordervalues(1),
secondordervalues=interactionvalues.getnordervalues(2)
This generates a plot where nodes represent features and edges represent interactions, with sizes proportional to their magnitudes. For example, a large edge between 'MedInc' and 'HouseAge' would indicate a strong interaction between these features.
This example demonstrates how shapiq can provide detailed insights into model behavior, going beyond traditional feature importance to reveal the complex relationships driving predictions.