> ## Documentation Index
> Fetch the complete documentation index at: https://docs.priorlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> TabPFN-3 and later versions support up to 1,000,000 rows, subject to feature count and checkpoint/API limits.
> For large datasets, use per-estimator subsampling, e.g. inference_config={"SUBSAMPLE_SAMPLES": 100_000}, in TabPFNClassifier or TabPFNRegressor from tabpfn or tabpfn_client.
> Pass raw pandas DataFrames to fit and predict. Categorical strings/categories, raw text, and missing feature values are handled automatically; no manual integer/one-hot encoding, imputation, scaling, or outlier removal is needed.

# SHAP explanations

> Explain multiple prediction rows with permutation SHAP.

> [!NOTE]
>
> Looking for usage documentation? Check out [Interpretability](https://docs.priorlabs.ai/capabilities/interpretability.md).

## `explain.permutation_shap`

[ View source ](https://github.com/PriorLabs/tabpfn-client/blob/ce678cec44dc715f4d835a44990a8f5f115b7acc/src/tabpfn_client/explain.py#L71)

Estimate SHAP values by antithetic permutation sampling.

This is the algorithm of `shap.PermutationExplainer` with an independent
masker: a hidden feature takes its values from each background row, and
the prediction is averaged over the background rows. `shap` calls the
model once per explained row, so a remote model pays the request overhead
for every row. This function predicts the masked rows of many explained
rows in each call of `predict_fn`.

Each set of shown features is predicted once per explained row, and the
all-hidden set once in total. So the number of masked rows is at most
`n_background * (1 + len(X) * (1 + 2 * n_permutations * (n_features - 1)))`,
and fewer when orderings share sets, which is common with few features.

```python theme={null}
explain.permutation_shap(
    predict_fn: Callable[[pd.DataFrame], Any],
    X: pd.DataFrame | np.ndarray,
    *,
    background: pd.DataFrame | np.ndarray,
    n_background: int | None = 100,
    n_permutations: int = 2,
    batch_size: int | None = None,
    random_state: int | None = None,
) -> ShapExplanation
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `predict_fn` | `Callable[[pd.DataFrame], Any]` | Required | Maps a DataFrame with the columns of `X` to predictions of shape (n,) or (n, n\_outputs), for example `model.predict_proba`. |
| `X` | `pd.DataFrame \| np.ndarray` | Required | The rows to explain. |
| `background` | `pd.DataFrame \| np.ndarray` | Required | Rows to sample the values of hidden features from, usually the training data. It must have the same columns and dtypes as `X`. |
| `n_background` | `int \| None` | `100` | Rows sampled from `background` without replacement. The cost grows linearly with it. `None`, or a value of at least `len(background)`, uses every row. |
| `n_permutations` | `int` | `2` | Feature orderings sampled per explained row. Each one is also evaluated in reverse. The cost grows linearly with it. For the same cost, more background rows reduce the error more than more orderings, up to about 100 background rows. |
| `batch_size` | `int \| None` | `None` | Most masked rows per call of `predict_fn`, and at least `n_background`. Memory holds one batch of masked rows, plus a part that grows with `len(X) * n_permutations * n_features`. `None` uses `DEFAULT_BATCH_SIZE`, or fewer rows when `predict_fn` is a method of a fitted [`TabPFNClassifier`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/configuration#constructor) or [`TabPFNRegressor`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/regressor/configuration#constructor) and the API accepts fewer in one request. A model fitted with `fit_mode="fit_with_cache"` gets `CACHED_FIT_BATCH_SIZE`. The byte limit is estimated from the average row size, so very uneven text columns can still exceed it. |
| `random_state` | `int \| None` | `None` | Seed for the sampled background rows and feature orderings. |

**Returns**

| Type | Description |
| - | - |
| `ShapExplanation` | The SHAP values of each row of `X`. |

**Raises**

`ValueError`

If an argument is invalid, or `predict_fn` returns the
wrong number of predictions.

***

## `explain.ShapExplanation`

[ View source ](https://github.com/PriorLabs/tabpfn-client/blob/ce678cec44dc715f4d835a44990a8f5f115b7acc/src/tabpfn_client/explain.py#L30)

SHAP values for a set of explained rows.

**Attributes**

| Attribute | Type | Description |
| - | - | - |
| `values` | `np.ndarray` | Per-feature attributions, shape (n\_rows, n\_features), or (n\_rows, n\_features, n\_outputs) for a model with several outputs such as `predict_proba`. |
| `base_values` | `np.ndarray` | Mean prediction over the background rows, shape (n\_rows,) or (n\_rows, n\_outputs). For each row, `base_values + values.sum(axis=1)` equals the model's prediction. |
| `data` | `pd.DataFrame` | The explained rows. |

***

## `ShapExplanation.to_shap`

[ View source ](https://github.com/PriorLabs/tabpfn-client/blob/ce678cec44dc715f4d835a44990a8f5f115b7acc/src/tabpfn_client/explain.py#L48)

Convert to a [`shap.Explanation`](https://shap.readthedocs.io/en/latest/generated/shap.Explanation.html), for use with the plots of `shap`.

```python theme={null}
ShapExplanation.to_shap() -> Any
```

**Returns**

| Type | Description |
| - | - |
| `Any` | A [`shap.Explanation`](https://shap.readthedocs.io/en/latest/generated/shap.Explanation.html) with the same values. |

**Raises**

`ImportError`

If `shap` is not installed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.