shapiq: Shapley Interaction Quantification

shapiq is a Python package designed for approximating any-order Shapley interactions, benchmarking game-theoretical algorithms for machine learning, and explaining feature interactions in model predictions.

It extends the shap package by quantifying the synergy effect between entities (referred to as players in game theory), such as explanatory features, data points, or weak learners in ensemble models. This provides a more comprehensive view of machine learning models compared to standard individual Shapley values.

shapiq provides several built-in visualization tools to interpret Shapley Interaction (SI) values and model behavior. Available visualization types include:

• Force plots: To visualize how different features push the prediction towards or away from a base value.
• Beeswarm plots: To show the distribution of interaction values across a dataset.
• SI graph plots: To visualize Shapley Interactions as a graph structure.
• UpSet plots: To visualize intersections and overlaps in feature interactions.

Refer to the specific example files in the examples/visualization/ directory to see implementation details for each plot type.

Traditional Shapley values distribute a model's prediction influence among individual features. However, they merge individual effects and interaction effects into a single number, making it impossible to distinguish if a feature's influence is independent or dependent on another feature.

Shapley interactions solve this by decomposing the prediction's influence into:

1. Individual contributions: The effect of a feature acting alone.
2. Interactions: The effect of combinations of features (e.g., how the combination of longitude and latitude identifies a specific location).

By setting a maximum interaction order, you can control the granularity of the analysis. For example, a second-order decomposition allows you to see how pairs of features interact, whereas traditional Shapley values only provide first-order (individual) effects.

To install the latest stable release of shapiq, use pip to fetch it from PyPI.

pip install shapiq

If you are contributing to shapiq and need additional packages for documentation or testing, use the optional installation extras:

• shapiq[docs]: Installs dependencies required for building documentation.
• shapiq[dev]: Installs all development dependencies, including those for documentation.

pip install shapiq[docs]
pip install shapiq[dev]

Install shapiq using uv or pip. Note that shapiq requires Python 3.12 or above.

uv add shapiq

pip install shapiq

If you need the development version of shapiq, you can install it directly from the GitHub repository.

pip install git+https://github.com/mmschlk/shapiq

The Game class is the base class for all cooperative games in shapiq. To use it with your own data or model, you must create a subclass and implement the value_function method. The value_function defines the worth of a coalition of players and is the core logic of your game.

When initializing your subclass, you can specify n_players, whether to normalize values (centering them so the empty coalition is zero), and an optional list of player_names to allow using string identifiers for coalitions.

from shapiq.game import Game
import numpy as np

class MyCustomGame(Game):
    def value_function(self, coalitions: np.ndarray) -> np.ndarray:
        # Implement your logic here
        # coalitions is a one-hot encoded matrix
        return np.sum(coalitions, axis=1)

# Usage
game = MyCustomGame(n_players=3)

The following types define how players and their groupings are represented in shapiq:

• CoalitionTuple: A sorted tuple[int, ...] of player indices.
• InteractionTuple: A sorted tuple[int, ...] of player indices representing an interaction.
• CoalitionsTuples: A Collection[CoalitionTuple] representing a set of coalitions.
• CoalitionMatrix: A 2D NDArray[np.bool_] of shape (n_coalitions, n_players) where 1 indicates player presence.
• InteractionScores: A dict[InteractionTuple, float] mapping interactions to their scores.
• GameScores: A dict[CoalitionTuple, float] mapping coalitions to their game values.