SHAP explanations

Looking for usage documentation? Check out Interpretability.

`explain.permutation_shap`

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.

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` or `TabPFNRegressor` 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

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

Convert to a shap.Explanation, for use with the plots of shap.

ShapExplanation.to_shap() -> Any

Returns

Type	Description
`Any`	A `shap.Explanation` with the same values.

Raises ImportError If shap is not installed.

Reference

tabpfn

tabpfn-client

tabpfn-extensions

tabpfn-rel

REST API

`explain.permutation_shap`

`explain.ShapExplanation`

`ShapExplanation.to_shap`

​explain.permutation_shap

​explain.ShapExplanation

​ShapExplanation.to_shap

`explain.permutation_shap`

`explain.ShapExplanation`

`ShapExplanation.to_shap`