graph-explain 0.7.0__py3-none-any.whl

graph_explain/core/explainer.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from typing import Any
+
+import torch
+
+from ..backends.base import Backend, get_backend
+from ..methods.base import ExplanationAlgorithm
+from .explanation import Explanation
+
+
+class Explainer:
+    def __init__(
+        self,
+        algorithm: ExplanationAlgorithm,
+        backend: Backend | str = "pyg",
+        node_mask_type: str | None = "attributes",
+        edge_mask_type: str | None = "object",
+        mask_threshold: float = 0.5,
+        explanation_type: str = "model",
+        **kwargs,
+    ):
+        if isinstance(backend, str):
+            backend = get_backend(backend)
+        self.backend = backend
+        self.algorithm = algorithm
+        self.node_mask_type = node_mask_type
+        self.edge_mask_type = edge_mask_type
+        self.mask_threshold = mask_threshold
+        self.explanation_type = explanation_type
+        self._extra = kwargs
+
+    def explain(
+        self,
+        data: Any,
+        model: Any,
+        index: int | list[int] | torch.Tensor | None = None,
+        target_class: int | None = None,
+        **kwargs,
+    ) -> Explanation:
+        explanation = self.algorithm.explain(
+            backend=self.backend,
+            model=model,
+            data=data,
+            index=index,
+            target_class=target_class,
+            node_mask_type=self.node_mask_type,
+            edge_mask_type=self.edge_mask_type,
+            **kwargs,
+        )
+        explanation.node_idx = index
+        explanation.mask_threshold = self.mask_threshold
+        explanation.metadata.setdefault("backend", self.backend)
+        explanation.metadata.setdefault("backing_data", data)
+        return explanation
+
+    def explain_node(
+        self,
+        data: Any,
+        model: Any,
+        node_idx: int,
+        target_class: int | None = None,
+        **kwargs,
+    ) -> Explanation:
+        return self.explain(
+            data, model, index=node_idx, target_class=target_class, **kwargs
+        )
+
+    def explain_graph(
+        self,
+        data: Any,
+        model: Any,
+        target_class: int | None = None,
+        **kwargs,
+    ) -> Explanation:
+        return self.explain(
+            data, model, index=None, target_class=target_class, **kwargs
+        )
+
+    def __call__(
+        self, data: Any, model: Any, index: int | list[int] | None = None, **kwargs
+    ):
+        return self.explain(data, model, index=index, **kwargs)

graph_explain/core/explanation.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import networkx as nx
+
+from ..core.evaluation import evaluate_fidelity, evaluate_sparsity
+
+
+@dataclass
+class Explanation:
+    node_importance: Any | None = None
+    edge_importance: Any | None = None
+    feature_importance: Any | None = None
+    subgraph: Any | None = None
+    prediction_original: Any | None = None
+    prediction_explanation: Any | None = None
+    node_idx: int | None = None
+    target_class: int | None = None
+    mask_threshold: float = 0.5
+    metadata: dict = field(default_factory=dict)
+
+    def evaluate(self, metrics: list[str] | None = None, **kwargs) -> dict:
+        metrics = metrics or ["fidelity", "sparsity"]
+        results: dict = {}
+        for name in metrics:
+            name = name.lower()
+            if name == "fidelity":
+                results[name] = evaluate_fidelity(self)
+            elif name in ("sparsity", "sparsity_ratio"):
+                results[name] = evaluate_sparsity(self, **kwargs)
+            else:
+                raise ValueError(f"Métrica desconocida: {name}")
+        return results
+
+    def to_networkx(self, threshold: float | None = None) -> nx.Graph:
+        threshold = threshold if threshold is not None else self.mask_threshold
+        backend = self.metadata.get("backend")
+        data = self.metadata.get("backing_data")
+        if backend is None or data is None:
+            raise ValueError(
+                "La explicación se creó sin backend/backing_data en metadata"
+            )
+        G = nx.Graph()
+        keep_edges = []
+        if self.edge_importance is not None:
+            edge_index = backend.edge_index(data)
+            for e in range(self.edge_importance.shape[0]):
+                if float(self.edge_importance[e]) >= threshold:
+                    u = int(edge_index[0, e])
+                    v = int(edge_index[1, e])
+                    keep_edges.append((u, v, float(self.edge_importance[e])))
+        if keep_edges:
+            G.add_weighted_edges_from(keep_edges)
+        nodes = {n for e in keep_edges for n in e[:2]}
+        if self.node_importance is not None:
+            for n in range(self.node_importance.shape[0]):
+                if float(self.node_importance[n]) >= threshold:
+                    nodes.add(n)
+        G.add_nodes_from(nodes)
+        return G
+
+    def __repr__(self) -> str:
+        parts = []
+        if self.node_importance is not None:
+            parts.append(f"node_importance={tuple(self.node_importance.shape)}")
+        if self.edge_importance is not None:
+            parts.append(f"edge_importance={tuple(self.edge_importance.shape)}")
+        if self.feature_importance is not None:
+            parts.append(f"feature_importance={tuple(self.feature_importance.shape)}")
+        return f"Explanation({', '.join(parts)})"

graph_explain/core/model_utils.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any
+
+import torch
+
+
+def capture_node_embeddings(
+    model: Any,
+    backend: Any,
+    data: Any,
+    layer_index: int = -2,
+) -> torch.Tensor:
+    children = list(model.children())
+    modules = list(model.modules())
+    if not children:
+        raise ValueError("El modelo no tiene submódulos para capturar embeddings")
+    target = children[layer_index] if layer_index < 0 else modules[layer_index]
+    captured: dict[str, torch.Tensor] = {}
+
+    def hook(_module, _input, output):
+        if isinstance(output, tuple):
+            output = output[0]
+        captured["emb"] = output.detach()
+
+    handle = target.register_forward_hook(hook)
+    try:
+        x = backend.node_features(data)
+        edge_index = backend.edge_index(data)
+        edge_weight = backend.edge_weight(data)
+        backend.forward(model, x, edge_index, edge_weight=edge_weight)
+    finally:
+        handle.remove()
+    emb = captured.get("emb")
+    if emb is None:
+        raise RuntimeError("No se capturaron embeddings del modelo")
+    return emb
+
+
+def edge_embeddings(
+    embeddings: torch.Tensor,
+    edge_index: torch.Tensor,
+) -> torch.Tensor:
+    return torch.cat([embeddings[edge_index[0]], embeddings[edge_index[1]]], dim=-1)

graph_explain/core/registry.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+_ALGORITHMS: dict[str, type] = {}
+_ALIASES: dict[str, str] = {}
+
+
+def _accepted_params(cls: type) -> set[str]:
+    try:
+        sig = inspect.signature(cls.__init__)
+    except (TypeError, ValueError):
+        return set()
+    names = set()
+    for name, p in sig.parameters.items():
+        if name in ("self", "kwargs", "args"):
+            continue
+        if p.kind in (p.POSITIONAL_OR_KEYWORD, p.KEYWORD_ONLY):
+            names.add(name)
+    return names
+
+
+def register(name: str, *aliases: str) -> Callable[[type], type]:
+    def decorator(cls: type) -> type:
+        _ALGORITHMS[name] = cls
+        for alias in aliases:
+            _ALIASES[alias] = name
+        cls.name = name
+        return cls
+
+    return decorator
+
+
+def get_algorithm(name: str) -> type:
+    registered = _ALGORITHMS.get(name) or _ALGORITHMS.get(_ALIASES.get(name, ""))
+    if registered is None:
+        from ..methods import _available_methods
+
+        raise ValueError(
+            f"Algoritmo desconocido: {name}. Disponibles: {sorted(_available_methods())}"
+        )
+    return registered
+
+
+def instantiate(name: str, **kwargs) -> Any:
+    cls = get_algorithm(name)
+    accepted = _accepted_params(cls)
+    filtered = {k: v for k, v in kwargs.items() if k in accepted}
+    return cls(**filtered)
+
+
+def _available_methods() -> set[str]:
+    return set(_ALGORITHMS.keys()) | set(_ALIASES.keys())

graph_explain/methods/__init__.py

@@ -0,0 +1,39 @@
+from .attention.attention import AttentionExplainer
+from .base import ExplanationAlgorithm
+from .baseline.random_baseline import RandomBaseline
+from .counterfactual.counterfactual import Counterfactual
+from .feature.graph_lime import GraphLIME
+from .gradient.grad_x_input import GradXInput
+from .gradient.guided_backprop import GuidedBackprop
+from .gradient.integrated_gradients import IntegratedGradients
+from .gradient.saliency import Saliency
+from .perturbation.gnn_explainer import GNNExplainer
+from .perturbation.node_mask import NodeMask
+from .perturbation.pg_explainer import PGExplainer
+from .perturbation.subgraphx import SubgraphX
+from .relevance.deeplift import DeepLift
+from .relevance.gnn_lrp import GNNGatedLRP
+
+__all__ = [
+    "AttentionExplainer",
+    "Counterfactual",
+    "DeepLift",
+    "ExplanationAlgorithm",
+    "GNNExplainer",
+    "GNNGatedLRP",
+    "GradXInput",
+    "GraphLIME",
+    "GuidedBackprop",
+    "IntegratedGradients",
+    "NodeMask",
+    "PGExplainer",
+    "RandomBaseline",
+    "Saliency",
+    "SubgraphX",
+]
+
+
+def _available_methods():
+    from ..core.registry import _available_methods
+
+    return _available_methods()

graph_explain/methods/attention/attention.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from typing import Any
+
+import torch
+
+from ...core.explanation import Explanation
+from ...core.registry import register
+from ..base import ExplanationAlgorithm
+
+
+def _is_gat(module) -> bool:
+    try:
+        from torch_geometric.nn import GATConv
+
+        return isinstance(module, GATConv)
+    except ImportError:
+        return False
+
+
+@register("attention", "gat", "attention_explainer")
+class AttentionExplainer(ExplanationAlgorithm):
+    """Explanation based on the attention weights of GAT models.
+
+    Captures the attention coefficients (pre-softmax) of each `GATConv` during a
+    single forward pass and normalizes them with a per-neighbor softmax. Edge
+    importance is the mean of the coefficients across attention heads and GAT
+    layers; node importance aggregates the attention of the incident edges.
+    """
+
+    def __init__(
+        self,
+        head_aggregate: str = "mean",
+        layer_aggregate: str = "mean",
+        node_aggregate: str = "sum",
+    ):
+        self.head_aggregate = head_aggregate
+        self.layer_aggregate = layer_aggregate
+        self.node_aggregate = node_aggregate
+
+    def explain(
+        self,
+        backend: Any,
+        model: Any,
+        data: Any,
+        index: int | list[int] | torch.Tensor | None = None,
+        target_class: int | None = None,
+        **kwargs,
+    ) -> Explanation:
+        model.eval()
+        x = backend.node_features(data)
+        edge_index = backend.edge_index(data)
+        num_nodes = int(x.size(0))
+        convs = [m for m in model.modules() if _is_gat(m)]
+        if not convs:
+            raise ValueError(
+                "AttentionExplainer requiere un modelo con capas GATConv "
+                "(torch_geometric.nn.GATConv)."
+            )
+
+        nodes = self._to_node_ids(index, num_nodes)
+        captured = self._capture_attention(model, backend, x, edge_index)
+        logits = captured["logits"]
+        # GATConv normaliza sobre las aristas + self-loops (añadidos al final)
+        alphas = [a[: edge_index.size(1)] for a in captured["alphas"]]
+
+        if logits.dim() != 2:
+            raise ValueError(
+                "AttentionExplainer requiere predicciones node-level (logits (N, C))."
+            )
+        target = target_class
+        if target is None:
+            target = int(logits[nodes[0]].argmax().item())
+        target_cls = max(0, min(int(target), logits.size(1) - 1))
+
+        per_layer: list[torch.Tensor] = []
+        for layer_idx, alpha in enumerate(alphas):
+            att = torch.softmax(alpha, dim=0)  # (E, heads) normalizada por vecino
+            if self.head_aggregate == "mean":
+                att = att.mean(dim=1)
+            elif self.head_aggregate == "max":
+                att = att.max(dim=1).values
+            elif self.head_aggregate == "sum":
+                att = att.sum(dim=1)
+            else:
+                raise ValueError(f"head_aggregate desconocido: {self.head_aggregate}")
+            weight = 1.0 / len(convs) if self.layer_aggregate == "mean" else 1.0
+            per_layer.append(weight * att)
+
+        edge_importance = torch.stack(per_layer).sum(dim=0).clamp(min=0.0)
+
+        node_importance = torch.zeros(num_nodes, device=x.device)
+        if self.node_aggregate == "sum":
+            node_importance = node_importance.index_add(
+                0, edge_index[0], edge_importance
+            )
+            node_importance = node_importance.index_add(
+                0, edge_index[1], edge_importance
+            )
+        elif self.node_aggregate == "in":
+            node_importance = node_importance.index_add(
+                0, edge_index[1], edge_importance
+            )
+        elif self.node_aggregate == "out":
+            node_importance = node_importance.index_add(
+                0, edge_index[0], edge_importance
+            )
+        else:
+            raise ValueError(f"node_aggregate desconocido: {self.node_aggregate}")
+
+        return Explanation(
+            node_importance=node_importance.detach().cpu(),
+            edge_importance=edge_importance.detach().cpu(),
+            feature_importance=None,
+            prediction_original=logits[nodes[0]].detach().cpu(),
+            prediction_explanation=None,
+            node_idx=int(nodes[0]) if nodes.shape[0] == 1 else index,
+            target_class=target_cls,
+        )
+
+    @staticmethod
+    def _to_node_ids(index, num_nodes: int) -> torch.Tensor:
+        if index is None:
+            return torch.zeros(1, dtype=torch.long)
+        if isinstance(index, int):
+            return torch.tensor([index], dtype=torch.long)
+        idx = torch.as_tensor(index, dtype=torch.long)
+        return idx.reshape(-1) if idx.numel() else torch.zeros(1, dtype=torch.long)
+
+    def _capture_attention(self, model, backend, x, edge_index):
+        from torch_geometric import nn as pyg_nn
+
+        captured: list[torch.Tensor] = []
+        real = pyg_nn.conv.gat_conv.softmax
+
+        def _wrapped(alpha, index, ptr=None, num_nodes=None):
+            captured.append(alpha.detach())
+            return real(alpha, index, ptr, num_nodes)
+
+        pyg_nn.conv.gat_conv.softmax = _wrapped
+        try:
+            with torch.no_grad():
+                logits = backend.forward(model, x, edge_index)
+        finally:
+            pyg_nn.conv.gat_conv.softmax = real
+        # un solo softmax por capa GAT en el forward
+        return {"logits": logits, "alphas": captured}

graph_explain/methods/base.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+import torch
+
+
+class ExplanationAlgorithm(ABC):
+    name = "base"
+    graph_level = False
+
+    @abstractmethod
+    def explain(
+        self,
+        backend: Any,
+        model: Any,
+        data: Any,
+        index: int | list[int] | torch.Tensor,
+        target_class: int | None = None,
+        **kwargs,
+    ) -> Any: ...
+
+    def validate(self, backend: Any, model: Any, data: Any) -> None:
+        return None

graph_explain/methods/baseline/random_baseline.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+
+import torch
+
+from ...core.explanation import Explanation
+from ...core.registry import register
+from ..base import ExplanationAlgorithm
+
+
+@register("random", "random_baseline", "rand")
+class RandomBaseline(ExplanationAlgorithm):
+    """Random: seed-able uniform random importance baseline.
+
+    Assigns random importances in [0, 1] to nodes, edges and features with no
+    link to the model; useful as a null-scenario reference in comparative
+    benchmarks.
+    """
+
+    graph_level = True
+
+    def __init__(self, seed: int | None = 0, **kwargs):
+        self.seed = seed
+
+    def explain(
+        self,
+        backend: Any,
+        model: Any,
+        data: Any,
+        index: int | torch.Tensor | None = None,
+        target_class: int | None = None,
+        **kwargs,
+    ) -> Explanation:
+        x = backend.node_features(data)
+        edge_index = backend.edge_index(data)
+        num_nodes = int(x.size(0))
+        num_edges = int(edge_index.size(1))
+
+        if self.seed is not None:
+            torch.manual_seed(self.seed)
+
+        node_importance = torch.rand(num_nodes).cpu()
+        edge_importance = torch.rand(num_edges).cpu()
+        feature_importance = torch.rand_like(x).cpu()
+
+        nodes = self._to_node_ids(index, num_nodes)
+        root = int(nodes[0])
+        with torch.no_grad():
+            logits = backend.forward(model, x, edge_index)
+        target = target_class
+        if logits.dim() == 2:
+            if target is None:
+                target = int(logits[root].argmax().item())
+            target = max(0, min(int(target), logits.size(1) - 1))
+            pred = logits[root].detach().cpu()
+        else:
+            target = None
+            pred = logits.detach().cpu()
+
+        return Explanation(
+            node_importance=node_importance,
+            edge_importance=edge_importance,
+            feature_importance=feature_importance,
+            prediction_original=pred,
+            prediction_explanation=None,
+            node_idx=root,
+            target_class=target,
+        )
+
+    @staticmethod
+    def _to_node_ids(index, num_nodes: int) -> torch.Tensor:
+        if index is None:
+            return torch.zeros(1, dtype=torch.long)
+        if isinstance(index, int):
+            return torch.tensor([index], dtype=torch.long)
+        idx = torch.as_tensor(index, dtype=torch.long)
+        return idx.reshape(-1) if idx.numel() else torch.zeros(1, dtype=torch.long)