gsnn.gsnn.interpret.ContrastiveOcclusionExplainer

class gsnn.gsnn.interpret.ContrastiveOcclusionExplainer(model: torch.nn.Module, data, batch_size: int = 32, ignore_cuda: bool = False, verbose: bool = False)[source]

Bases: object

Simple batched edge occlusion explainer for contrastive questions.

This module attributes the prediction difference:

Δf = f(x1)[target_idx] - f(x2)[target_idx]

to every edge e by systematically removing each edge and measuring the change in the absolute prediction difference:

\[\mathrm{Occ}_e = |Δf_{\text{baseline}}| - |Δf_{\text{without } e}|\]

where the baseline uses all edges present and the occluded version removes edge e completely (edge_mask = 0).

  • Occ_e > 0 removing edge e decreases |Δf| (edge contributes to difference).

  • Occ_e < 0 removing edge e increases |Δf| (edge reduces difference).

  • Occ_e ≈ 0 edge e has no impact on the prediction difference.

Parameters:

  • model (torch.nn.Module) – Trained GSNN model (evaluation mode is enforced internally).

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

  • batch_size (int, optional (default=32)) – Number of edge occlusions to process in parallel.

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

  • verbose (bool, optional (default=False)) – Print progress information during explanation computation.

Example

>>> explainer = ContrastiveOcclusionExplainer(model, data, batch_size=64)
>>> df = explainer.explain(x1, x2, target_idx=0)
>>> df.sort_values('score', ascending=False).head()
source target   score
in0    func0    0.42
func0  func3    0.40
func3  out0     0.38
__init__(model: torch.nn.Module, data, batch_size: int = 32, ignore_cuda: bool = False, verbose: bool = False) → None[source]

Methods

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

explain(x1, x2, target_idx, *[, ...])

Compute occlusion attributions for f(x₁) − f(x₂).
explain(x1: torch.Tensor, x2: torch.Tensor, target_idx: Union[int, List[int]], *, element_mask=None, target: str = 'edge', reduction: str = 'mean', model_kwargs1=None, model_kwargs2=None) → pandas.DataFrame[source]

Compute occlusion attributions for f(x₁) − f(x₂).

Parameters:

  • x1 (torch.Tensor (shape: [N_in], [1, N_in], or [B, N_in] for batch)) – Two input feature tensors. They must have identical batch size and ordering of nodes. Each pair (x1[i], x2[i]) is explained.

  • x2 (torch.Tensor (shape: [N_in], [1, N_in], or [B, N_in] for batch)) – Two input feature tensors. They must have identical batch size and ordering of nodes. Each pair (x1[i], x2[i]) is explained.

  • target_idx (int or list[int]) – Output dimension(s) to explain. If a list is provided the attributions refer to the sum of those outputs.

  • element_mask (torch.Tensor or np.ndarray, optional (shape: [E] or [N])) – Boolean mask indicating which elements to compute occlusion for. If None, all elements are considered. If provided, only elements where element_mask[i] is True will have occlusion scores computed.

  • 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)

Returns:

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.

Return type:

pd.DataFrame