gsnn.interpret.IGExplainer

class gsnn.interpret.IGExplainer(model, data, ignore_cuda=False, n_steps=50, baseline=None)[source]

Bases: object

Integrated-Gradients explainer for GSNN models (non-contrastive).

Computes per-edge or per-node attributions for a prediction f(x)[target_idx] by integrating the gradient along a straight-line path in feature space from a baseline input x′ (default all zeros) to the observation x.

For edge-level attributions:

IG_e = (x - x′) · \int_0^1 ∂f(x′ + α(x-x′))/∂m_e dα.

For node-level attributions:

IG_n = (x - x′) · \int_0^1 ∂f(x′ + α(x-x′))/∂n_n dα.

When the baseline masks are zero this reduces to the EdgeIG/NodeIG variants. The attributions satisfy the completeness axiom for their respective domains.

Node-level and edge-level attributions are computed independently using separate masking mechanisms in the GSNN model.

Parameters:

  • model (torch.nn.Module) – Trained GSNN model (copied and frozen internally).

  • data (torch_geometric.data.Data) – Graph data object; only used for edge names.

  • ignore_cuda (bool, optional (default=False)) – Force the explainer to run on CPU even if CUDA is available.

  • n_steps (int, optional (default=50)) – Number of points on the IG path (baseline included).

  • baseline (torch.Tensor or None, optional) – Custom baseline edge-mask of shape (1,E). None defaults to an all-zeros mask.

Example

>>> explainer = IGExplainer(model, data, n_steps=64)
>>> # Edge-level attributions
>>> df_edge = explainer.explain(x, target_idx=0, target='edge')
>>> df_edge.nlargest(5, 'score')
>>> # Node-level attributions
>>> df_node = explainer.explain(x, target_idx=0, target='node')
>>> df_node.nlargest(5, 'score')

>>> # Compute IG for only a subset of edges
>>> edge_mask = np.array([True, False, True, False, True])  # Only integrate edges 0, 2, 4
>>> df_edge = explainer.explain(x, target_idx=0, target='edge', element_mask=edge_mask)
>>> # Edges 1 and 3 will have None scores; edges 0, 2, 4 have IG attributions
>>> # Note: Completeness axiom won't hold when using element_mask
__init__(model, data, ignore_cuda=False, n_steps=50, baseline=None)[source]

Create a new IGExplainer instance.

Methods

__init__(model, data[, ignore_cuda, ...])

Create a new IGExplainer instance.

explain(x, target_idx, *[, jitter, ...])

Compute integrated gradients attributions for GSNN predictions.
explain(x, target_idx, *, jitter: Optional[torch.Tensor] = None, element_mask=None, target='edge', reduction='mean', model_kwargs=None)[source]

Compute integrated gradients attributions for GSNN predictions.

Parameters:

  • x (torch.Tensor) – Input features of shape (N_in,), (1, N_in), or (B, N_in) for batch.

  • target_idx (int) – Index of the target output node to explain.

  • jitter (torch.Tensor, optional) – Optional noise to add to baseline, shape (E,) or (1, E) for edge target, shape (N,) or (1, N) for node target.

  • element_mask (torch.Tensor or np.ndarray, optional (shape: [E] or [N])) –

    Boolean mask indicating which elements to compute IG attributions for. If None, all elements are integrated. If provided: - True/nonzero elements: integrate from baseline to 1 (normal IG) - False/zero elements: fixed at 1 throughout the path (no integration) Elements not in the mask will have None scores in the output.

    Note: When using element_mask, the completeness axiom (attributions sum to f(x) - f(baseline)) will not hold since only a subset of elements are integrated. The attributions measure “contribution while holding other elements fixed at full strength”.

  • target (str, optional (default='edge')) – Whether to return ‘edge’ or ‘node’ level attributions.

  • reduction (str, optional (default='mean')) – How to aggregate attributions across batch samples: - ‘mean’: average attributions across samples (default) - ‘sum’: sum attributions across samples - ‘none’: return all per-sample attributions (adds ‘sample_idx’ column)

  • model_kwargs (dict, optional (default=None)) – Extra keyword arguments forwarded to every self.model(...) call (e.g. {'x_fn': x_fn} for models trained with node_activity=True). Tensor values must have leading dim equal to x.shape[0] (or 1 to broadcast); they will be sliced per sample and replicated to n_steps+1 along the IG path. edge_mask / node_mask are reserved and should not be included.

Returns:

  • pd.DataFrame – If target=’edge’: columns [‘source’, ‘target’, ‘score’] for edge attributions. If target=’node’: columns [‘node’, ‘score’] for node attributions. If reduction=’none’: additional ‘sample_idx’ column for batch dimension. Elements not in element_mask will have None scores.

  • Following approach and style from (https://github.com/ankurtaly/Integrated-Gradients/blob/master/IntegratedGradients/integrated_gradients.py)

  • Reference

  • @article{DBLP (journals/corr/SundararajanTY17,) –

    author = {Mukund Sundararajan and

    Ankur Taly and Qiqi Yan},

    title = {Axiomatic Attribution for Deep Networks}, journal = {CoRR}, volume = {abs/1703.01365}, year = {2017}, url = {http://arxiv.org/abs/1703.01365}, eprinttype = {arXiv}, eprint = {1703.01365}, timestamp = {Mon, 13 Aug 2018 16:48:32 +0200}, biburl = {https://dblp.org/rec/journals/corr/SundararajanTY17.bib}, bibsource = {dblp computer science bibliography, https://dblp.org} }