gsnn.gsnn.interpret.NoiseTunnel

class gsnn.gsnn.interpret.NoiseTunnel(explainer, n_samples: int = 20, noise_std: float = 0.05, agg: str = 'mean')[source]

Bases: object

Edge-level NoiseTunnel wrapper for IGExplainer and ContrastiveIGExplainer.

This module runs the wrapped explainer multiple times while injecting Gaussian noise in the edge-mask space and finally aggregates the obtained attributions. The procedure is inspired by SmoothGrad / NoiseTunnel (Smilkov et al. 2017) but adapted to GSNNs where the inputs are the edge weights rather than node features.

Parameters:

  • explainer (IGExplainer or ContrastiveIGExplainer) – A configured explainer instance whose explain method will be executed repeatedly. The explainer must expose the underlying GSNN model via the attribute model.

  • n_samples (int, optional (default=20)) – Number of noisy repetitions.

  • noise_std (float, optional (default=0.05)) – Standard deviation of the Gaussian noise added to the edge weights.

  • agg ({'mean', 'median'}, optional (default='mean')) – Aggregation statistic used to combine the per-sample attributions.

Notes

  1. For IGExplainer we add noise to its baseline edge-mask (explainer.baseline). This is equivalent to sampling different straight-line paths m(α) = α·(1 + ε) where ε ~ 𝓝(0, σ²).

  2. ContrastiveIGExplainer does not expose a baseline. Therefore we perturb the terminal mask m=1 only, which yields a noisy path m(α)=α·(1+ε). The implementation copies the internal logic of the contrastive explainer because the original method does not accept external masks.

  3. The injected noise is clipped to the valid range [0, 1].

Example

>>> ig = ContrastiveIGExplainer(model, data, n_steps=64)
>>> nt = NoiseTunnel(ig, n_samples=30, noise_std=0.1)
>>> df = nt.explain(x1, x2, target_idx=0)
>>> df.sort_values('score', ascending=False).head()
__init__(explainer, n_samples: int = 20, noise_std: float = 0.05, agg: str = 'mean') → None[source]

Methods

__init__(explainer[, n_samples, noise_std, agg])

explain(*args, **kwargs)

Compute noise-tunnel edge attributions.
explain(*args, **kwargs) → pandas.DataFrame[source]

Compute noise-tunnel edge attributions.

The positional / keyword arguments are forwarded verbatim to the wrapped explainer’s explain method.