shap_enhanced.explainers.SPSHAP

Support-Preserving SHAP Explainer

Theoretical Explanation

Support-Preserving SHAP is a specialized feature attribution method tailored for sparse or structured discrete data, such as one-hot encodings or binary presence/absence features. Unlike traditional SHAP variants that create synthetic masked inputs (often resulting in out-of-distribution samples), this explainer only evaluates inputs that have been observed in the dataset and match the support pattern induced by masking.

For each coalition (subset of features to mask), the method attempts to find a real background sample with the same binary support (nonzero positions) as the masked instance. If no such sample exists, the coalition is skipped or flagged—ensuring that only valid, realistic inputs are used for estimating SHAP values.

For continuous or dense data, the method gracefully falls back to mean-masking (standard SHAP behavior).

Key Concepts

  • Support Pattern Matching:

    Masked inputs are replaced with real background examples that match the nonzero pattern (support) of the masked input. This maintains validity and avoids generating unrealistic inputs.

  • One-Hot / Binary Support:

    Especially effective for categorical features encoded as one-hot vectors or binary indicators. Masking respects group structures and ensures feasible combinations.

  • Graceful Fallback:

    When applied to continuous or dense data, the explainer defaults to mean-masking to retain applicability.

  • Additivity Normalization:

    Final attributions are scaled such that their total equals the model output difference between the original and fully-masked inputs.

Algorithm

  1. Initialization:

    • Accepts a model, background dataset, device context, and configuration for skipping or flagging unmatched patterns.

  2. Support-Preserving Masking:
    • For each sampled coalition of masked features:

      • Create a masked version of the input.

      • Find a background example with the same binary support (nonzero positions).

      • If no match is found, either skip or raise an exception based on configuration.

      • For non-sparse (dense) inputs, fallback to mean-masking.

  3. SHAP Value Estimation:
    • For each feature:

      • Repeatedly sample coalitions of other features.

      • For each:

        • Mask the coalition and find a matching background sample.

        • Mask the coalition plus the feature of interest and find another match.

        • Compute the model output difference.

      • Average these differences to estimate the feature’s marginal contribution.

  4. Normalization:
    • Scale the final attributions so their sum matches the model output difference

      between the unmasked and fully-masked input.

Use Case

Ideal for:

  • One-hot encoded categorical features.

  • Binary indicators (presence/absence).

  • Sparse high-dimensional data where only valid observed patterns should be used for attribution.

References

  • Lundberg & Lee (2017), “A Unified Approach to Interpreting Model Predictions” [SHAP foundation—coalitional feature attribution framework]

  • Aas, Jullum & Løland (2021), “Explaining individual predictions when features are dependent: More accurate approximations to Shapley values” [Introduces empirical conditional sampling to handle feature dependence—precursor to support-based masking] :contentReference[oaicite:1]{index=1}

  • Redelmeier, Jullum & Aas (2020), “Explaining predictive models with mixed features using Shapley values and conditional inference trees” [Uses conditional inference tree models to mask or impute categorical/binary features while preserving valid structures] :contentReference[oaicite:2]{index=2}

  • Jullum et al. (2021), “groupShapley: Efficient prediction explanation with Shapley values for feature groups” [Supports grouping features (e.g., one‑hot groups) as units for coalition explanation—informing valid group-level attribution] :contentReference[oaicite:3]{index=3}

  • Laberge & Pequignot (2022), “Understanding Interventional TreeSHAP: How and Why it Works” [Analyzes how TreeSHAP preserves valid one‑hot/categorical support during coalition masking using interventional logic] :contentReference[oaicite:4]{index=4}

  • Molnar, *Interpretable Machine Learning* (2022), SHAP chapter [Discusses practical techniques for masking in structured and sparse input domains and emphasizes validity of perturbed inputs] :contentReference[oaicite:5]{index=5}

Classes

SupportPreservingSHAPExplainer(model, background)

SupportPreservingSHAPExplainer: Real-Pattern-Constrained SHAP Estimator
class shap_enhanced.explainers.SPSHAP.SupportPreservingSHAPExplainer(model, background, skip_unmatched=True, device=None)[source]

Bases: BaseExplainer

SupportPreservingSHAPExplainer: Real-Pattern-Constrained SHAP Estimator

This explainer approximates SHAP values by generating only masked inputs that match real examples in the dataset—preserving the discrete or sparse structure of the input space. It avoids out-of-distribution perturbations by requiring coalitions (masked variants) to have binary support patterns that exist in the original data.

If the data is not sparse (e.g., continuous), the method falls back to mean-masking, akin to standard SHAP explainers.

Parameters:

  • model (Any) – Predictive model to explain.

  • background (np.ndarray or torch.Tensor) – Dataset used to match support patterns (shape: (N, T, F) or (N, F)).

  • skip_unmatched (bool) – If True, coalitions without support-matching background samples are skipped.

  • device (str) – Device to evaluate model on (‘cpu’ or ‘cuda’).

property expected_value

Optional property returning the expected model output on the background dataset.

Returns:

Expected value if defined by the subclass, else None.

Return type:

float or None

explain(X, **kwargs)

Alias to shap_values for flexibility and API compatibility.

Parameters:

  • X (Union[np.ndarray, torch.Tensor, list]) – Input samples to explain.

  • kwargs – Additional arguments.

Returns:

SHAP values.

Return type:

Union[np.ndarray, list]

shap_values(X, nsamples=100, check_additivity=True, random_seed=42, **kwargs)[source]

Compute SHAP values by evaluating only valid support-preserving perturbations.

For sparse inputs (e.g., one-hot or binary):

  • For each feature, sample coalitions of other features.

  • Construct masked inputs and locate matching background samples with same nonzero support.

  • Evaluate model differences with and without the feature of interest.

  • Average differences to estimate SHAP values.

For dense inputs: - Fallback to standard mean-based masking for each feature individually.

\[\phi_i = \mathbb{E}_{S \subseteq N \setminus \{i\}} \left[ f(x_{S \cup \{i\}}) - f(x_S) \right]\]

Final attributions are normalized such that:

\[\sum_i \phi_i = f(x) - f(x_{\text{masked}})\]
Parameters:

  • X (np.ndarray or torch.Tensor) – Input sample or batch of shape (T, F) or (B, T, F).

  • nsamples (int) – Number of coalition samples per feature.

  • check_additivity (bool) – If True, prints sum of SHAP vs model output difference.

  • random_seed (int) – Seed for reproducibility.

Returns:

SHAP attributions with same shape as input.

Return type:

np.ndarray