shap_enhanced.explainers.SCSHAP

Sparse Coalition SHAP Explainer

Theoretical Explanation

Sparse Coalition SHAP is a feature attribution method specifically designed for sparse, discrete, or structured inputs—such as one-hot encodings and binary feature sets. Unlike standard SHAP approaches that may generate invalid or unrealistic feature perturbations, Sparse Coalition SHAP only considers valid coalitions that preserve the sparsity and logical structure of the input space.

For one-hot encoded groups, masking a group zeroes out the entire set—representing “no selection”—without producing fractional or ambiguous class encodings. For binary features, masking is performed element-wise while maintaining input validity.

This approach ensures all perturbed inputs remain on-manifold, improving both interpretability and the validity of model attributions in discrete domains.

Key Concepts

  • Valid Sparse Coalitions:

    Coalitions are restricted to those that produce syntactically valid inputs under the sparsity constraints. This avoids creating feature patterns that would never occur naturally.

  • One-Hot Group Support:

    Groups of mutually exclusive features (e.g., one-hot encodings) are masked by setting the entire group to zero, simulating “no class selected.”

  • Binary Feature Support:

    Element-wise masking is applied to binary features, allowing localized coalitions across time and features.

  • Flexible Masking Strategies:
    • Default: zero-masking.

    • Extensible to other strategies (e.g., pattern sampling from background data).

  • Additivity Normalization:

    Final attributions are normalized so their total matches the difference between the model outputs of the original and fully-masked inputs.

Algorithm

  1. Initialization:
    • Accepts the target model, background dataset, one-hot group definitions, masking strategy (default: zero),

      and device configuration.

  2. Coalition Sampling:
    • For each one-hot group or binary feature:
      • Randomly sample subsets of other groups/features to form coalitions.

      • For each coalition:
        • Mask the selected features/groups in the input.

        • Mask the coalition plus the current target group/feature.

        • Compute the model outputs for both variants.

        • Record the output difference.

  3. SHAP Value Estimation:
    • Average the output differences over many sampled coalitions to approximate the Shapley value

      (i.e., the marginal contribution) of each group/feature.

  4. Normalization:
    • Scale all attributions so their sum equals the model output difference between

      the original and fully-masked inputs.

Use Case

Ideal for models operating on:
  • Categorical variables represented via one-hot encoding.

  • Structured binary inputs (e.g., presence/absence features).

  • Sparse input spaces where validity and interpretability are critical.

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” [Discusses conditional sampling for discrete and dependent features, relevant to preserving input structure] :contentReference[oaicite:1]{index=1}

  • Redelmeier, Jullum & Aas (2020), “Explaining predictive models with mixed features using Shapley values and conditional inference trees” [Imputes discrete/categorical features via conditional rules—addresses one-hot and binary feature dependencies] :contentReference[oaicite:2]{index=2}

  • Jullum et al. (2021), “groupShapley: Efficient prediction explanation with Shapley values for feature groups” [Introduces feature-group-wise Shapley values—related to grouping one-hot encoded variables as a coalition block] :contentReference[oaicite:3]{index=3}

  • Laberge & Pequignot (2022), “Understanding Interventional TreeSHAP: How and Why it Works” [Covers interventional masking logic for one-hot encoded and categorical features in TreeSHAP context] :contentReference[oaicite:4]{index=4}

  • Molnar, _Interpretable Machine Learning_ (2022), SHAP chapter [Practical guidance on masking strategies, grouping discrete features, and ensuring validity under sparsity] :contentReference[oaicite:5]{index=5}

Classes

SparseCoalitionSHAPExplainer(model, background)

SparseCoalitionSHAPExplainer: Valid SHAP for Structured Sparse Inputs

class shap_enhanced.explainers.SCSHAP.SparseCoalitionSHAPExplainer(model, background, onehot_groups=None, mask_strategy='zero', device=None)[source]

Bases: BaseExplainer

SparseCoalitionSHAPExplainer: Valid SHAP for Structured Sparse Inputs

This explainer approximates Shapley values by sampling valid sparse coalitions of features. It ensures that perturbed inputs remain syntactically valid, especially for inputs with structured sparsity such as one-hot encodings or binary indicator features.

Note

One-hot groups are masked as entire sets to simulate “no class selected”. General binary features are masked element-wise.

Parameters:
  • model (Any) – Predictive model to explain.

  • background (np.ndarray or torch.Tensor) – Background data (not directly used but required for base class).

  • onehot_groups (list[list[int]] or None) – List of one-hot index groups, e.g., [[0,1,2], [3,4]].

  • mask_strategy (str) – Currently supports only “zero” masking.

  • device (str) – Device context for evaluation (e.g., ‘cuda’ or ‘cpu’).

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]

Estimate SHAP values using sparse-valid coalitions.

For each input sample: - Iterates over all features (or one-hot groups). - Randomly samples subsets of other features/groups to form coalitions. - Computes model output difference when adding the current feature/group to the coalition. - Averages these differences to estimate the Shapley value.

\[\phi_i = \mathbb{E}_{S \subseteq N \setminus \{i\}} \left[ f(S \cup \{i\}) - f(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 instance(s), shape (T, F) or (B, T, F).

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

  • check_additivity (bool) – If True, prints the additivity check.

  • random_seed (int) – Seed for reproducible sampling.

Returns:

SHAP attribution values, same shape as input.

Return type:

np.ndarray