shap_enhanced.explainers.CASHAP

CASHAP: Coalition-Aware SHAP Explainer

Theoretical Explanation

CASHAP (Coalition-Aware SHAP) is a Shapley value estimation framework tailored for models that process sequential or structured inputs, such as LSTMs. Unlike classical SHAP methods that treat features independently, CASHAP considers feature-time pairs—enabling attribution of both spatial and temporal components.

By explicitly sampling coalitions (subsets) of feature-time pairs and measuring marginal contributions, CASHAP provides granular, context-aware explanations. It also supports multiple imputation strategies to ensure the perturbed inputs remain valid and interpretable.

Key Concepts

  • Coalition Sampling: For every feature-time pair ((t, f)), random subsets of all other positions are sampled.

    The contribution of ((t, f)) is assessed by adding it to each coalition and measuring the change in model output.

  • Masking/Imputation Strategies:

    • Zero masking: Replace masked values with zero.

    • Mean imputation: Use feature-wise means from background data.

    • Custom imputers: Support for user-defined imputation functions.

  • Model-Agnostic & Domain-General: While ideal for time-series and sequential models, CASHAP can also be applied to tabular data

    wherever structured coalition masking is appropriate.

  • Additivity Normalization: Attribution scores are scaled such that their total sum equals the difference in model output

    between the original input and a fully-masked version.

Algorithm

  1. Initialization:

    • Accepts a model, background data for imputation, masking strategy, optional custom imputer, and device context.

  2. Coalition Sampling:
    • For each feature-time pair ((t, f)):

      • Sample coalitions ( C subseteq (T imes F) setminus {(t, f)} ).

      • For each coalition ( C ):

        • Impute features in ( C ) using the chosen strategy.

        • Impute features in ( C cup {(t, f)} ).

        • Compute and record the model output difference.

  3. Attribution Estimation:

    • Average the output differences across coalitions to estimate the marginal contribution of ((t, f)).

  4. Normalization:
    • Normalize attributions so that their total matches the difference between the model’s prediction

      on the original and the fully-masked input.

References

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

  • Jutte et al. (2025), “C‑SHAP for time series: An approach to high‑level temporal explanations” [Applies concept‑based SHAP to structured temporal data; treats temporal segments or concepts as coalition elements] :contentReference[oaicite:1]{index=1}

  • Schlegel et al. (2019), “Towards a Rigorous Evaluation of XAI Methods on Time Series” [Evaluates how SHAP and other methods behave for sequential/time‑series models, highlighting temporal structure challenges] :contentReference[oaicite:2]{index=2}

  • Franco de la Peña et al. (2025), “ShaTS: A Shapley‑based Explainability Method for Time Series Models” [Proposes temporally aware grouping for Shapley attribution in sequential IoT data, preserving temporal dependencies] :contentReference[oaicite:3]{index=3}

  • Molnar, “Interpretable Machine Learning” (2022), SHAP chapter [Describes masking and coalition sampling strategies, including dealing with structured or dependent features]

Classes

CoalitionAwareSHAPExplainer(model[, ...])

Coalition-Aware SHAP (CASHAP) Explainer
class shap_enhanced.explainers.CASHAP.CoalitionAwareSHAPExplainer(model, background=None, mask_strategy='zero', imputer=None, device=None)[source]

Bases: BaseExplainer

Coalition-Aware SHAP (CASHAP) Explainer

Estimates Shapley values for models processing structured inputs (e.g., time-series, sequences) by sampling coalitions of feature-time pairs and computing their marginal contributions using various imputation strategies.

Parameters:

  • model (Any) – Model to be explained.

  • background (Optional[np.ndarray or torch.Tensor]) – Background data used for mean imputation strategy.

  • mask_strategy (str) – Strategy for imputing/masking feature-time pairs. Options: ‘zero’, ‘mean’, or ‘custom’.

  • imputer (Optional[Callable]) – Custom callable for imputation. Required if mask_strategy is ‘custom’.

  • device (Optional[str]) – Device on which computation runs. Defaults to ‘cuda’ if available.

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, coalition_size=None, mask_strategy=None, check_additivity=True, random_seed=42, **kwargs)[source]
Return type:

ndarray

Compute CASHAP Shapley values for structured inputs via coalition-aware sampling.

For each feature-time pair ((t, f)), randomly sample coalitions excluding ((t, f)), compute model outputs with and without the pair added, and average the marginal contributions. Attribution values are normalized so their total matches the model output difference between the original and fully-masked input.

\[\phi_{t,f} pprox \mathbb{E}_{C \subseteq (T imes F) \setminus \{(t,f)\}} \left[ f(C \cup \{(t,f)\}) - f(C)\]

ight]

Note

Normalization ensures: sum_{t=1}^T sum_{f=1}^F phi_{t,f} pprox f(x) - f(x_{ ext{masked}})