Shapley explainers

Looking for usage documentation? Check out Interpretability and KV cache.

`shapiq.get_tabpfn_imputation_explainer`

Gets a TabularExplainer from shapiq with imputation-based feature removal. The explainer uses an imputation-based paradigm of feature removal [3]: for each coalition, masked features are filled by an imputer and TabPFN is queried for a prediction. The training set is fixed across coalitions, so the KV cache makes this dramatically faster than the remove-and-recontextualize path (cf. get_tabpfn_explainer). A warning is emitted if the model is not configured for the cache. The default imputer is "baseline" (one fixed fill value per feature, so each coalition costs exactly one forward pass). Marginal/conditional imputers draw multiple samples per coalition and are 50-100x slower in practice without commensurate gains for in-context models — switch to them only if you have a specific reason.

shapiq.get_tabpfn_imputation_explainer(
    model: tabpfn.TabPFNRegressor | tabpfn.TabPFNClassifier,
    data: pd.DataFrame | np.ndarray,
    index: str = "k-SII",
    max_order: int = 2,
    imputer: str = "baseline",
    class_index: int | None = None,
    approximator = None,
    random_state: int | None = None,
    **kwargs,
)

Parameters

Parameter	Type	Default	Description
`model`	`tabpfn.TabPFNRegressor \| tabpfn.TabPFNClassifier`	Required	The TabPFN model to explain. Should be constructed with `fit_mode="fit_with_cache"` to engage the KV-cache fast path.
`data`	`pd.DataFrame \| np.ndarray`	Required	The background data to use for the explainer.
`index`	`str`	`"k-SII"`	The explanation index. Defaults to `"k-SII"`. For Shapley values like SHAP, use `index="SV"` with `max_order=1`. See the shapiq reference for the available indices.
`max_order`	`int`	`2`	The maximum order of interactions to consider. Defaults to `2`.
`imputer`	`str`	`"baseline"`	The imputation method to use. See `shapiq.TabularExplainer` documentation for more information and an up-to-date list of available imputation methods.
`class_index`	`int \| None`	`None`	The class index of the model to explain. If not provided, the class index will be set to `1` per default for classification models. This argument is ignored for regression models. Defaults to `None`.
`approximator`	—	`None`	The shapiq approximator to estimate the coalition game with. Defaults to `None`, which routes to the recommended estimator: `OddSHAP` for first-order Shapley values (`index="SV"`) and `ProxySHAP` for interaction indices (see `_resolve_approximator`). Pass a shapiq `Approximator` instance or a literal string (e.g. `"auto"`) to override the routing.
`random_state`	`int \| None`	`None`	Seed forwarded to the routed `OddSHAP`/`ProxySHAP` approximator for reproducible coalition sampling. Has no effect when an explicit `approximator` is passed or the `"auto"` fallback is used. Defaults to `None`.
`**kwargs`	—	—	Additional keyword arguments to pass to the explainer. See `shapiq.TabularExplainer` for keyword options.

Returns

Type	Description
`shapiq.TabularExplainer`	Explainer that imputes masked features while keeping the training data fixed.

References

[1] shapiq repository.
[2] Muschalik et al. (2024). shapiq: Shapley Interactions for Machine Learning.
[3] Lundberg and Lee (2017). A Unified Approach to Interpreting Model Predictions.

`shapiq.get_tabpfn_inf_explainer`

View source

Gets a TabularExplainer that masks missing features with +inf. When a coalition leaves a feature out, this explainer sets that feature to +inf and lets TabPFN’s native missing-value handling absorb it as “missing” — no sampling from a background distribution, just one forward pass per coalition. Since the training set never changes across coalitions, this is the fastest path on TabPFN v3: construct the model with fit_mode="fit_with_cache" and set model.executor_.keep_cache_on_device = True after .fit() so every coalition evaluation reuses one on-device KV cache. This differs from get_tabpfn_imputation_explainer — that one samples the absent features from a background distribution, so their values are drawn from the data. Here nothing is sampled: a masked feature is genuinely missing and TabPFN decides how to handle it. +inf (rather than NaN) is used deliberately: NaN is transformed by TabPFN’s preprocessing pipeline before it reaches the model, whereas +inf is carried through and handled natively as missingness. IMPORTANT: this requires the model to be constructed with inference_config={"PASSTHROUGH_INF": True} (available in tabpfn>=8.1.0). Without it, TabPFN rejects non-finite inputs at validation and this function raises ValueError up front rather than letting every coalition evaluation fail later. The remote backends forward the flag to the TabPFN they run, so this path works there too.

shapiq.get_tabpfn_inf_explainer(
    model: tabpfn.TabPFNRegressor | tabpfn.TabPFNClassifier,
    data: pd.DataFrame | np.ndarray,
    index: str = "SV",
    max_order: int = 1,
    class_index: int | None = None,
    approximator = None,
    random_state: int | None = None,
    **kwargs,
)

Parameters

Parameter	Type	Default	Description
`model`	`tabpfn.TabPFNRegressor \| tabpfn.TabPFNClassifier`	Required	The TabPFN model to explain. Must be constructed with `inference_config={"PASSTHROUGH_INF": True}`. For the v3 KV-cache fast path, also pass `fit_mode="fit_with_cache"` before `.fit(X, y)` and set `model.executor_.keep_cache_on_device = True` afterwards.
`data`	`pd.DataFrame \| np.ndarray`	Required	Background data. Only its shape (number of features) and a single row for shapiq’s compatibility check are used — it does not drive the masking, since absent features are replaced with `+inf` rather than sampled.
`index`	`str`	`"SV"`	The Shapley-style index to compute. Defaults to `"SV"` (plain Shapley values). See shapiq docs for alternatives.
`max_order`	`int`	`1`	Maximum interaction order. Defaults to `1` (individual feature attributions, equivalent to classical SHAP values).
`class_index`	`int \| None`	`None`	Class to explain for classification models. Defaults to `None` (shapiq uses class 1). Ignored for regression.
`approximator`	—	`None`	The shapiq approximator to estimate the coalition game with. Defaults to `None`, which routes to the recommended estimator: `OddSHAP` for first-order Shapley values (`index="SV"`, the default here) and `ProxySHAP` for interaction indices (see `_resolve_approximator`). Pass a shapiq `Approximator` instance or a literal string (e.g. `"auto"`) to override.
`random_state`	`int \| None`	`None`	Seed forwarded to the routed `OddSHAP`/`ProxySHAP` approximator for reproducible coalition sampling. Has no effect when an explicit `approximator` is passed or the `"auto"` fallback is used. Defaults to `None`.
`**kwargs`	—	—	Passed through to `shapiq.TabularExplainer`.

Returns

Type	Description
`shapiq.TabularExplainer`	Explainer that replaces masked features with `+inf`.

Raises ValueError If model can be introspected and does not have PASSTHROUGH_INF enabled. Example

>>> from tabpfn import TabPFNClassifier
>>> from tabpfn_extensions.interpretability import shapiq as tpe_shapiq
>>> clf = TabPFNClassifier(
...     inference_config={"PASSTHROUGH_INF": True},
...     fit_mode="fit_with_cache",
... )
>>> clf.fit(X_train, y_train)
>>> clf.executor_.keep_cache_on_device = True  # optional but faster
>>> explainer = tpe_shapiq.get_tabpfn_inf_explainer(
...     model=clf, data=X_train, class_index=1
... )
>>> iv = explainer.explain(x=X_test[0], budget=2 ** X_train.shape[1])

`shapiq.get_tabpfn_explainer`

View source

Get a TabPFNExplainer (remove-and-recontextualize) from shapiq. The explainer uses the remove-and-recontextualize paradigm of model explanation [2] [3]: for each coalition S, TabPFN is re-fit on the columns in S and predictions are made with that re-fitted model. This is expensive because every coalition triggers a fresh fit. NOTE: This path does not benefit from the KV cache even when the underlying model is configured with fit_mode="fit_with_cache". Each coalition does exactly one fit + one predict, so there are no repeated predicts to amortize the cache over. If you want the cache to actually speed things up, prefer get_tabpfn_imputation_explainer (which runs budget predicts against a single fit).

shapiq.get_tabpfn_explainer(
    model: tabpfn.TabPFNRegressor | tabpfn.TabPFNClassifier,
    data: pd.DataFrame | np.ndarray,
    labels: pd.DataFrame | np.ndarray,
    index: str = "k-SII",
    max_order: int = 2,
    class_index: int | None = None,
    approximator = None,
    random_state: int | None = None,
    **kwargs,
)

Parameters

Parameter	Type	Default	Description
`model`	`tabpfn.TabPFNRegressor \| tabpfn.TabPFNClassifier`	Required	The TabPFN model to explain.
`data`	`pd.DataFrame \| np.ndarray`	Required	The background data to use for the explainer.
`labels`	`pd.DataFrame \| np.ndarray`	Required	The labels for the background data.
`index`	`str`	`"k-SII"`	The explanation index. Defaults to `"k-SII"`. For Shapley values like SHAP, use `index="SV"` with `max_order=1`. See the shapiq reference for the available indices.
`max_order`	`int`	`2`	The maximum order of interactions to consider. Defaults to `2`.
`class_index`	`int \| None`	`None`	The class index of the model to explain. If not provided, the class index will be set to `1` per default for classification models. This argument is ignored for regression models. Defaults to `None`.
`approximator`	—	`None`	The shapiq approximator to estimate the coalition game with. Defaults to `None`, which routes to the recommended estimator: `OddSHAP` for first-order Shapley values (`index="SV"`) and `ProxySHAP` for interaction indices (see `_resolve_approximator`). Pass a shapiq `Approximator` instance or a literal string (e.g. `"auto"`) to override the routing.
`random_state`	`int \| None`	`None`	Seed forwarded to the routed `OddSHAP`/`ProxySHAP` approximator for reproducible coalition sampling. Has no effect when an explicit `approximator` is passed or the `"auto"` fallback is used. Defaults to `None`.
`**kwargs`	—	—	Additional keyword arguments to pass to the explainer. See `shapiq.TabPFNExplainer` for keyword options.

Returns

Type	Description
`shapiq.TabPFNExplainer`	Explainer that removes features and refits TabPFN for each coalition.

References

[1] shapiq repository.
[2] Muschalik et al. (2024). shapiq: Shapley Interactions for Machine Learning.
[3] Rundel et al. (2024). Interpretable Machine Learning for TabPFN.

`shap.shapiq_to_shap_explanation`

View source

Compute first-order Shapley values with a shapiq explainer for each row in X and wrap them in a shap.Explanation ready for use with shap.plots.* and shap.summary_plot. Mirrors the pattern in examples/interpretability/shap_example.py: one .explain(...) call per row, stack the first-order arrays into an (n, d) matrix, average baseline values, and pass everything to shap.Explanation.

shap.shapiq_to_shap_explanation(
    explainer: Any,
    X: ArrayLike,
    *,
    budget: int,
    feature_names: list[str] | None = None,
) -> shap.Explanation

Parameters

Parameter	Type	Default	Description
`explainer`	`Any`	Required	A shapiq explainer — e.g. one returned by `get_tabpfn_imputation_explainer(..., index="SV", max_order=1)`.
`X`	`ArrayLike`	Required	`(n, d)` array of rows to explain.
`budget`	`int`	Required	Number of model evaluations shapiq is allowed per row. For small `d` and exact Shapley values, pass `2**d`.
`feature_names`	`list[str] \| None`	`None`	Optional list of feature name strings (length `d`). Used by `shap.plots.*` for axis labels.

Returns

Type	Description
`shap.Explanation`	Shapley values for each input sample, with `values.shape == (n, d)`.

Notes Only first-order Shapley values are wrapped. shap.Explanation doesn’t represent higher-order interactions; for those, use shapiq’s native plots on the InteractionValues object. Requires shap to be installed (pip install shap). It is kept out of the interpretability extra by design — shapiq is the runtime dependency, shap is opt-in for plotting.

Reference

tabpfn

tabpfn-client

tabpfn-extensions

REST API

`shapiq.get_tabpfn_imputation_explainer`

`shapiq.get_tabpfn_inf_explainer`

`shapiq.get_tabpfn_explainer`

`shap.shapiq_to_shap_explanation`

​shapiq.get_tabpfn_imputation_explainer

​shapiq.get_tabpfn_inf_explainer

​shapiq.get_tabpfn_explainer

​shap.shapiq_to_shap_explanation

`shapiq.get_tabpfn_imputation_explainer`

`shapiq.get_tabpfn_inf_explainer`

`shapiq.get_tabpfn_explainer`

`shap.shapiq_to_shap_explanation`