Interpretability

The Interpretability Extension adds dedicated support for shapiq, along with convenience wrappers for sklearn’s built-in interpretability tools, and for plotting with the shap library (see here). Shapley values explain a single prediction by attributing the prediction’s deviation from the baseline (mean prediction) to individual features. They provide a consistent, game-theoretic measure of feature influence. Mathematically, each Shapley value represents the marginal contribution of a feature across all possible feature combinations. This can be used to:

See which features drive model predictions.
Compare feature importance across samples.
Detect feature interactions.
Debug unexpected model behavior.

Why TabPFN is Well-Suited for Interpretability

TabPFN produces smooth, well-calibrated predictions that make post-hoc explanations more stable and meaningful. Because it is a foundation model pretrained on synthetic data, it generalizes without overfitting to individual training samples — so feature attributions reflect genuine patterns. TabPFN follows the scikit-learn estimator API (fit, predict, predict_proba), which means it works out of the box with most interpretability tools in the sklearn ecosystem — partial dependence plots, permutation importance, and any other method that accepts a sklearn-compatible estimator. No wrappers or adapters needed.

SHAP beeswarm plot of global feature importance for coronary-disease risk

Global feature importance on the heart-statlog dataset: each dot is one patient, horizontal position is the feature’s SHAP value (right = pushed toward disease), colour is the feature value. Blocked vessels and thallium scan dominate, and the clean colour separation shows the model learned monotone, clinically sensible effects. Full walkthrough in the Interpreting Results cookbook.

Installation

pip install tabpfn "tabpfn-extensions[interpretability]"

This installs shapiq and the other dependencies needed for all methods. To run against the cloud API instead of locally, install tabpfn-client in place of tabpfn:

pip install tabpfn-client "tabpfn-extensions[interpretability]"

Quickstart

Train a model, explain a single prediction, and plot the result:

This tutorial runs TabPFN locally, which requires a GPU — see our FAQ for GPU setup. The recommended get_tabpfn_imputation_explainer relies on fit_mode="fit_with_cache", which is local-only and not available in the tabpfn_client backend. To use the cloud API, replace the tabpfn import with tabpfn_client and remove fit_mode (the client does not support it yet).

from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from tabpfn import TabPFNClassifier
from tabpfn_extensions.interpretability.shapiq import get_tabpfn_imputation_explainer

X, y = load_iris(return_X_y=True, as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

# fit_mode="fit_with_cache" engages the KV-cache fast path; set it BEFORE .fit().
clf = TabPFNClassifier(fit_mode="fit_with_cache")
clf.fit(X_train, y_train)

explainer = get_tabpfn_imputation_explainer(model=clf, data=X_train)
sv = explainer.explain(X_test.iloc[0:1].values, budget=128)
sv.plot_waterfall()

Choosing a Method

Before diving into each method, here is a summary to help you pick the right tool for the question you are trying to answer.

Two shapiq adapters — get_tabpfn_imputation_explainer uses imputation-based feature removal (marginal / conditional / baseline). The training set is fixed across coalitions, so the KV-cache fast path applies — construct the model with fit_mode="fit_with_cache". This is the recommended adapter. get_tabpfn_explainer uses the remove-and-recontextualize paradigm (Rundel et al. 2024): TabPFN is re-fit for every coalition, so the KV cache cannot be reused — expect this path to be substantially slower.

Method	What it tells you	When to reach for it	Recommended scale
shapiq (recommended)	A redesigned and improved version of the well-known SHAP library, with a more efficient and scalable implementation of Shapley values and Shapley interactions, plus native support for TabPFN. Tells you which features drove a specific prediction.	You want per-sample explanations and care about feature interactions, or you want the fastest Shapley-based method for TabPFN.	Any dataset TabPFN supports. Cost is per-sample and controlled by the `budget` parameter, so explain in batches if needed.
Partial Dependence / ICE	The global, marginal effect of one or two features across the entire dataset.	You want to understand how a feature affects the model on average rather than for a single sample, or you want to visually compare TabPFN against another sklearn estimator.	Any dataset TabPFN supports. Cost scales with grid resolution × samples, so limit to a few features at a time.
Feature Selection	Which minimal subset of features preserves model performance.	You want to simplify your model or identify redundant features before deployment.	Best under ~5,000 samples. Involves repeated cross-validation across feature subsets, so cost multiplies quickly with dataset size.

If you are still unsure which method to use, follow the table below to see the best tools for most common questions.

Question	Method
”Why did the model predict this for this sample?“	shapiq — `get_tabpfn_imputation_explainer`
”Which feature pairs interact most?“	shapiq — `get_tabpfn_imputation_explainer` with `index="k-SII"`, `max_order=2`
”How does feature X affect predictions globally?”	Partial Dependence — `partial_dependence_plots`
”How can I use the remove-and-recontextualize paradigm?“	shapiq — `get_tabpfn_explainer`
”Which features can I drop without losing accuracy?”	Feature Selection — `feature_selection`
”How do I get SHAP values for many rows with the cloud API?”	`tabpfn_client.explain.permutation_shap`

Use Cases

Explain a prediction with shapiq

Use Shapley interaction indices to understand not just which features matter, but which feature pairs drive a prediction together.

Classification
Regression

from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split
from tabpfn import TabPFNClassifier
from tabpfn_extensions.interpretability.shapiq import get_tabpfn_imputation_explainer

X, y = load_breast_cancer(return_X_y=True, as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

clf = TabPFNClassifier(fit_mode="fit_with_cache")
clf.fit(X_train, y_train)

# k-SII captures pairwise feature interactions
explainer = get_tabpfn_imputation_explainer(
    model=clf,
    data=X_train,
    index="k-SII",
    max_order=2,
)

sv = explainer.explain(X_test.iloc[0:1].values, budget=128)
print(sv)              # top interactions ranked by magnitude
sv.plot_waterfall()    # waterfall plot showing additive contributions

from sklearn.datasets import load_diabetes
from sklearn.model_selection import train_test_split
from tabpfn import TabPFNRegressor
from tabpfn_extensions.interpretability.shapiq import get_tabpfn_imputation_explainer

X, y = load_diabetes(return_X_y=True, as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

reg = TabPFNRegressor(fit_mode="fit_with_cache")
reg.fit(X_train, y_train)

# SV with max_order=1 gives plain Shapley values (no interactions)
explainer = get_tabpfn_imputation_explainer(
    model=reg,
    data=X_train,
    index="SV",
    max_order=1,
)

sv = explainer.explain(X_test.iloc[0:1].values, budget=128)
sv.plot_waterfall()

Because TabPFN follows the sklearn API, you can also hand predict_proba to a shap explainer directly when you run TabPFN locally and reuse the same values for both the global beeswarm above and per-sample waterfalls (pip install shap):

import numpy as np
import shap

predict = lambda A: clf.predict_proba(np.asarray(A))[:, 1]
explainer = shap.PermutationExplainer(predict, shap.sample(X_train, 50, random_state=42))
sv = explainer(X_test, max_evals=2 * X_test.shape[1] + 1)

shap.plots.beeswarm(sv, max_display=X_test.shape[1])  # global view
shap.plots.waterfall(sv[0])                           # one prediction

Waterfall plot for the highest-risk patient

Waterfall plot for the lowest-risk patient

Waterfall explanations for the highest-risk (left, 100%) and lowest-risk (right, 1%) patient in the test set. Both start from the same population base rate of 53% and the bars show how each feature moved that patient’s predicted probability. See the Interpreting Results cookbook for the borderline case and the full setup.

Explain many rows with the cloud API

With tabpfn_client, use tabpfn_client.explain.permutation_shap. It sends the rows of many explanations in each API request, and it gives the same plots as the example above.

from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split
from tabpfn_client import TabPFNClassifier
from tabpfn_client.explain import permutation_shap
import shap

X, y = load_breast_cancer(return_X_y=True, as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

clf = TabPFNClassifier()  # keep the default fit_mode
clf.fit(X_train, y_train)

result = permutation_shap(
    clf.predict_proba,   # pass the method itself, not a lambda
    X_test,
    background=X_train,  # 100 rows are sampled from it for the hidden features
    random_state=42,
)

sv = result.to_shap()[:, :, 1]  # shap.Explanation for the positive class
shap.plots.beeswarm(sv)
shap.plots.waterfall(sv[0])

We advise against using shap.PermutationExplainer with tabpfn_client, as it calls the model about two times for each explained row. Each call is one API request, so 1,000 rows need about 2,000 requests and can take more than 20 minutes.

Requests, cost and settings

Requests. By default, each request has at most 50,000 rows, and fewer when the API accepts fewer. Larger requests cost more tokens per row. Set batch_size to change it.Fit the model with the default fit_mode. With fit_mode="fit_with_cache", each request has at most 10,000 rows, so permutation_shap needs more requests and is slower. It gives a warning in that case.Cost. Each predicted row counts toward your usage. The number of rows is at most:

n_background × (1 + len(X) × (1 + 2 × n_permutations × (n_features − 1)))

To estimate the tokens before you start, price one full request with estimate_cost and multiply by the number of requests:

import math
import numpy as np
from tabpfn_client import estimate_cost

n_rows = 100 * (1 + len(X_test) * (1 + 2 * 2 * (X_test.shape[1] - 1)))
per_request = estimate_cost(X_train, np.empty((50_000, X_test.shape[1])))
print(per_request.estimated_cost * math.ceil(n_rows / 50_000))  # upper bound

Setting	Effect
`n_background`	Default `100`. Rows sampled from `background`. The cost increases linearly with it. Below about 100 rows, more rows reduce the error more than more permutations for the same cost.
`n_permutations`	Default `2`. The cost increases linearly with it. Increase it if values change too much between runs with different `random_state`.
`background`	Usually the training data. It must have the same columns and dtypes as `X`.
`random_state`	Set it to get the same values each run.

Visualize global feature effects with Partial Dependence Plots

PDP and ICE curves show how a feature affects predictions across the whole dataset, not just one sample.

Classification
Regression

from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split
from tabpfn import TabPFNClassifier
from tabpfn_extensions.interpretability.pdp import partial_dependence_plots

X, y = load_breast_cancer(return_X_y=True, as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

clf = TabPFNClassifier()
clf.fit(X_train, y_train)

# PDP for two features; set kind="individual" for ICE, or "both" for overlay
partial_dependence_plots(
    clf, X_test.values,
    features=[0, 1],
    kind="average",
    target_class=1,
)

from sklearn.datasets import load_diabetes
from sklearn.model_selection import train_test_split
from tabpfn import TabPFNRegressor
from tabpfn_extensions.interpretability.pdp import partial_dependence_plots

X, y = load_diabetes(return_X_y=True, as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

reg = TabPFNRegressor()
reg.fit(X_train, y_train)

# 1D partial dependence for features 0 and 2, with ICE overlay
partial_dependence_plots(reg, X_test.values, features=[0, 2], kind="both")

# 2D interaction plot
partial_dependence_plots(reg, X_test.values, features=[(0, 2)])

Partial dependence plots for four continuous features

Partial dependence for the four most important continuous features of the coronary-disease model. Where SHAP shows attribution, partial dependence shows shape: risk climbs steeply with the number of blocked vessels, falls with maximum heart rate (better exercise capacity is protective), and cholesterol is nearly flat over its observed range.

The remove-and-recontextualize alternative

get_tabpfn_explainer uses the remove-and-recontextualize paradigm (Rundel et al. 2024): TabPFN is re-fit for every coalition, so the KV cache cannot be reused — expect this path to be substantially slower than the recommended get_tabpfn_imputation_explainer. Reach for it when you specifically want this paradigm. It also takes the training labels and does not need fit_mode.

from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split
from tabpfn import TabPFNClassifier
from tabpfn_extensions.interpretability.shapiq import get_tabpfn_explainer

X, y = load_breast_cancer(return_X_y=True, as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

clf = TabPFNClassifier()
clf.fit(X_train, y_train)

explainer = get_tabpfn_explainer(model=clf, data=X_train, labels=y_train)
sv = explainer.explain(X_test.iloc[0:1].values, budget=128)
sv.plot_waterfall()

Feature selection

Sequential feature selection identifies the minimal subset of features that contributes most to model performance:

from tabpfn_extensions.interpretability.feature_selection import feature_selection

result = feature_selection(clf, X_train.values, y_train.values, n_features_to_select=5)
X_selected = result.selector.transform(X_test.values)
print("Selected feature indices:", result.selected_indices)
print(f"CV score: {result.selected_score_mean:.4f} ± {result.selected_score_std:.4f}")

Controlling the budget parameter

The budget parameter in explainer.explain() sets how many coalition samples shapiq evaluates to approximate Shapley values. Each coalition is a subset of features — evaluating more of them produces more accurate estimates but costs more model calls. In theory, exact Shapley values require evaluating all 2^n feature subsets (e.g. 1024 for 10 features, ~1 billion for 30). In practice, shapiq’s approximation algorithms converge well before that:

Number of features	Suggested budget	Notes
Few features (< 10)	`64`–`128`	Converges quickly; low budgets are fine
Medium (10–20 features)	`128`–`512`	Good accuracy/speed tradeoff
Many features (20+)	`512`–`2048`	Higher budgets help, but returns diminish

Start low (e.g. budget=128) and increase only if the resulting explanations look noisy or unstable across repeated runs.

Library Reference

See the Interpretability reference for generated signatures, parameter tables, return types, and links to the classes that accept forwarded keyword arguments.

FAQ

GPU setup, batch inference, and performance tuning.

Classification

Binary and multi-class classification guide.

Regression

Point estimates, quantiles, and full distributions.

Fine-Tuning

Adapt TabPFN to your domain-specific data.

Getting Started

Capabilities

Using the API

Agentic

Integrations

Troubleshooting

TabPFN in Action

Customer References

Changelog

Why TabPFN is Well-Suited for Interpretability

Installation

Quickstart

Choosing a Method

Use Cases

Explain a prediction with shapiq

Explain many rows with the cloud API

Visualize global feature effects with Partial Dependence Plots

The remove-and-recontextualize alternative

Feature selection

Controlling the budget parameter

Library Reference

FAQ

Classification

Regression

Fine-Tuning

​Why TabPFN is Well-Suited for Interpretability

​Installation

​Quickstart

​Choosing a Method

​Use Cases

​Explain a prediction with shapiq

​Explain many rows with the cloud API

​Visualize global feature effects with Partial Dependence Plots

​The remove-and-recontextualize alternative

​Feature selection

​Controlling the budget parameter

​Library Reference

FAQ

Classification

Regression

Fine-Tuning

Why TabPFN is Well-Suited for Interpretability

Installation

Quickstart

Choosing a Method

Use Cases

Explain a prediction with shapiq

Explain many rows with the cloud API

Visualize global feature effects with Partial Dependence Plots

The remove-and-recontextualize alternative

Feature selection

Controlling the budget parameter

Library Reference