skip to content

When shap.Explainer runs with algorithm="auto", how does it decide which explainer to build for a given model and masker?

level: middleimportance: should knowfreq 16%

answer

  1. model-specific checks come first
  2. linear, then tree, then additive
  3. callable fallback depends on the masker
  4. Independent: 10 features; Partition: 32
  5. Kernel, Deep and Gradient never auto-picked

basics

~20 s

shap.Explainer tries the linear, tree and additive explainers in turn; failing those, a callable model gets exact or permutation by masker type and feature count, or partition for text and image maskers. Kernel, Deep and Gradient are never chosen.

solid answer

~40 s

`shap.Explainer(model, masker)` first wraps a DataFrame or 2-D array masker as `shap.maskers.Independent` (or `Partition` if you asked for `algorithm="partition"`). With `algorithm="auto"` it then asks `LinearExplainer`, `TreeExplainer` and `AdditiveExplainer` in that order whether they support the model with that masker. If none does and the model is callable, the masker decides: an `Independent` masker gives "exact" up to 10 features and "permutation" above; a `Partition` masker gives "exact" up to 32 and "permutation" above; a text or image masker that carries a clustering gives "partition"; anything else gives "permutation". A non-callable model it cannot parse raises a `TypeError`. Kernel and Gradient are not even in the `algorithm` list, and "deep" is never auto-selected, so those are built directly. Check `type(explainer).__name__` to see what you got.

code

python · 13 lines
python
import shap

# A plain function over a 48-column DataFrame
explainer = shap.Explainer(partner_predict, X_background)
print(type(explainer).__name__)   # PermutationExplainer: 48 > 10 features

# The LightGBM model object parses as a tree ensemble
explainer = shap.Explainer(quote_model, X_background)
print(type(explainer).__name__)   # TreeExplainer

# Its bound predict method does not
explainer = shap.Explainer(quote_model.predict, X_background)
print(type(explainer).__name__)   # PermutationExplainer: tree path lost

go deeper

for a junior

Remember that shap.Explainer picks an algorithm for you, that a tree model object becomes TreeExplainer, and that a plain function becomes an exact or permutation explainer.

for a middle

Walk the order: masker wrapping, then the linear, tree and additive checks, then the callable fallback with its 10- and 32-feature cut-offs, and name what auto never builds.

for a senior

Show you would assert the built class in a batch job, keep model objects rather than predict wrappers, and build Deep, Gradient or Kernel explainers explicitly when you mean them.

for a principal

Argue for pinning algorithm= explicitly in shared explanation code, so a wrapper change or a feature-count change cannot silently switch exactness and cost.

## What the unified Explainer is `shap.Explainer` is the front door of the **shap** library. You call `shap.Explainer(model, masker, algorithm="auto")` and get back an object whose class is one of the concrete explainers: the constructor literally swaps its own class to `TreeExplainer`, `PermutationExplainer` and so on. Knowing what "auto" picks matters because the choice decides both **exactness** and **run time**, and the unified call gives no message about which one it took. ## Step 1: the masker is normalised Before any choice, the masker argument is wrapped: - a pandas **DataFrame** or a 2-D NumPy or sparse array becomes `shap.maskers.Independent(data)`, or `shap.maskers.Partition(data)` when you passed `algorithm="partition"`; - a `transformers` tokenizer becomes a `shap.maskers.Text` masker; - a masker object you built yourself is kept as it is. The default `Independent` masker keeps at most `max_samples=100` background rows, which matters later for cost. ## Step 2: model-specific explainers are tried in order With `algorithm="auto"`, three checks run in sequence, each a `supports_model_with_masker(model, masker)` call: 1. **Linear**: the masker is `Independent`, `Partition` or `Impute`, and shap can parse a linear model's coefficients. 2. **Tree**: the masker is `Independent` or `None`, and the model object parses as a supported tree ensemble (LightGBM, XGBoost, CatBoost, most scikit-learn trees). 3. **Additive**: one specific glass-box additive model type is recognised. The first one that says yes wins. For a freight quote engine's LightGBM regressor, `shap.Explainer(quote_model, X_background)` becomes a `TreeExplainer`. ## Step 3: the callable fallback If no model-specific explainer applies, shap checks whether the model is **callable**. If it is, the masker decides: | Masker | Features | Algorithm chosen | |---|---|---| | `Independent` | 10 or fewer | "exact" | | `Independent` | more than 10 | "permutation" | | `Partition` | 32 or fewer | "exact" | | `Partition` | more than 32 | "permutation" | | text or image masker with a clustering | any | "partition" | | anything else | any | "permutation" | The thresholds follow cost. The exact algorithm with an `Independent` masker needs 2^M masked evaluations for M varying features; with a clustering it follows the hierarchy and needs on the order of M squared, which is why the `Partition` cut-off is higher. If the model is not callable and nothing parsed it, the constructor raises a `TypeError` saying the model cannot be analysed with the given masker. ## What auto never picks The `algorithm` argument accepts "auto", "permutation", "partition", "tree", "linear", "deep", "exact" and "additive". Note what is missing and what is never chosen: - **KernelExplainer** has no entry at all. It is the older standalone path, used by constructing `shap.KernelExplainer(f, data)` yourself. - **GradientExplainer** has no entry either; build `shap.GradientExplainer(model, data)` directly. - **"deep"** is in the list but auto never selects it. A PyTorch `nn.Module` is callable, so auto treats it as a black box and lands on exact or permutation, which also means feeding it whatever the masker produces rather than tensors. ## The traps this creates - **Passing `model.predict`.** A bound method is not a tree model, so the tree check fails and a 48-feature quote model is explained by the permutation algorithm: slower, approximate, and silent about it. - **Assuming Kernel.** Older tutorials taught `KernelExplainer` for black boxes; `shap.Explainer` on the same function gives a permutation or exact explainer instead, with different arguments (`max_evals`, not `nsamples`). - **Not checking.** `type(explainer).__name__` tells you what was built; log it in a batch job so a change in the model wrapper cannot quietly switch algorithms. ## Overriding the choice Auto is a convenience, not a contract. In shared code it is often clearer to name the algorithm: - `algorithm="tree"` or `algorithm="linear"` fails loudly if the model cannot be parsed, instead of drifting to a model-agnostic path; - `algorithm="permutation"` or `algorithm="exact"` fixes the black-box algorithm regardless of how many features a later model version has; - `algorithm="partition"` makes a DataFrame masker a `Partition` masker, so the explanation follows a feature clustering; - `seed=` on `shap.Explainer` is passed to the permutation algorithm, so reruns of a batch give the same values. Why a different algorithm or background changes the numbers is a question about Shapley values themselves; the library question is which algorithm you actually ran.

  • How do you get a KernelExplainer or GradientExplainer if algorithm="auto" never builds one?
    Construct the class yourself: `shap.KernelExplainer(f, background)` for the older sampling-regression path, or `shap.GradientExplainer(model, background)` for a PyTorch or TensorFlow network. Neither name is a value `algorithm=` accepts. For a network, `shap.DeepExplainer(model, background)` is likewise the direct call, because auto treats an `nn.Module` as an ordinary callable.
  • A callable model has 9 features and a DataFrame background; what does auto build, and what does one row cost?
    The DataFrame becomes an `Independent` masker, and 9 is at most 10, so auto builds an `ExactExplainer`. It needs 2^9 = 512 masked evaluations per row, each run over up to the 100 background rows the masker keeps, so up to 51,200 model predictions per explained row. At 20 features the same choice would need about a million masked evaluations, which is why the cut-off sits at 10.

  • algorithm="auto" falls back to KernelExplainer for any black-box model.
  • Passing model.predict instead of the model object makes no difference to the explainer.
  • shap.Explainer on a PyTorch module automatically uses DeepExplainer.
  • The auto choice depends only on the model, never on the masker.
  • ExactExplainer is never selected automatically because it is too slow.