shap_enhanced.explainers.ERSHAP

ER-SHAP: Ensemble of Random SHAP Explainer

Theoretical Explanation

ER-SHAP is a computationally efficient, ensemble-based approximation of Shapley values, designed for both sequential and tabular models. Instead of exhaustively enumerating all possible coalitions, ER-SHAP repeatedly samples random subsets of feature–timestep positions and estimates their marginal contributions to model output.

This stochastic approach significantly accelerates SHAP estimation while maintaining interpretability, especially in high-dimensional or temporal settings. ER-SHAP also allows prior knowledge (e.g., feature importance) to guide coalition sampling through weighted schemes.

Key Concepts

  • Random Coalition Sampling:

    For each position ((t, f)), sample coalitions ( C subseteq (T imes F) setminus {(t, f)} ) and estimate the marginal contribution of ((t, f)) by measuring its impact on model output.

  • Weighted Sampling:

    Coalition sampling can be uniform or weighted based on prior feature importance scores or positional frequency, allowing informed, efficient sampling.

  • Flexible Masking:
    Masked features are imputed using:

    • Zeros (hard masking).

    • Feature-wise means from the background dataset (soft masking).

  • Additivity Normalization:

    Final attributions are scaled so that their sum matches the model output difference between the original and fully-masked input.

Algorithm

  1. Initialization:
    • Accepts a model, background dataset for imputation, number of sampled coalitions,

      masking strategy (‘zero’ or ‘mean’), weighting scheme, optional feature importance, and device context.

  2. Coalition Sampling:
    • For each feature–timestep pair ((t, f)):

      • Sample coalitions ( C subseteq (T imes F) setminus {(t, f)} ), either uniformly or using weights.

      • For each coalition:

        • Impute the coalition ( C ) in the input.

        • Impute the coalition ( C cup {(t, f)} ).

        • Compute the model output difference.

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

  3. Normalization:
    • Scale the final attributions so that their total equals the difference in model output

      between the original input and a fully-masked baseline.

References

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

  • Castro et al. (2009) and Mann & Shapley (1960), Monte Carlo sampling for Shapley values [Introduces simple uniform random sampling of permutations/coalitions for Shapley estimation] :contentReference[oaicite:1]{index=1}

  • Okhrati & Lipani (2020), “A Multilinear Sampling Algorithm to Estimate Shapley Values” [Proposes variance-reduced sampling for Shapley value estimation via multilinear extensions] :contentReference[oaicite:2]{index=2}

  • Witter et al. (2025), “Regression‑adjusted Monte Carlo Estimators for Shapley Values and Probabilistic Values” [Combines Monte Carlo with regression adjustments to achieve more efficient, low-variance Shapley approximations] :contentReference[oaicite:3]{index=3}

  • Rozemberczki et al. (2023), “Ensembles of Random SHAPs” (ER‑SHAP) [Directly describes ER‑SHAP: building ensembles of SHAPs over random subsets and averaging—also includes weighted sampling via preliminary importance] :contentReference[oaicite:4]{index=4}

  • Maleki et al. (2013), “Bounding the Estimation Error of Sampling‑based Shapley Value Approximation” [Provides theoretical error bounds for Monte Carlo approximation and discusses stratified sampling for variance reduction] :contentReference[oaicite:5]{index=5}

Classes

ERSHAPExplainer(model, background[, ...])

ER-SHAP: Ensemble of Random SHAP Explainer
class shap_enhanced.explainers.ERSHAP.ERSHAPExplainer(model, background, n_coalitions=100, mask_strategy='mean', weighting='uniform', feature_importance=None, device=None)[source]

Bases: BaseExplainer

ER-SHAP: Ensemble of Random SHAP Explainer

An efficient approximation of Shapley values using random coalition sampling over time-feature positions. Supports uniform and weighted sampling strategies and flexible masking (zero or mean) to generate perturbed inputs.

Parameters:

  • model (Any) – Model to explain, compatible with PyTorch tensors.

  • background (np.ndarray or torch.Tensor) – Background dataset for mean imputation; shape (N, T, F).

  • n_coalitions (int) – Number of coalitions to sample per (t, f) position.

  • mask_strategy (str) – Masking method: ‘zero’ or ‘mean’.

  • weighting (str) – Sampling scheme: ‘uniform’, ‘frequency’, or ‘importance’.

  • feature_importance (Optional[np.ndarray]) – Prior feature importances for weighted sampling; shape (T, F).

  • device (str) – Device identifier, ‘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, check_additivity=True, random_seed=42, **kwargs)[source]

Compute SHAP values via random coalition sampling.

For each position (t, f), sample coalitions of other positions, compute marginal contributions, and average over samples. Attributions are normalized to satisfy:

\[\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 or tensor of shape (T, F) or (B, T, F).

  • check_additivity (bool) – Whether to apply normalization for additivity.

  • random_seed (int) – Seed for reproducibility.

Returns:

SHAP values of shape (T, F) or (B, T, F).

Return type:

np.ndarray