### Install shapiq using pip or uv

Source: https://context7.com/mmschlk/shapiq/llms.txt

Install the shapiq library using either pip or uv package managers.

```bash
pip install shapiq
```

```bash
# or
uv add shapiq
```

--------------------------------

### Install Shapiq Development Packages

Source: https://github.com/mmschlk/shapiq/blob/main/docs/source/introduction/installation.md

Install optional packages for contributing to Shapiq's development, including documentation and testing tools. The `dev` extra includes `docs`.

```default
pip install shapiq[docs]
```

```default
pip install shapiq[dev] # includes docs
```

--------------------------------

### Install Shapiq Development Version

Source: https://github.com/mmschlk/shapiq/blob/main/docs/source/introduction/installation.md

Install the latest code directly from the GitHub repository for development or testing purposes.

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

--------------------------------

### Install shapiq using uv

Source: https://github.com/mmschlk/shapiq/blob/main/README.md

Install the shapiq package using the uv package manager. Ensure you are using Python 3.12 or above.

```bash
uv add shapiq
```

--------------------------------

### Install Latest Shapiq Release

Source: https://github.com/mmschlk/shapiq/blob/main/docs/source/introduction/installation.md

Use this command to install the most recent stable version of the Shapiq library from the Python Package Index (PyPI).

```default
pip install shapiq
```

--------------------------------

### shapiq.ProxySPEX

Source: https://context7.com/mmschlk/shapiq/llms.txt

Proxy sparse explainer for large models, combining a LightGBM proxy model with SPEX. Requires `lightgbm` to be installed.

```APIDOC
## `shapiq.ProxySPEX` — Proxy sparse explainer for large models

Combines a LightGBM proxy model with SPEX for very large feature spaces. Requires `lightgbm` to be installed.

```python
import shapiq

# Large model with many features
data, model, n_features = ...  # your model

# Use ProxySPEX directly
approx = shapiq.ProxySPEX(n=n_features, index="FBII", max_order=2)bii_scores = approx.approximate(budget=2000, game=model.predict)

# Or via Explainer with approximator="proxyspex"
explainer = shapiq.Explainer(
    model=model,
    data=data,
    index="FBII",
    max_order=2,
    approximator="proxyspex",
)
explanation = explainer.explain(data[0])
```
```

--------------------------------

### Explain Model with k-SII Interaction Values

Source: https://github.com/mmschlk/shapiq/blob/main/docs/source/introduction/start.md

Use this snippet to explain a model's predictions using k-SII interaction values up to a specified order. Ensure you have scikit-learn and SHAP-IQ installed. The explainer requires the model, training data, and the desired interaction index.

```python
import shapiq
# load data
X, y = shapiq.load_california_housing(to_numpy=True)
# train a model
from sklearn.ensemble import RandomForestRegressor
model = RandomForestRegressor()
model.fit(X, y)
# set up an explainer with k-SII interaction values up to order 4
explainer = shapiq.TabularExplainer(
    model=model,
    data=X,
    index="k-SII",
    max_order=4
)
# explain the model's prediction for the first sample
interaction_values = explainer.explain(X[0], budget=256)
# analyse interaction values
print(interaction_values)
```

--------------------------------

### Getting Top-K Interactions

Source: https://context7.com/mmschlk/shapiq/llms.txt

Illustrates how to extract the top k interactions from an InteractionValues object, either as a new InteractionValues object or as sorted dictionaries.

```python
# --- Top-k ---
top5 = iv.get_top_k(5)                    # InteractionValues with 5 entries
top5_dict, top5_sorted = iv.get_top_k(5, as_interaction_values=False)
```

--------------------------------

### Getting n-order NumPy Arrays from InteractionValues

Source: https://context7.com/mmschlk/shapiq/llms.txt

Explains how to retrieve interaction values as NumPy arrays, specifically for first-order (main effects) and second-order (pairwise interactions).

```python
# --- n-order numpy arrays ---
first_order_arr = iv.get_n_order_values(1)    # shape (n_players,)
second_order_arr = iv.get_n_order_values(2)   # shape (n_players, n_players)
```

--------------------------------

### Build Project Documentation

Source: https://github.com/mmschlk/shapiq/blob/main/CLAUDE.md

Run this command from the project root to build the documentation. It cleans previous builds and uses sphinx-build.

```bash
rm -rf docs/source/generated docs/source/auto_examples && uv run sphinx-build -b html docs/source docs/build/html
```

--------------------------------

### Initialize and Explain with TabularExplainer

Source: https://context7.com/mmschlk/shapiq/llms.txt

Sets up a TabularExplainer using a RandomForestRegressor model and California Housing data, then explains a single data point's features using the k-SII index.

```python
import numpy as np
import shapiq
from sklearn.ensemble import RandomForestRegressor
from sklearn.model_selection import train_test_split

X, y = shapiq.load_california_housing()
feature_names = list(X.columns)
X_train, X_test, y_train, y_test = train_test_split(X.values, y.values, test_size=0.2)

model = RandomForestRegressor(n_estimators=50, random_state=0)
model.fit(X_train, y_train)
explainer = shapiq.TabularExplainer(model=model, data=X_train, index="k-SII", max_order=3)
iv = explainer.explain(X_test[0], budget=256)
```

--------------------------------

### Initialize and Use MarginalImputer

Source: https://context7.com/mmschlk/shapiq/llms.txt

Sets up a MarginalImputer using a trained model and background data, then demonstrates its use by imputing values for a given coalition.

```python
import shapiq
import numpy as np
from sklearn.ensemble import RandomForestRegressor

X, y = shapiq.load_california_housing(to_numpy=True)
model = RandomForestRegressor(n_estimators=50, random_state=0).fit(X[:1000], y[:1000])

imputer = shapiq.MarginalImputer(
    model=model,
    data=X[:500],          # background data
    sample_size=100,        # samples per coalition
    random_state=42,
)
# imputer is callable: takes (n_coalitions, n_players) → (n_coalitions,) game values
coalition = np.array([[True, False, True, False, True, False, False, True]])
print(imputer(coalition))  # model output with absent features imputed marginally
```

--------------------------------

### Initialize Gaussian and GaussianCopulaImputers

Source: https://context7.com/mmschlk/shapiq/llms.txt

Demonstrates the initialization of GaussianImputer and GaussianCopulaImputer, which are conditional imputers that respect feature correlations. Also shows how to integrate them into TabularExplainer.

```python
import shapiq
from sklearn.ensemble import RandomForestRegressor

X, y = shapiq.load_california_housing(to_numpy=True)
model = RandomForestRegressor(n_estimators=50, random_state=0).fit(X[:1000], y[:1000])

# Gaussian conditional imputer
gauss_imputer = shapiq.GaussianImputer(model=model, data=X[:500])

# Gaussian copula conditional imputer
copula_imputer = shapiq.GaussianCopulaImputer(model=model, data=X[:500])

# Use in TabularExplainer by passing the imputer instance directly
explainer = shapiq.TabularExplainer(
    model=model,
    data=X[:500],
    index="SV",
    max_order=1,
    imputer=gauss_imputer,
)
```

--------------------------------

### shapiq.waterfall_plot / iv.plot_waterfall

Source: https://context7.com/mmschlk/shapiq/llms.txt

Displays a waterfall chart that cumulatively visualizes individual feature contributions, starting from the baseline prediction and progressing to the final prediction.

```APIDOC
## `shapiq.waterfall_plot` / `iv.plot_waterfall`

### Description
Waterfall chart visualizing individual contributions cumulatively from baseline to final prediction.

### Method
`iv.plot_waterfall(feature_names, show=True)`
`shapiq.waterfall_plot(interaction_values, feature_names, show=True)`

### Parameters
#### Method Parameters (`iv.plot_waterfall`)
- **feature_names** (list[str]) - Names of the features.
- **show** (bool, optional) - Whether to display the plot. Defaults to True.

#### Function Parameters (`shapiq.waterfall_plot`)
- **interaction_values** (InteractionValues) - The interaction values object.
- **feature_names** (list[str]) - Names of the features.
- **show** (bool, optional) - Whether to display the plot. Defaults to True.
```

--------------------------------

### Loading Datasets

Source: https://context7.com/mmschlk/shapiq/llms.txt

Demonstrates how to load bundled benchmark datasets like California Housing, Bike Sharing, and Adult Census. Datasets can be loaded as pandas DataFrames or numpy arrays.

```APIDOC
## Load Datasets

### `shapiq.load_california_housing` / `load_bike_sharing` / `load_adult_census`

Load one of the three bundled benchmark datasets as a `(X, y)` pair of pandas DataFrames (or numpy arrays when `to_numpy=True`).

```python
import shapiq

# Load as pandas DataFrames (default)
X, y = shapiq.load_california_housing()
print(X.shape, X.columns.tolist())
# (20640, 8) ['MedInc', 'HouseAge', 'AveRooms', ...]

# Load as numpy arrays
X_np, y_np = shapiq.load_california_housing(to_numpy=True)

# Bike-sharing and adult census
X_bike, y_bike = shapiq.load_bike_sharing()
X_adult, y_adult = shapiq.load_adult_census()
```
```

--------------------------------

### Run Pre-commit Checks

Source: https://github.com/mmschlk/shapiq/blob/main/CLAUDE.md

Execute pre-commit checks on all files. This command is fast, taking only 3 seconds.

```bash
uv run pre-commit run --all-files
```

--------------------------------

### shapiq.Explainer

Source: https://context7.com/mmschlk/shapiq/llms.txt

The `Explainer` class is a high-level entry point that automatically selects the best explanation method for a given model type. It supports specifying the game-theoretic concept (`index`) and interaction depth (`max_order`).

```APIDOC
## `shapiq.Explainer` — Auto-dispatching explainer

High-level entry point that automatically selects the best explanation method for a given model type (dispatches to `TabularExplainer`, `TreeExplainer`, `KNNExplainer`, etc.). Use `index` to choose the game-theoretic concept and `max_order` for interaction depth.

```python
import shapiq
from sklearn.ensemble import RandomForestRegressor
from sklearn.model_selection import train_test_split

X, y = shapiq.load_california_housing(to_numpy=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

model = RandomForestRegressor(n_estimators=100, random_state=42)
model.fit(X_train, y_train)

# Auto-dispatch: will select TreeExplainer for a RandomForest
explainer = shapiq.Explainer(
    model=model,
    data=X_train,
    index="SV",      # Shapley Values (first-order only)
    max_order=1,
)

sv = explainer.explain(X_test[0])
print(sv)
# InteractionValues(index=SV, max_order=1, min_order=0, estimated=False,
#     n_players=8, baseline_value=2.07, Top 10 interactions: ...)

sv.plot_force(feature_names=["MedInc", "HouseAge", "AveRooms",
                              "AveBedrms", "Population", "AveOccup",
                              "Latitude", "Longitude"])
```
```

--------------------------------

### Save and Load Game State in SHAPIQ

Source: https://context7.com/mmschlk/shapiq/llms.txt

Demonstrates how to save the current game state to a JSON file and load it back later. This is useful for preserving precomputed values.

```python
game.save("my_game.json")
loaded_game = MyGame.load("my_game.json")
```

--------------------------------

### Initialize shapiq Explainer for auto-dispatch

Source: https://context7.com/mmschlk/shapiq/llms.txt

Use shapiq.Explainer for high-level model explanation. It auto-dispatches to the appropriate explainer (e.g., TreeExplainer for RandomForest). Specify the game-theoretic concept with `index` and interaction depth with `max_order`.

```python
import shapiq
from sklearn.ensemble import RandomForestRegressor
from sklearn.model_selection import train_test_split

X, y = shapiq.load_california_housing(to_numpy=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

model = RandomForestRegressor(n_estimators=100, random_state=42)
model.fit(X_train, y_train)

# Auto-dispatch: will select TreeExplainer for a RandomForest
explainer = shapiq.Explainer(
    model=model,
    data=X_train,
    index="SV",      # Shapley Values (first-order only)
    max_order=1,
)

sv = explainer.explain(X_test[0])
print(sv)
# InteractionValues(index=SV, max_order=1, min_order=0, estimated=False,
#     n_players=8, baseline_value=2.07, Top 10 interactions: ...)

sv.plot_force(feature_names=["MedInc", "HouseAge", "AveRooms",
                              "AveBedrms", "Population", "AveOccup",
                              "Latitude", "Longitude"])
```

--------------------------------

### Exact Tree-Based Explainer with SHAP-IQ

Source: https://context7.com/mmschlk/shapiq/llms.txt

Demonstrates using TreeExplainer for exact Shapley interactions with tree ensemble models. Supports different indices like k-SII and SV, and allows for explaining single instances or multiple instances for global importance.

```python
import shapiq
import lightgbm
from sklearn.model_selection import train_test_split

X, y = shapiq.load_bike_sharing()
X_train, X_test, y_train, y_test = train_test_split(
    X.values, y.values, test_size=0.25, random_state=42
)
feature_names = list(X.columns)

model = lightgbm.LGBMRegressor(n_estimators=100, max_depth=8, random_state=42, verbose=-1)
model.fit(X_train, y_train)

# Exact k-SII up to order 3 — no budget needed
explainer = shapiq.TreeExplainer(model=model, index="k-SII", min_order=1, max_order=3)
iv = explainer.explain(X_test[1234])
print(iv)
```

```python
# First-order Shapley values only
sv_explainer = shapiq.TreeExplainer(model=model, index="SV", max_order=1)
sv = sv_explainer.explain(X_test[0])
sv.plot_force(feature_names=feature_names, contribution_threshold=0.03)
```

```python
# Global feature importance from 50 instances
list_of_ivs = explainer.explain_X(X_test[:50])
shapiq.bar_plot(list_of_ivs, feature_names=feature_names, max_display=20)
```

--------------------------------

### Manage Subset Generation and Budget Splitting with shapiq utilities

Source: https://context7.com/mmschlk/shapiq/llms.txt

Utility functions for generating specific subsets and distributing computational budgets across different subset sizes for approximation algorithms.

```python
import shapiq

# Get all subsets up to a specific size
subsets = shapiq.get_explicit_subsets(n=5, subset_sizes=[1, 2])

# Split a budget across different subset sizes
budget_split = shapiq.split_subsets_budget(order=2, budget=200, n=8)
```

--------------------------------

### SPEX Sparse Fourier-based Explainer

Source: https://context7.com/mmschlk/shapiq/llms.txt

An efficient explainer for finding sparse interaction structures using Fourier analysis. SPEX is ideal for models with few significant interactions and requires a larger budget compared to Monte Carlo methods. Results can be visualized with a force plot.

```python
import numpy as np
import shapiq

weights = np.array([0.4, 0.3, 0.2, 0.1, 0.05, -0.1, -0.2, -0.3])

def game_fun(coalitions: np.ndarray) -> np.ndarray:
    return (coalitions @ weights) + 0.5 * coalitions[:, 0] * coalitions[:, 1]

# SPEX requires a larger budget than Monte Carlo methods
approx = shapiq.SPEX(n=8, max_order=2, random_state=42)
iv = approx.approximate(budget=500, game=game_fun)
print(iv)
iv.plot_force(feature_names=[f"x{i}" for i in range(8)])
```

--------------------------------

### Compute Shapley Values with SHAP Index

Source: https://github.com/mmschlk/shapiq/blob/main/README.md

Use shapiq.Explainer with index='SV' to compute Shapley values similar to the SHAP library. Requires data and a model. The plot_force method visualizes the results.

```python
import shapiq

data, model = ...  # get your data and model
explainer = shapiq.Explainer(
    model=model,
    data=data,
    index="SV",  # Shapley values
)
shapley_values = explainer.explain(data[0])
shapley_values.plot_force(feature_names=...)
```

--------------------------------

### Initialize BaselineImputer

Source: https://context7.com/mmschlk/shapiq/llms.txt

Initializes a BaselineImputer with a model and background data. This imputer replaces absent features with a constant baseline value, typically the mean.

```python
import shapiq
from sklearn.ensemble import RandomForestRegressor
import numpy as np

X, y = shapiq.load_california_housing(to_numpy=True)
model = RandomForestRegressor(n_estimators=50, random_state=0).fit(X[:1000], y[:1000])

imputer = shapiq.BaselineImputer(
    model=model,
    data=X[:500],    # used to compute the baseline (mean)
)
```

--------------------------------

### Load bundled datasets in shapiq

Source: https://context7.com/mmschlk/shapiq/llms.txt

Load benchmark datasets like California Housing, Bike Sharing, or Adult Census. Datasets can be loaded as pandas DataFrames or numpy arrays.

```python
import shapiq

# Load as pandas DataFrames (default)
X, y = shapiq.load_california_housing()
print(X.shape, X.columns.tolist())
# (20640, 8) ['MedInc', 'HouseAge', 'AveRooms', ...]

# Load as numpy arrays
X_np, y_np = shapiq.load_california_housing(to_numpy=True)

# Bike-sharing and adult census
X_bike, y_bike = shapiq.load_bike_sharing()
X_adult, y_adult = shapiq.load_adult_census()
```

--------------------------------

### Generate All Subsets with shapiq.powerset

Source: https://context7.com/mmschlk/shapiq/llms.txt

Generate the powerset (all possible subsets) of a given set of elements. Can be constrained by minimum and maximum subset sizes.

```python
import shapiq

for subset in shapiq.powerset(range(4)):
    print(subset)
# (), (0,), (1,), (2,), (3,), (0,1), ...

# Limit to subsets of size 1 and 2
for subset in shapiq.powerset(range(5), min_size=1, max_size=2):
    print(subset)
```

--------------------------------

### shapiq.get_explicit_subsets / shapiq.split_subsets_budget

Source: https://context7.com/mmschlk/shapiq/llms.txt

Provides utility functions for handling subsets. `get_explicit_subsets` retrieves all subsets up to a specified size, while `split_subsets_budget` helps in distributing a computational budget across different subset sizes.

```APIDOC
## `shapiq.get_explicit_subsets` / `shapiq.split_subsets_budget`

### Description
Utility functions for subset generation and budget allocation.

### Methods
`shapiq.get_explicit_subsets(n, subset_sizes)`
`shapiq.split_subsets_budget(order, budget, n)`

### Parameters
#### `get_explicit_subsets`
- **n** (int) - The total number of elements.
- **subset_sizes** (list[int]) - A list of desired subset sizes.

#### `split_subsets_budget`
- **order** (int) - The maximum order of interactions to consider.
- **budget** (int) - The total computational budget.
- **n** (int) - The total number of features.
```

--------------------------------

### Approximate Interaction Values with SHAPIQ

Source: https://context7.com/mmschlk/shapiq/llms.txt

Shows how to use the SHAPIQ approximator to calculate interaction values for a game. Requires specifying the number of players, maximum interaction order, index type, and random state.

```python
approx = shapiq.SHAPIQ(n=n, max_order=2, index="k-SII", random_state=42)
iv = approx.approximate(budget=150, game=game)
print(iv)
```

--------------------------------

### Use ProxySPEX for Large Feature Spaces

Source: https://context7.com/mmschlk/shapiq/llms.txt

Use ProxySPEX for approximating interaction indices in models with very large feature spaces. Requires the 'lightgbm' library. Can be used directly or via the Explainer class.

```python
import shapiq

# Large model with many features
data, model, n_features = ...  # your model

# Use ProxySPEX directly
approx = shapiq.ProxySPEX(n=n_features, index="FBII", max_order=2)bii_scores = approx.approximate(budget=2000, game=model.predict)

# Or via Explainer with approximator="proxyspex"
explainer = shapiq.Explainer(
    model=model,
    data=data,
    index="FBII",
    max_order=2,
    approximator="proxyspex",
)
explanation = explainer.explain(data[0])
```

--------------------------------

### shapiq.AgnosticExplainer

Source: https://context7.com/mmschlk/shapiq/llms.txt

Generic explainer for any callable value function or `shapiq.Game` object.

```APIDOC
## shapiq.AgnosticExplainer

### Description
Works with any callable value function or `shapiq.Game` object. Useful when the model is not a standard ML estimator.

### Usage
```python
def my_game(coalitions: np.ndarray) -> np.ndarray:
    weights = np.array([0.4, 0.3, 0.2, 0.1, 0.05, -0.1, -0.2, -0.3])
    return (coalitions @ weights) + 0.5 * coalitions[:, 0] * coalitions[:, 1]

explainer = shapiq.AgnosticExplainer(
    model=my_game,
    data=None,           # not needed for pure game functions
    n_players=8,
    index="k-SII",
    max_order=2,
)
iv = explainer.explain(np.ones(8), budget=200)
print(iv)
```
```

--------------------------------

### Explain TabPFN Models

Source: https://github.com/mmschlk/shapiq/blob/main/README.md

Explain TabPFN models using shapiq.TabPFNExplainer, which implements the remove-and-recontextualize paradigm. Requires TabPFN model, data, labels, and the desired index (e.g., 'FSII').

```python
import tabpfn, shapiq
data, labels = ...                    # load your data
model = tabpfn.TabPFNClassifier()     # get TabPFN
model.fit(data, labels)               # "fit" TabPFN (optional)
explainer = shapiq.TabPFNExplainer(   # setup the explainer
    model=model,
    data=data,
    labels=labels,
    index="FSII"
)
fsii_values = explainer.explain(data[0])  # explain with Faithful Shapley values
fsii_values.plot_force()               # plot the force plot
```

--------------------------------

### Performing Arithmetic Operations on InteractionValues

Source: https://context7.com/mmschlk/shapiq/llms.txt

Shows how to perform element-wise arithmetic operations (addition, multiplication by scalar) on InteractionValues objects and how to sparsify by zeroing out near-zero interactions.

```python
# --- Arithmetic ---
iv2 = explainer.explain(X_test[1], budget=256)
avg_iv = (iv + iv2) * 0.5               # average over two explanations
iv.sparsify(threshold=1e-3)              # zero out near-zero interactions
```

--------------------------------

### Approximate Interaction Values with ProxySPEX

Source: https://github.com/mmschlk/shapiq/blob/main/README.md

For large-scale problems, use shapiq.ProxySPEX for approximation. It can be used directly or specified as an approximator within shapiq.Explainer. Requires the number of features and the model's prediction function.

```python
# load your data and model with large number of features
data, model, n_features = ...

# use the ProxySPEX approximator directly
approximator = shapiq.ProxySPEX(n=n_features, index="FBII", max_order=2)
fbii_scores = approximator.approximate(budget=2000, game=model.predict)

# or use ProxySPEX with an explainer
explainer = shapiq.Explainer(
    model=model,
    data=data,
    index="FBII",
    max_order=2,
    approximator="proxyspex"  # specify ProxySPEX as approximator
)
explanation = explainer.explain(data[0])
```

--------------------------------

### Agnostic Explainer for SHAP-IQ

Source: https://context7.com/mmschlk/shapiq/llms.txt

A generic explainer for any callable value function or shapiq.Game object. Useful when the model is not a standard ML estimator. The `data` parameter is not needed for pure game functions.

```python
import numpy as np
import shapiq

# Any callable: takes (n_coalitions, n_players) binary matrix, returns (n_coalitions,) scores
def my_game(coalitions: np.ndarray) -> np.ndarray:
    weights = np.array([0.4, 0.3, 0.2, 0.1, 0.05, -0.1, -0.2, -0.3])
    return (coalitions @ weights) + 0.5 * coalitions[:, 0] * coalitions[:, 1]

explainer = shapiq.AgnosticExplainer(
    model=my_game,
    data=None,           # not needed for pure game functions
    n_players=8,
    index="k-SII",
    max_order=2,
)
iv = explainer.explain(np.ones(8), budget=200)
print(iv)
```

--------------------------------

### Compute Interaction Values with k-SII Index

Source: https://github.com/mmschlk/shapiq/blob/main/README.md

Compute interaction values by setting index='k-SII' and specifying max_order in shapiq.Explainer. This allows for the calculation of higher-order interactions. The plot_force method can visualize these values.

```python
explainer = shapiq.Explainer(
    model=model,
    data=data,
    index="k-SII",  # k-SII interaction values
    max_order=2     # specify any order you want
)
interaction_values = explainer.explain(data[0])
interaction_values.plot_force(feature_names=...)
```

--------------------------------

### shapiq.SPEX

Source: https://context7.com/mmschlk/shapiq/llms.txt

Sparse Fourier-based explainer for finding sparse interaction structure.

```APIDOC
## shapiq.SPEX

### Description
Sparse Fourier-based explainer. Efficiently finds sparse interaction structure using Fourier analysis. Ideal for models where only a small number of interactions are significant.

### Usage
```python
weights = np.array([0.4, 0.3, 0.2, 0.1, 0.05, -0.1, -0.2, -0.3])

def game_fun(coalitions: np.ndarray) -> np.ndarray:
    return (coalitions @ weights) + 0.5 * coalitions[:, 0] * coalitions[:, 1]

# SPEX requires a larger budget than Monte Carlo methods
approx = shapiq.SPEX(n=8, max_order=2, random_state=42)
iv = approx.approximate(budget=500, game=game_fun)
print(iv)
iv.plot_force(feature_names=[f"x{i}" for i in range(8)])
```
```

--------------------------------

### TabPFN Explainer for SHAP-IQ

Source: https://context7.com/mmschlk/shapiq/llms.txt

Utilizes TabPFNExplainer for TabPFN models, employing the 'remove-and-recontextualize' method. This explainer refits the model on each coalition, suitable for TabPFN's in-context learning.

```python
import tabpfn
import shapiq

X, y = shapiq.load_california_housing(to_numpy=True)

model = tabpfn.TabPFNRegressor()
model.fit(X[:500], y[:500])

explainer = shapiq.TabPFNExplainer(
    model=model,
    data=X[:500],
    labels=y[:500],
    index="FSII",        # Faithful Shapley Interaction Index
    max_order=2,
)

fsii_values = explainer.explain(X[0])
fsii_values.plot_force()
```

--------------------------------

### Initialize shapiq TabularExplainer for imputation-based explanations

Source: https://context7.com/mmschlk/shapiq/llms.txt

Use shapiq.TabularExplainer for models predicting tabular data. It supports various imputation methods ('marginal', 'conditional', 'baseline', 'generative') and interaction indices. Specify `sample_size` for approximation.

```python
import shapiq
from sklearn.ensemble import RandomForestRegressor
from sklearn.model_selection import train_test_split

X, y = shapiq.load_california_housing()
X_train, X_test, y_train, y_test = train_test_split(
    X.values, y.values, test_size=0.25, random_state=42
)
feature_names = list(X.columns)

model = RandomForestRegressor(n_estimators=100, max_depth=8, random_state=42)
model.fit(X_train, y_train)

# k-SII up to order 4 with marginal imputation
explainer = shapiq.TabularExplainer(
    model=model,
    data=X_train,
    index="k-SII",
    max_order=4,
    imputer="marginal",
    sample_size=100,
    random_state=42,
)

iv = explainer.explain(X_test[0], budget=256)
print(iv)
# InteractionValues(index=k-SII, max_order=4, min_order=0, estimated=False,
#     n_players=8, baseline_value=2.07, Top 10 interactions:
#         (0,): 1.696     # MedInc main effect
#         (0, 5): 0.484   # MedInc × AveOccup interaction
#         ...)

# Explain multiple instances
list_of_ivs = explainer.explain_X(X_test[:50], budget=256, verbose=True)
```

--------------------------------

### Exact Game-Theoretic Computation with ExactComputer

Source: https://context7.com/mmschlk/shapiq/llms.txt

ExactComputer computes game-theoretic indices by evaluating all 2^n coalitions. It is feasible for n up to approximately 14 players. Requires defining a custom game by subclassing shapiq.Game.

```python
import numpy as np
import shapiq

# Define a custom cooperative game by subclassing shapiq.Game
class CookingGame(shapiq.Game):
    def __init__(self):
        self.char_fun = {
            (): 0, (0,): 4, (1,): 3, (2,): 2,
            (0, 1): 9, (0, 2): 8, (1, 2): 7, (0, 1, 2): 15,
        }
        super().__init__(
            n_players=3,
            player_names=["Alice", "Bob", "Charlie"],
            normalization_value=0,
        )

    def value_function(self, coalitions: np.ndarray) -> np.ndarray:
        return np.array([self.char_fun[tuple(np.where(c)[0])] for c in coalitions])

game = CookingGame()

# Exact computation: pass a Game object (n_players inferred)
computer = shapiq.ExactComputer(game=game)

# Shapley Values
sv = computer(index="SV")
print(sv)
# (0,): 5.833, (1,): 4.5, (2,): 4.666

# k-SII up to order 2
ksII = computer(index="k-SII", order=2)
ksII.plot_stacked_bar(
    feature_names=["Alice", "Bob", "Charlie"],
    xlabel="Cooks", ylabel="k-SII"
)

# Banzhaf Values
bv = computer(index="BV")

# Moebius Transform
moebius = computer(index="Moebius")
```

--------------------------------

### Other Approximators

Source: https://context7.com/mmschlk/shapiq/llms.txt

Lists various other approximator classes available in SHAPIQ, all following the same interface `Approximator(n, index, max_order).approximate(budget, game)`.

```APIDOC
### Other approximators

All follow the same interface `Approximator(n, index, max_order).approximate(budget, game)`:

| Class |
|---|---|
| `shapiq.PermutationSamplingSV` | SV | Permutation sampling |
| `shapiq.PermutationSamplingSII` | SII | Permutation sampling |
| `shapiq.PermutationSamplingSTII` | STII | Permutation sampling |
| `shapiq.SVARM` | SV | Variance-reduced sampling |
| `shapiq.SVARMIQ` | SII, STII, FSII | Variance-reduced sampling |
| `shapiq.StratifiedSamplingSV` | SV | Stratified sampling |
| `shapiq.OwenSamplingSV` | SV | Owen sampling |
| `shapiq.UnbiasedKernelSHAP` | SV | Unbiased regression |
| `shapiq.kADDSHAP` | kADD-SHAP | k-additive regression |
| `shapiq.ProxySHAP` | SV/SI | Proxy tree acceleration |
```

--------------------------------

### shapiq.ExactComputer

Source: https://context7.com/mmschlk/shapiq/llms.txt

Exact game-theoretic computation for cooperative games, feasible for n ≤ ~14 players.

```APIDOC
## ExactComputer

### `shapiq.ExactComputer` — Exact game-theoretic computation

Evaluates all 2^n coalitions and computes any supported game-theoretic index exactly. Feasible for n ≤ ~14 players.

```python
import numpy as np
import shapiq

# Define a custom cooperative game by subclassing shapiq.Game
class CookingGame(shapiq.Game):
    def __init__(self):
        self.char_fun = {
            (): 0, (0,): 4, (1,): 3, (2,):
            2,
            (0, 1): 9, (0, 2): 8, (1, 2): 7, (0, 1, 2): 15,
        }
        super().__init__(
            n_players=3,
            player_names=["Alice", "Bob", "Charlie"],
            normalization_value=0,
        )

    def value_function(self, coalitions: np.ndarray) -> np.ndarray:
        return np.array([self.char_fun[tuple(np.where(c)[0])] for c in coalitions])

game = CookingGame()

# Exact computation: pass a Game object (n_players inferred)
computer = shapiq.ExactComputer(game=game)

# Shapley Values
sv = computer(index="SV")
print(sv)
# (0,): 5.833, (1,): 4.5, (2,): 4.666

# k-SII up to order 2
ksII = computer(index="k-SII", order=2)
ksII.plot_stacked_bar(
    feature_names=["Alice", "Bob", "Charlie"],
    xlabel="Cooks", ylabel="k-SII"
)

# Banzhaf Values
bv = computer(index="BV")

# Moebius Transform
moebius = computer(index="Moebius")
```
```

--------------------------------

### KernelSHAP Approximator for SHAP-IQ

Source: https://context7.com/mmschlk/shapiq/llms.txt

Implements regression-based Shapley values using KernelSHAP. Requires a budget for approximation and a game function as input. Visualizes results using a force plot.

```python
import numpy as np
import shapiq

weights = np.array([0.4, 0.3, 0.2, 0.1, 0.05, -0.1, -0.2, -0.3])

def game_fun(coalitions: np.ndarray) -> np.ndarray:
    return (coalitions @ weights) + 0.5 * coalitions[:, 0] * coalitions[:, 1]

approx = shapiq.KernelSHAP(n=8, random_state=42)
sv = approx.approximate(budget=200, game=game_fun)
print(sv)
sv.plot_force(feature_names=[f"x{i}" for i in range(8)])
```

--------------------------------

### SHAPIQ Monte Carlo Approximator

Source: https://context7.com/mmschlk/shapiq/llms.txt

A Monte Carlo approximator for any-order interactions in SHAP-IQ. It requires a budget and a game function. The results can be visualized as a network plot.

```python
import numpy as np
import shapiq

weights = np.array([0.4, 0.3, 0.2, 0.1, 0.05, -0.1, -0.2, -0.3])

def game_fun(coalitions: np.ndarray) -> np.ndarray:
    return (coalitions @ weights) + 0.5 * coalitions[:, 0] * coalitions[:, 1]

approx = shapiq.SHAPIQ(n=8, max_order=2, index="k-SII", random_state=42)
iv = approx.approximate(budget=200, game=game_fun)
print(iv)
iv.plot_network(feature_names=[f"x{i}" for i in range(8)])
```

--------------------------------

### shapiq.TabPFNExplainer

Source: https://context7.com/mmschlk/shapiq/llms.txt

Specialized explainer for TabPFN models using the *remove-and-recontextualize* paradigm.

```APIDOC
## shapiq.TabPFNExplainer

### Description
Specialized explainer for `TabPFNClassifier` / `TabPFNRegressor` using the *remove-and-recontextualize* paradigm. Handles the in-context learning nature of TabPFN by refitting on each coalition.

### Usage
```python
explainer = shapiq.TabPFNExplainer(
    model=model,
    data=X[:500],
    labels=y[:500],
    index="FSII",        # Faithful Shapley Interaction Index
    max_order=2,
)
fsii_values = explainer.explain(X[0])
fsii_values.plot_force()
```
```

--------------------------------

### Serialize and Deserialize InteractionValues

Source: https://context7.com/mmschlk/shapiq/llms.txt

Demonstrates saving an InteractionValues object to a JSON file with a description and loading it back, verifying equality.

```python
# --- Serialization ---
from pathlib import Path
iv.to_json_file(Path("iv.json"), desc="California Housing explanation")
iv_loaded = shapiq.InteractionValues.from_json_file(Path("iv.json"))
assert iv == iv_loaded
```

--------------------------------

### shapiq.powerset

Source: https://context7.com/mmschlk/shapiq/llms.txt

Generates the powerset of a given set, which includes all possible subsets. It can be configured to include subsets within a specific size range.

```APIDOC
## `shapiq.powerset`

### Description
Generate all subsets of a given set, optionally filtering by size.

### Method
`shapiq.powerset(iterable, min_size=0, max_size=None)`

### Parameters
- **iterable** (iterable) - The input iterable (e.g., a list or range).
- **min_size** (int, optional) - The minimum size of subsets to include. Defaults to 0.
- **max_size** (int, optional) - The maximum size of subsets to include. Defaults to None (no upper limit).
```

--------------------------------

### shapiq.KernelSHAP

Source: https://context7.com/mmschlk/shapiq/llms.txt

Regression-based Shapley values approximator.

```APIDOC
## shapiq.KernelSHAP

### Description
Regression-based Shapley values approximator.

### Usage
```python
weights = np.array([0.4, 0.3, 0.2, 0.1, 0.05, -0.1, -0.2, -0.3])

def game_fun(coalitions: np.ndarray) -> np.ndarray:
    return (coalitions @ weights) + 0.5 * coalitions[:, 0] * coalitions[:, 1]

approx = shapiq.KernelSHAP(n=8, random_state=42)
sv = approx.approximate(budget=200, game=game_fun)
print(sv)
sv.plot_force(feature_names=[f"x{i}" for i in range(8)])
```
```

--------------------------------

### Accessing Interaction Values

Source: https://context7.com/mmschlk/shapiq/llms.txt

Demonstrates how to access specific interaction scores (main effects, pairwise interactions), the baseline value, and the dictionary representation of all interaction values from an InteractionValues object.

```python
# --- Accessing values ---
print(iv[(0,)])          # main effect of feature 0
print(iv[(0, 1)])        # pairwise interaction between features 0 and 1
print(iv.baseline_value) # empty coalition value
print(iv.dict_values)    # {tuple: float} for all interactions
```

--------------------------------

### Create Customizable Interaction Graph with shapiq.si_graph_plot

Source: https://context7.com/mmschlk/shapiq/llms.txt

A flexible interaction graph visualization, serving as the backend for `network_plot`. Allows for more customization of interaction visualizations.

```python
import shapiq

shapiq.si_graph_plot(
    interaction_values=iv,
    feature_names=feature_names,
    show=True,
)
```

--------------------------------

### Extracting Subset of Players from InteractionValues

Source: https://context7.com/mmschlk/shapiq/llms.txt

Demonstrates how to create a new InteractionValues object containing only interactions among a specified subset of players.

```python
# --- Subset of players ---
sub = iv.get_subset([0, 1, 5])            # only interactions among features 0, 1, 5
```

--------------------------------

### Create Stacked Bar Chart of Contributions with shapiq.stacked_bar_plot

Source: https://context7.com/mmschlk/shapiq/llms.txt

Visualize contributions broken down by interaction order using a stacked horizontal bar chart. Supports plotting all orders, first order only, or a range of orders.

```python
import shapiq

# All orders stacked
shapiq.stacked_bar_plot(interaction_values=iv, feature_names=feature_names)

# First order only
shapiq.stacked_bar_plot(iv.get_n_order(1), feature_names=feature_names)

# First + second order
shapiq.stacked_bar_plot(iv.get_n_order(2, min_order=1), feature_names=feature_names)
```

--------------------------------

### Visualize NLP Attributions with shapiq.sentence_plot

Source: https://context7.com/mmschlk/shapiq/llms.txt

Inline text visualization for NLP tasks, coloring words/tokens by their first-order attribution. Also demonstrates using `network_plot` for pairwise interactions in NLP contexts.

```python
import shapiq
from shapiq_games.benchmark import SentimentAnalysisLocalXAI

game = SentimentAnalysisLocalXAI(
    input_text="I really loved this amazing film",
    mask_strategy="mask",
    normalize=True,
)
tokens = game.input_text.split()

approx = shapiq.KernelSHAP(n=game.n_players, random_state=42)
sv = approx.approximate(budget=50, game=game)

# Inline sentence plot
sv.plot_sentence(words=tokens)

# Pairwise interactions via network plot
approx_sii = shapiq.KernelSHAPIQ(n=game.n_players, index="k-SII", max_order=2)
sii = approx_sii.approximate(budget=50, game=game)
sii.plot_network(feature_names=tokens)
```

--------------------------------

### Create Beeswarm Summary Plot with shapiq.beeswarm_plot

Source: https://context7.com/mmschlk/shapiq/llms.txt

Display the distribution of interaction values across multiple samples using a beeswarm plot. Supports interaction terms and allows limiting the number of features displayed with `max_display`.

```python
import shapiq

list_of_ivs = explainer.explain_X(X.values[:200])
shapiq.beeswarm_plot(
    list_of_ivs,
    feature_names=feature_names,
    max_display=12,
)
```

--------------------------------

### Define Custom Cooperative Games with shapiq.Game

Source: https://context7.com/mmschlk/shapiq/llms.txt

Subclass shapiq.Game to define custom cooperative games. This base class provides precomputation, serialization, and integration with approximators and ExactComputer. Ensure 'numpy' is imported.

```python
import numpy as np
import shapiq

class MyGame(shapiq.Game):
    """A simple weighted coalition game."""

    def __init__(self, n: int, weights: np.ndarray):
        self.weights = weights
        super().__init__(
            n_players=n,
            normalize=True,
            normalization_value=0.0,
            verbose=False,
        )

    def value_function(self, coalitions: np.ndarray) -> np.ndarray:
        # coalitions shape: (n_coalitions, n_players), dtype bool/int
        return (coalitions @ self.weights) + 0.3 * coalitions[:, 0] * coalitions[:, 1]


n = 6
weights = np.array([0.5, 0.3, 0.2, -0.1, 0.4, -0.2])
game = MyGame(n=n, weights=weights)

# Precompute all 2^n = 64 coalitions for fast repeated access
game.precompute()
print(game.precomputed, game.n_values_stored)  # True, 64
```

--------------------------------

### Visualize Feature Interactions with Network Plot

Source: https://github.com/mmschlk/shapiq/blob/main/docs/source/introduction/start.md

Visualize the calculated feature interactions using SHAP-IQ's network plotting functions. This requires the first and second-order interaction values obtained from the explainer. Alternatively, the InteractionValues object has a built-in plot_network method.

```python
# visualize interaction values
shapiq.network_plot(
    first_order_values=interaction_values.get_n_order_values(1),
    second_order_values=interaction_values.get_n_order_values(2)
)
# or use
interaction_values.plot_network()
```

--------------------------------

### Conditional Imputer for SHAP-IQ

Source: https://context7.com/mmschlk/shapiq/llms.txt

Initializes a TabularExplainer with conditional imputation, respecting feature correlations. Requires specifying imputation parameters like sample_size and conditional_threshold.

```python
explainer_cond = shapiq.TabularExplainer(
    model=model,
    data=X_train,
    index="SII",
    max_order=2,
    imputer="conditional",
    sample_size=100,
    conditional_budget=32,
    conditional_threshold=0.04,
)
iv_cond = explainer_cond.explain(X_test[0], budget=2**8)
```

--------------------------------

### shapiq.RegressionFSII / shapiq.RegressionFBII

Source: https://context7.com/mmschlk/shapiq/llms.txt

Regression-based estimators for Faithful Shapley Interaction Index (FSII) and Faithful Banzhaf Interaction Index (FBII).

```APIDOC
### `shapiq.RegressionFSII` / `shapiq.RegressionFBII`

Regression-based estimators for Faithful Shapley Interaction Index (FSII) and Faithful Banzhaf Interaction Index (FBII).

```python
import numpy as np
import shapiq

def game_fun(coalitions: np.ndarray) -> np.ndarray:
    weights = np.array([0.5, 0.3, -0.2, 0.1])
    return coalitions @ weights + 0.4 * coalitions[:, 0] * coalitions[:, 1]

fsii_approx = shapiq.RegressionFSII(n=4, max_order=2, random_state=0)
fsii = fsii_approx.approximate(budget=100, game=game_fun)
print(fsii)

fbii_approx = shapiq.RegressionFBII(n=4, max_order=2, random_state=0)
fbii = fbii_approx.approximate(budget=100, game=game_fun)
print(fbii)
```
```