shap_enhanced.explainers.hSHAP

h-SHAP: Hierarchical SHAP Explainer

Theoretical Explanation

Hierarchical SHAP (h-SHAP) is an extension of the SHAP framework that enables structured, group-wise attribution of features in models operating over high-dimensional or structured input data, such as time series or grouped tabular features.

Instead of treating each feature independently, h-SHAP introduces a hierarchy of feature groups, allowing recursive estimation of SHAP values at multiple levels—first over coarse groups, then over finer subgroups or individual features. This promotes interpretability and computational efficiency in contexts where feature dimensions have natural structure.

Key Concepts

  • Hierarchical Grouping:

    Features are grouped into blocks (e.g., temporal windows, spatial zones, feature families), possibly in multiple nested levels. These groups define the hierarchy over which SHAP values are computed.

  • Recursive SHAP Estimation:

    SHAP values are estimated first at the group level, and then recursively subdivided among subgroups or features within each group. This preserves hierarchical structure in the resulting attribution map.

  • Flexible Masking:
    Features can be masked by:

    • Setting them to zero (hard masking).

    • Imputing with background mean values (soft masking), using a provided reference dataset.

  • Additivity Normalization:

    Final attributions are normalized such that their total sum equals the model output difference between the original and fully-masked inputs.

Algorithm

  1. Initialization:
    • Accepts a model, background dataset for imputation, a user-defined hierarchy of feature groups,

      masking strategy (‘zero’ or ‘mean’), and a device context.

  2. Recursive Attribution:
    • For each group in the hierarchy:

      • Sample coalitions of other groups.

      • Estimate the group’s marginal contribution by masking:

        • Only the coalition, and

        • The coalition plus the current group.

      • Compute the model output difference to get SHAP value.

      • If the group contains subgroups, repeat recursively.

      • If not, distribute the SHAP value equally among group members or subfeatures.

  3. Normalization:
    • Rescale all SHAP values so that their sum matches the change in model output

      between the unmasked input and the fully-masked input.

References

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

  • Teneggi, Luster & Sulam (2022), *Fast Hierarchical Games for Image Explanations (h‑Shap)* [Exact hierarchical Shapley values for groups of pixels, with exponential computational improvements] :contentReference[oaicite:1]{index=1}

  • Jullum, Redelmeier & Løland (2021), *groupShapley: Efficient prediction explanation with Shapley values for feature groups* [Introduces grouping features and computing Shapley values at group level for efficiency and interpretability] :contentReference[oaicite:2]{index=2}

  • **Wang et al. (2025), Group Shapley with Robust Significance Testing ** [Extends Shapley framework to hierarchical groups and provides statistical tests for group contributions] :contentReference[oaicite:3]{index=3}

  • SHAP PartitionExplainer documentation [Implements recursive hierarchical coalitions and Owen‑value attribution via user‑defined feature hierarchies] :contentReference[oaicite:4]{index=4}

  • Molnar, *Interpretable Machine Learning* (2022), SHAP chapter [Discusses hierarchical coalitions, Owen and Shapley values, and structured feature grouping strategies] :contentReference[oaicite:5]{index=5}

Functions

generate_hierarchical_groups(T, F[, ...])

Generate a hierarchical grouping of features in a (T, F)-shaped input space.

Classes

HShapExplainer(model, background, hierarchy)

HShapExplainer: Hierarchical SHAP Explainer
class shap_enhanced.explainers.hSHAP.HShapExplainer(model, background, hierarchy, mask_strategy='mean', device=None)[source]

Bases: BaseExplainer

HShapExplainer: Hierarchical SHAP Explainer

Implements the h-SHAP algorithm, which recursively computes SHAP values over structured groups of features using hierarchical masking. Suitable for time-series or block-structured feature inputs where interpretability benefits from grouped attributions.

Note

Features can be masked using hard zero-masking or soft imputation via background means.

Parameters:

  • model – Model to explain.

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

  • hierarchy (list) – Nested list of feature index groups (e.g., [[(t1, f1), (t2, f2)], …]).

  • mask_strategy (str) – Either “mean” for imputation or “zero” for hard masking.

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

Compute hierarchical SHAP values for a batch of inputs.

The method recursively attributes model output to hierarchical feature groups. It also ensures additivity via normalization of final attributions.

\[\sum_{i=1}^{TF} \phi_i = f(x) - f(x_{\text{masked}})\]
Parameters:

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

  • nsamples (int) – Number of Monte Carlo samples per group.

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

  • random_seed (int) – Seed for reproducible sampling.

Returns:

SHAP values, same shape as X.

Return type:

np.ndarray

shap_enhanced.explainers.hSHAP.generate_hierarchical_groups(T, F, time_block=None, feature_block=None, nested=False)[source]

Generate a hierarchical grouping of features in a (T, F)-shaped input space.

This utility is useful for constructing hierarchical feature groupings for use with hierarchical SHAP (h-SHAP). Depending on the specified block sizes, it partitions time steps, features, or both into groups. If nested=True, the function returns subgroups within each block.

Note

The output format supports both flat and nested group structures, which are compatible with recursive SHAP attribution.

Parameters:

  • T (int) – Number of time steps (first input dimension).

  • F (int) – Number of features (second input dimension).

  • time_block (int or None) – Size of time blocks (e.g., 2 for groups of 2 time steps). If None, no time blocking.

  • feature_block (int or None) – Size of feature blocks. If None, no feature blocking.

  • nested (bool) – Whether to return nested groups (group → list of singleton subgroups).

Returns:

A list of grouped (t, f) indices, either flat or nested depending on nested.

Return type:

list[list[tuple[int, int]]] or list[list[list[tuple[int, int]]]]