SHAP values are defined relative to a cooperative game. The background data and masker define what hidden features mean and therefore help define the question being answered. They are not merely performance parameters.
For a row x, an explanation decomposes a model output relative to a baseline:
explained output = base value + sum(feature attributions)
The baseline and attributions depend on the reference distribution used when features are hidden.
Examples of distinct questions:
These questions can produce different baselines, signs, magnitudes, and rankings. State the intended question before sampling background rows.
Use background data that:
Do not use:
Larger backgrounds increase cost for interventional tree, deep, kernel, and permutation methods. Current SHAP maskers default to at most 100 tabular background rows in several APIs.
Treat size as an empirical convergence choice:
shap.sample samples without replacement:
background = shap.sample(X_train, 100, random_state=7)
For heterogeneous populations, stratified sampling may be more appropriate:
background = (
training_frame.groupby("site", group_keys=False)
.sample(n=20, random_state=7)
.drop(columns="site")
)
Only stratify on information legitimately available at the prediction time and relevant to the reference population.
Independentmasker = shap.maskers.Independent(background, max_samples=100)
Hidden features are replaced by values from background rows and integrated over that marginal reference distribution.
Use when:
Risk: combining observed and background columns can create off-manifold or impossible rows when features are dependent.
Partitionmasker = shap.maskers.Partition(
background,
max_samples=100,
clustering="correlation",
)
Partition constrains coalitions using a hierarchical feature tree. With PartitionExplainer, this produces Owen values for the constrained game.
Use when:
clustering can be:
"correlation" for common tabular use;Correlation clustering is descriptive, not causal. Review the tree rather than assuming automatically derived groups are scientifically valid.
Imputemasker = shap.maskers.Impute(background, method="linear")
Impute estimates hidden features conditional on observed features. It is commonly paired with LinearExplainer for correlation-aware allocations.
Conditional games can give attribution to a feature the model does not directly use because that feature carries information about a used feature. Do not interpret such an attribution as a model coefficient or intervention effect.
Fixed and composite maskersFixed: leaves an input unchanged; useful for fixed labels or auxiliary arguments.Composite: joins maskers for multiple model inputs.FixedComposite: returns both masked and original inputs.OutputComposite: combines masking with a model output used by an explanation algorithm.Use these only after verifying the model's full call signature with a one-row test.
masker = shap.maskers.Text(tokenizer)
Text masking respects tokenizer boundaries and can create a token hierarchy for PartitionExplainer. The mask token, collapse behavior, and tokenizer special tokens affect the explanation.
masker = shap.maskers.Image("inpaint_telea", image_shape)
Supported masking approaches include blurring, inpainting, and constant values. Each asks a different counterfactual question. Inpainting may create plausible local texture but does not guarantee an in-distribution image.
See modalities.md for full workflows.
There is no universally correct single-feature allocation when inputs share information.
An independent masker asks how model output changes while integrating hidden features over a marginal reference. It can expose the model's functional dependence, including behavior on unrealistic combinations.
A conditional masker asks how model output changes under an estimated conditional distribution. It stays closer to the observed manifold but can allocate credit to unused correlated features.
A partition game attributes to hierarchical coalitions, reducing arbitrary competition among related features. Individual values remain conditional on the chosen hierarchy.
For important correlated features:
If a model consumes transformed columns, SHAP explains those transformed inputs unless the entire preprocessing pipeline is wrapped in the model callable.
Advantages:
Requirements:
feature_names = preprocessor.get_feature_names_out()
X_background_t = preprocessor.transform(X_background)
X_eval_t = preprocessor.transform(X_eval)
explainer = shap.Explainer(
model,
X_background_t,
feature_names=feature_names.tolist(),
)
exp = explainer(X_eval_t)
Only attach names when their order exactly matches the transformed matrix.
Wrap the full pipeline in a callable:
def predict_positive(frame):
return fitted_pipeline.predict_proba(frame)[:, 1]
masker = shap.maskers.Independent(raw_background, max_samples=100)
explainer = shap.PermutationExplainer(
predict_positive,
masker,
feature_names=raw_background.columns.tolist(),
seed=7,
)
exp = explainer(raw_eval, max_evals=2 * raw_eval.shape[1] + 1)
This attributes raw columns but may be much slower and uses model-agnostic masking. Ensure the callable preserves DataFrame columns and dtypes.
Distinguish:
Do not manually replace masked values with NaN unless the masker and model are designed for that operation. For tree models, missing-value routing can be model-library-specific. Validate explanations after upgrading SHAP or the tree library.
Use a shared background when comparing cohorts if the goal is to compare model behavior against one common reference. Separate cohort-specific backgrounds change both baselines and attributions, confounding reference-population differences with model-use differences.
If separate backgrounds are scientifically necessary:
A background distribution can change subgroup explanations but cannot establish fairness.
Do not infer:
Proxy features, calibration, base rates, thresholds, error rates, and label quality require separate analysis.
Store:
Do not place secrets, protected health information, or direct identifiers into plot labels or exported explanation JSON.