shap_enhanced.explainers.CMSHAP

Contextual Masking SHAP (CM-SHAP) Explainer for Sequential Models

Theoretical Explanation

CM-SHAP is a SHAP-style feature attribution method designed for sequential (time series) models. Instead of masking features with zeros or mean values, CM-SHAP uses context-aware imputation: masked values are replaced by interpolating between their immediate temporal neighbors (forward/backward average). This preserves the temporal structure and context, leading to more realistic and faithful perturbations for sequential data.

Key Concepts

  • Contextual Masking: When masking a feature at time t, its value is replaced by the average of its neighboring time steps (t-1 and t+1). For boundary cases (first or last time step), only the available neighbor is used.

  • Coalition Sampling: For each feature-time position (t, f), random coalitions (subsets of all other positions) are sampled. The marginal contribution of (t, f) is estimated by measuring the change in model output when (t, f) is added to the coalition.

  • Additivity Normalization: Attributions are normalized so their sum matches the model output difference between the original and fully-masked input.

Algorithm

  1. Initialization:

    • Accepts a model and device.

  2. Contextual Masking:

    • For each coalition (subset of features to mask), masked positions are replaced by the average of their immediate temporal neighbors.

  3. SHAP Value Estimation:
    • For each feature-time position (t, f), repeatedly:

      • Sample a random coalition of other positions.

      • Mask the coalition using contextual interpolation.

      • Mask the coalition plus (t, f) using contextual interpolation.

      • Compute the model output difference.

      • Average these differences to estimate the marginal contribution of (t, f).

    • Normalize attributions so their sum matches the difference between the original and fully-masked model output.

References

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

  • Bento et al. (2020), “TimeSHAP: Explaining Recurrent Models through Sequence Perturbations” [Extends KernelSHAP to sequential models, computing attributions for time‑step-level features] :contentReference[oaicite:1]{index=1}

  • Villani et al. (2022), “Feature Importance for Time Series Data: Improving KernelSHAP” [Introduces time-consistent SHAP and addresses feature masking in time‑series with temporal dependencies] :contentReference[oaicite:2]{index=2}

  • Nayebi et al. (2022), “WindowSHAP: An Efficient Framework for Explaining Time-series Classifiers…” [Partitions sequences into windows for SHAP, acknowledging temporal structure in coalition sampling] :contentReference[oaicite:3]{index=3}

  • Molnar, _Interpretable Machine Learning_ (2022), SHAP chapter [Discusses masking strategies and handling temporally dependent features in SHAP] :contentReference[oaicite:4]{index=4}

Classes

ContextualMaskingSHAPExplainer(model[, device])

Contextual Masking SHAP (CM-SHAP) Explainer for Sequential Models
class shap_enhanced.explainers.CMSHAP.ContextualMaskingSHAPExplainer(model, device=None)[source]

Bases: BaseExplainer

Contextual Masking SHAP (CM-SHAP) Explainer for Sequential Models

Estimates SHAP values for sequential inputs by replacing masked feature values with interpolated values from neighboring time steps. This context-aware masking strategy preserves temporal coherence and enables more realistic feature perturbation in time-series data.

Parameters:

  • model (Any) – Model to explain. Must accept NumPy arrays or PyTorch tensors.

  • device (Optional[str]) – Device to perform computations on (‘cpu’ or ‘cuda’). 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, check_additivity=True, random_seed=42, **kwargs)[source]

Estimate SHAP values using contextual (interpolated) masking.

Each feature-time pair (t, f) is evaluated by sampling coalitions of other positions, applying context-aware masking, and averaging the difference in model outputs when (t, f) is added to the coalition.

Interpolation strategy ensures continuity in time series by replacing masked values with averages of adjacent time steps:

\[\begin{split}x_{t,f}^{masked} = \begin{cases} x_{t+1,f}, & \text{if } t = 0 \\ x_{t-1,f}, & \text{if } t = T-1 \\ \frac{x_{t-1,f} + x_{t+1,f}}{2}, & \text{otherwise} \end{cases}\end{split}\]

Final attributions are normalized such that:

\[\sum_{t=1}^T \sum_{f=1}^F \phi_{t,f} \approx f(x) - f(x_{masked})\]
Parameters:

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

  • nsamples (int) – Number of sampled coalitions per position.

  • check_additivity (bool) – Whether to normalize SHAP values to match output difference.

  • random_seed (int) – Random seed for reproducibility.

Returns:

SHAP values with same shape as input.

Return type:

np.ndarray