shap_enhanced.explainers.BSHAP

BShapExplainer: Distribution-Free SHAP for Sequential Models

Theoretical Explanation

BShap is a distribution-free variant of the SHAP framework, specifically designed for sequential models such as LSTMs. Unlike classical SHAP methods that rely on empirical data (e.g., using mean or sample values as feature baselines), BShap masks features using uninformative replacements such as uniform noise, Gaussian noise, or zeros. This makes it particularly suitable when the underlying data distribution is unknown, unreliable, or intentionally ignored.

By avoiding assumptions about the data, BShap enables a cleaner interpretation of how a model behaves under entirely synthetic perturbations—revealing how features contribute even when removed from their contextual correlations.

Key Concepts

  • Distribution-Free Masking: Masked features are replaced with independently sampled values that do not rely on the input data distribution.

  • Masking Strategies: - ‘random’: Sample feature values uniformly at random from a defined range (default). - ‘noise’: Add Gaussian noise to masked feature values. - ‘zero’: Set masked features to zero.

  • No Data Assumptions: All masking is performed without drawing from empirical feature distributions.

  • Additivity Normalization: Feature attributions are normalized so that their sum equals the change in model output between the original and fully-masked input.

Algorithm

  1. Initialization: - Accepts a model, a value range for feature sampling, the number of samples, masking strategy (‘random’, ‘noise’, ‘zero’), and device context.

  2. Masking:
    • For each coalition (a subset of features to mask), masked values are replaced by:

      • Random values (uniform), or

      • Gaussian noise, or

      • Zeros, depending on the selected strategy.

  3. SHAP Value Estimation:
    • For each feature:

      • Randomly select a subset of other features to mask.

      • Compute model output for:

        • The input with the coalition masked.

        • The input with the coalition plus the current feature masked.

      • Record and average the difference in outputs as the estimated contribution.

  4. Normalization:

    • Scale the attributions so that their sum equals the difference between the original and fully-masked model outputs.

References

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

  • Molnar, “Interpretable Machine Learning” (2022), SHAP chapter [Discusses various SHAP variants, including noise or zero baselines vs. data-driven baselines]

  • Chen, Lundberg & Lee (2022), “Explaining a Series of Models by Propagating Shapley Values” (Generalized DeepSHAP) [Highlights how interpretation depends on baseline distributions and how multiple or synthetic baselines influence attribution] :contentReference[oaicite:2]{index=2}

Classes

BShapExplainer(model[, input_range, ...])

BShap: Distribution-Free SHAP Explainer for Sequential Models
class shap_enhanced.explainers.BSHAP.BShapExplainer(model, input_range=None, n_samples=50, mask_strategy='random', device=None)[source]

Bases: BaseExplainer

BShap: Distribution-Free SHAP Explainer for Sequential Models

Implements a SHAP-based attribution method that avoids empirical data distribution assumptions by applying synthetic masking strategies (e.g., uniform noise, Gaussian noise, or zero). This is useful for evaluating model robustness or interpretability in data-agnostic contexts.

Parameters:

  • model – Sequence model to explain.

  • input_range (tuple or (np.ndarray, np.ndarray)) – Tuple of (min, max) or arrays defining per-feature value bounds. Used for random masking.

  • n_samples (int) – Number of coalitions sampled per feature.

  • mask_strategy (str) – Masking strategy: ‘random’, ‘noise’, or ‘zero’.

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

Compute SHAP values using distribution-free perturbations.

Estimates marginal feature contributions by averaging differences between model outputs under masked coalitions. Uses synthetic masking based on the configured strategy without any reliance on background data statistics.

Final attributions are normalized to satisfy the SHAP additivity constraint:

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

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

  • nsamples (int) – Number of coalition samples per feature (defaults to self.n_samples).

  • check_additivity (bool) – Print diagnostic message for SHAP sum vs. model delta.

  • random_seed (int) – Seed for reproducibility.

Returns:

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

Return type:

np.ndarray