graph-explain 0.7.0__py3-none-any.whl

graph_explain/methods/relevance/deeplift.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+from typing import Any
+
+import torch
+from torch import nn
+
+from ...core.explanation import Explanation
+from ...core.registry import register
+from ..base import ExplanationAlgorithm
+
+_ACTIVATION_GATES = (
+    nn.ReLU,
+    nn.ReLU6,
+    nn.LeakyReLU,
+)
+
+
+@register("deep_lift", "deeplift", "dl")
+class DeepLift(ExplanationAlgorithm):
+    """DeepLIFT (rescale rule) for GCNs + ReLU + Linear.
+
+    It is an additive rule: each input feature receives a contribution (delta)
+    proportional to how much the target-class output changes when moving from a
+    baseline (zero, by default) to the actual instance. The multiplier is
+    propagated backwards layer by layer: exact for linear layers and GCN
+    messages, and with the rescale rule (delta_out / delta_in) for elementwise
+    nonlinearities.
+
+    Returns `node_importance` (absolute contribution per node), `edge_importance`
+    (contributions through the message passing of each GCNConv, per directed
+    edge) and `feature_importance` (contribution per feature).
+    """
+
+    def __init__(
+        self,
+        eps: float = 1e-7,
+        normalize: bool = False,
+        node_mask_type: str | None = "attributes",
+    ):
+        self.eps = float(eps)
+        self.normalize = bool(normalize)
+        self.node_mask_type = node_mask_type
+
+    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).detach()
+        edge_index = backend.edge_index(data)
+        edge_weight = backend.edge_weight(data)
+        num_nodes = int(x.size(0))
+
+        nodes = self._to_node_ids(index, num_nodes)
+
+        order, order0, logits, logits0 = self._capture(
+            model, backend, x, edge_index, edge_weight
+        )
+        if logits.dim() != 2:
+            raise ValueError(
+                "DeepLift 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))
+
+        mul = torch.zeros_like(logits)
+        mul[nodes, target_cls] = 1.0
+        edge_rel_full = torch.zeros(edge_index.size(1), device=x.device)
+        eps = self.eps
+
+        for m, m0 in reversed(list(zip(order, order0))):
+            in_x = m["args"][0]
+            in_x0 = m0["args"][0]
+            delta_in = in_x - in_x0
+            name = m["name"]
+            mod = m["module"]
+            if name == "linear":
+                mul = mul @ mod.weight
+            elif name == "gcn":
+                mul, edge_rel = self._conv_back(
+                    mod, in_x, in_x0, edge_index, edge_weight, mul
+                )
+                edge_rel_full = edge_rel_full + edge_rel[: edge_index.size(1)]
+            elif name == "activation":
+                delta_out = mod(in_x) - mod(in_x0)
+                mul = mul * self._rescale_ratio(delta_in, delta_out, eps)
+            else:
+                continue
+
+        delta_total = logits[nodes, target_cls].sum() - logits0[nodes, target_cls].sum()
+        contrib = mul * x
+        node_importance = contrib.abs().sum(dim=-1)
+        edge_importance = edge_rel_full.abs()
+        self._last_delta_total = float(delta_total.item())
+
+        if self.normalize:
+            total = float(node_importance.sum().item())
+            if total > 0:
+                node_importance = node_importance / total
+                total_e = float(edge_importance.sum().item())
+                if total_e > 0:
+                    edge_importance = edge_importance / total_e
+
+        return Explanation(
+            node_importance=node_importance.detach().cpu(),
+            edge_importance=edge_importance.detach().cpu(),
+            feature_importance=(
+                contrib.detach().cpu() if self.node_mask_type == "attributes" else 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,
+        )
+
+    # ------------------------------------------------------------------ utils
+    @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)
+
+    @staticmethod
+    def _is_linear(module: nn.Module) -> bool:
+        return isinstance(module, nn.Linear)
+
+    @staticmethod
+    def _is_activation(module: nn.Module) -> bool:
+        return isinstance(module, _ACTIVATION_GATES)
+
+    @staticmethod
+    def _is_gcn(module: nn.Module) -> bool:
+        try:
+            from torch_geometric.nn import GCNConv
+
+            return isinstance(module, GCNConv)
+        except ImportError:
+            return False
+
+    def _capture(self, model, backend, x, edge_index, edge_weight):
+        order: list[dict[str, Any]] = []
+        order0: list[dict[str, Any]] = []
+
+        def _pre(module, args):
+            order.append(
+                {
+                    "module": module,
+                    "name": self._kind(module),
+                    "args": tuple(
+                        a.detach() if torch.is_tensor(a) else a for a in args
+                    ),
+                }
+            )
+
+        def _pre0(module, args):
+            order0.append(
+                {
+                    "module": module,
+                    "name": self._kind(module),
+                    "args": tuple(
+                        a.detach() if torch.is_tensor(a) else a for a in args
+                    ),
+                }
+            )
+
+        handles = [
+            module.register_forward_pre_hook(_pre)
+            for module in model.modules()
+            if module is not model
+        ]
+        with torch.no_grad():
+            logits = backend.forward(model, x, edge_index, edge_weight=edge_weight)
+        for handle in handles:
+            handle.remove()
+
+        handles0 = [
+            module.register_forward_pre_hook(_pre0)
+            for module in model.modules()
+            if module is not model
+        ]
+        baseline = torch.zeros_like(x)
+        with torch.no_grad():
+            logits0 = backend.forward(
+                model, baseline, edge_index, edge_weight=edge_weight
+            )
+        for handle in handles0:
+            handle.remove()
+        return order, order0, logits, logits0
+
+    @staticmethod
+    def _kind(module: nn.Module) -> str:
+        if DeepLift._is_linear(module):
+            return "linear"
+        if DeepLift._is_gcn(module):
+            return "gcn"
+        if DeepLift._is_activation(module):
+            return "activation"
+        return "other"
+
+    def _conv_back(
+        self,
+        conv: nn.Module,
+        x: torch.Tensor,
+        x0: torch.Tensor,
+        edge_index: torch.Tensor,
+        edge_weight: torch.Tensor | None,
+        mul: torch.Tensor,
+    ):
+        from torch_geometric.nn.conv.gcn_conv import gcn_norm
+        from torch_geometric.utils import add_self_loops
+
+        num_nodes = int(x.size(0))
+        if getattr(conv, "normalize", True):
+            ei, norm = gcn_norm(
+                edge_index,
+                edge_weight=edge_weight,
+                num_nodes=num_nodes,
+                improved=getattr(conv, "improved", False),
+                add_self_loops=getattr(conv, "add_self_loops", True),
+                flow=getattr(conv, "flow", "source_to_target"),
+            )
+        else:
+            ei = (
+                add_self_loops(edge_index, num_nodes=num_nodes)[0]
+                if getattr(conv, "add_self_loops", True)
+                else edge_index
+            )
+            norm = (
+                edge_weight
+                if edge_weight is not None
+                else torch.ones(ei.size(1), device=x.device)
+            )
+        src, dst = ei[0], ei[1]
+        W = conv.lin.weight  # (out, in)
+
+        mul_agg = mul @ W  # (N, F_in)
+
+        delta_in = x - x0
+        edge_contrib = (mul_agg[dst] * (norm[:, None] * delta_in[src])).sum(dim=-1)
+
+        mul_src = torch.zeros(num_nodes, delta_in.size(1), device=x.device)
+        mul_src.index_add_(0, src, mul_agg[dst] * norm[:, None])
+        return mul_src, edge_contrib
+
+    @staticmethod
+    def _rescale_ratio(delta_in: torch.Tensor, delta_out: torch.Tensor, eps: float):
+        denom = delta_in.abs()
+        safe = denom > eps
+        ratio = torch.ones_like(delta_in)
+        ratio[safe] = delta_out[safe] / delta_in[safe]
+        return ratio

graph_explain/methods/relevance/gnn_lrp.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+from typing import Any
+
+import torch
+from torch import nn
+
+from ...core.explanation import Explanation
+from ...core.registry import register
+from ..base import ExplanationAlgorithm
+
+_ACTIVATION_GATES = (
+    nn.ReLU,
+    nn.ReLU6,
+    nn.LeakyReLU,
+)
+
+
+@register("gnn_lrp", "gnn-lrp", "lrp")
+class GNNGatedLRP(ExplanationAlgorithm):
+    """GNN-LRP (Layer-wise Relevance Propagation for GNNs).
+
+    Propagates the relevance from the target-class logit backwards, layer by
+    layer, redistributing it according to the positive contributions of each
+    neuron (LRP-0 / z+ rules). For each `GCNConv` the relevance is split into
+    two steps: (a) the linear transform `W` over the aggregated features and (b)
+    the convolution, attributing relevance to the neighboring nodes/edges in
+    proportion to their contribution to the message-passing step (GCN norm
+    included). Supports GCN architectures (`GCNConv` + `ReLU` + `Linear`).
+
+    The resulting relevance is non-negative (positive rules) and is returned as
+    `node_importance` (sum per node) and `edge_importance` (per directed edge,
+    aligned with the `edge_index` indices).
+    """
+
+    def __init__(
+        self,
+        eps: float = 1e-6,
+        normalize: bool = False,
+        node_mask_type: str | None = None,
+    ):
+        self.eps = float(eps)
+        self.normalize = bool(normalize)
+        self.node_mask_type = node_mask_type
+
+    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).detach().requires_grad_(False)
+        edge_index = backend.edge_index(data)
+        edge_weight = backend.edge_weight(data)
+        num_nodes = int(x.size(0))
+
+        nodes = self._to_node_ids(index, num_nodes)
+        order: list[tuple[nn.Module, tuple[Any, ...]]] = []
+
+        def _pre(module: nn.Module, args: tuple[Any, ...]):
+            order.append((module, args))
+
+        handles = [
+            module.register_forward_pre_hook(_pre)
+            for module in model.modules()
+            if module is not model
+        ]
+
+        out = backend.forward(model, x, edge_index, edge_weight=edge_weight)
+        for handle in handles:
+            handle.remove()
+
+        logits = out
+        if logits.dim() != 2:
+            raise ValueError(
+                "GNN-LRP 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))
+
+        seed = torch.zeros_like(logits)
+        seed[nodes, target_cls] = 1.0
+        relevance = seed  # (N, C)
+
+        edge_rel = torch.zeros(edge_index.size(1), device=x.device)
+        eps = self.eps
+
+        for module, args in reversed(order):
+            if isinstance(module, nn.Linear):
+                relevance = self._linear_lrp(module.weight, args[0], relevance, eps)
+            elif self._is_gcn(module):
+                rel_out, rel_edge = self._conv_lrp(
+                    module, args[0], edge_index, edge_weight, relevance, eps
+                )
+                relevance = rel_out
+                num_expanded = int(rel_edge.numel())
+                if num_expanded >= edge_index.size(1):
+                    edge_rel = edge_rel + rel_edge[: edge_index.size(1)]
+            elif self._is_activation(module):
+                gate = (args[0] > 0).to(relevance.dtype)
+                relevance = relevance * gate
+            else:
+                continue
+
+        node_importance = relevance.sum(dim=-1)
+        if self.normalize:
+            total = float(node_importance.sum().item())
+            if total > 0:
+                node_importance = node_importance / total
+                total_e = float(edge_rel.sum().item())
+                if total_e > 0:
+                    edge_rel = edge_rel / total_e
+
+        return Explanation(
+            node_importance=node_importance.detach().cpu(),
+            edge_importance=edge_rel.detach().cpu(),
+            feature_importance=(
+                relevance.detach().cpu()
+                if self.node_mask_type == "attributes"
+                else 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,
+        )
+
+    # ------------------------------------------------------------------ utils
+    @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)
+
+    @staticmethod
+    def _is_gcn(module: nn.Module) -> bool:
+        try:
+            from torch_geometric.nn import GCNConv
+
+            return isinstance(module, GCNConv)
+        except ImportError:
+            return False
+
+    @staticmethod
+    def _is_activation(module: nn.Module) -> bool:
+        return isinstance(module, _ACTIVATION_GATES)
+
+    @staticmethod
+    def _linear_lrp(
+        weight: torch.Tensor,
+        x: torch.Tensor,
+        r: torch.Tensor,
+        eps: float,
+    ) -> torch.Tensor:
+        """z+ rule (positive LRP-0) for a linear transform y = Wx."""
+        wp = weight.clamp(min=0)  # (out, in)
+        xp = x.clamp(min=0)  # (N, in)
+        contrib = xp[:, None, :] * wp[None, :, :]  # (N, out, in)
+        denom = contrib.sum(dim=-1).clamp(min=eps)  # (N, out)
+        return (contrib / denom[:, :, None] * r[:, :, None]).sum(dim=1)  # (N, in)
+
+    def _conv_lrp(
+        self,
+        conv: nn.Module,
+        x: torch.Tensor,
+        edge_index: torch.Tensor,
+        edge_weight: torch.Tensor | None,
+        r: torch.Tensor,
+        eps: float,
+    ):
+        """Relevance through a GCNConv: linear `W` + messages (GCN norm)."""
+        from torch_geometric.nn.conv.gcn_conv import gcn_norm
+
+        num_nodes = int(x.size(0))
+        if getattr(conv, "normalize", True):
+            ei, norm = gcn_norm(
+                edge_index,
+                edge_weight=edge_weight,
+                num_nodes=num_nodes,
+                improved=getattr(conv, "improved", False),
+                add_self_loops=getattr(conv, "add_self_loops", True),
+                flow=getattr(conv, "flow", "source_to_target"),
+            )
+        else:
+            if getattr(conv, "add_self_loops", True):
+                from torch_geometric.utils import add_self_loops
+
+                ei = add_self_loops(edge_index, num_nodes=num_nodes)[0]
+            else:
+                ei = edge_index
+            norm = (
+                edge_weight
+                if edge_weight is not None
+                else torch.ones(ei.size(1), device=x.device)
+            )
+        src, dst = ei[0], ei[1]
+
+        xp = x.clamp(min=0)
+        msg = norm[:, None] * xp[src]  # (E, F)
+        agg = torch.zeros(num_nodes, x.size(1), device=x.device)
+        agg.index_add_(0, dst, norm[:, None] * x[src])
+        agg_pos = agg.clamp(min=0)
+
+        r_agg = self._linear_lrp(conv.lin.weight, agg_pos, r, eps)  # (N, F)
+
+        frac = msg / agg_pos[dst].clamp(min=eps)  # (E, F)
+        r_msg = (r_agg[dst] * frac).sum(dim=-1)  # (E,)
+        r_to_src = torch.zeros(num_nodes, x.size(1), device=x.device)
+        r_to_src.index_add_(0, src, r_agg[dst] * frac)
+        return r_to_src, r_msg

graph_explain/narration/__init__.py

@@ -0,0 +1,3 @@
+from .narrator import Narrator, describe, narrate, summarize
+
+__all__ = ["Narrator", "describe", "narrate", "summarize"]

graph_explain/narration/narrator.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Any
+
+import torch
+
+
+def _top_values(importance, k: int) -> list[tuple[int, float]]:
+    imp = importance.detach().reshape(-1)
+    n = int(imp.numel())
+    k = max(1, min(int(k), n))
+    idx = imp.argsort(descending=True)[:k]
+    return [(int(i), float(imp[i])) for i in idx.tolist()]
+
+
+def _data_context(explanation, data: Any | None):
+    if data is None:
+        data = explanation.metadata.get("backing_data")
+    backend = explanation.metadata.get("backend")
+    return backend, data
+
+
+def _labels(explanation, data: Any | None) -> Any | None:
+    backend, data = _data_context(explanation, data)
+    if backend is None or data is None:
+        return None
+    try:
+        return backend.node_labels(data)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _edge_index(data, backend) -> Any | None:
+    if backend is not None and data is not None:
+        try:
+            return backend.edge_index(data)
+        except Exception:  # noqa: BLE001
+            return None
+    return None
+
+
+def summarize(explanation, data: Any | None = None, top_k: int = 5) -> dict[str, Any]:
+    """Structured summary of an explanation (for narration or JSON)."""
+    backend, data = _data_context(explanation, data)
+    node = explanation.node_idx
+    target = explanation.target_class
+    pred = None
+    if explanation.prediction_original is not None:
+        p = explanation.prediction_original
+        if torch.is_tensor(p):
+            pred = int(p.reshape(-1).argmax().item())
+    labels = _labels(explanation, data)
+
+    true_label = None
+    if labels is not None and node is not None:
+        try:
+            true_label = int(labels[node].item())
+        except Exception:  # noqa: BLE001
+            true_label = None
+
+    summary: dict[str, Any] = {
+        "node": None if node is None else int(node),
+        "target_class": target,
+        "predicted_class": pred,
+        "true_class": true_label,
+        "correct": (
+            None if pred is None or true_label is None else bool(pred == true_label)
+        ),
+        "important_nodes": (
+            _top_values(explanation.node_importance, top_k)
+            if explanation.node_importance is not None
+            else []
+        ),
+        "important_edges": [],
+        "counterfactual": bool(explanation.metadata.get("counterfactual", False)),
+    }
+    if explanation.edge_importance is not None:
+        ei = _edge_index(data, backend)
+        top = _top_values(explanation.edge_importance, top_k)
+        if ei is None:
+            summary["important_edges"] = [v for _, v in top]
+        else:
+            summary["important_edges"] = [
+                (int(ei[0, i]), int(ei[1, i]), v) for i, v in top
+            ]
+    if summary["counterfactual"]:
+        summary["original_class"] = explanation.metadata.get("original_class")
+    return summary
+
+
+def describe(explanation, data: Any | None = None, top_k: int = 5) -> str:
+    """Deterministic template-based narration of an explanation (Spanish by default)."""
+    s = summarize(explanation, data, top_k)
+    node = s["node"]
+    target = (
+        s["target_class"] if s["target_class"] is not None else s["predicted_class"]
+    )
+
+    if node is None:
+        head = "Explicación a nivel de grafo."
+    else:
+        head = f"Explicación del nodo {node}."
+    if target is not None:
+        head += f" La clase objetivo es {target}."
+    if s["correct"] is True:
+        head += " La predicción del modelo es correcta."
+    elif s["correct"] is False:
+        head += " La predicción del modelo difiere de la etiqueta real."
+
+    nodes_txt = ", ".join(
+        f"nodo {i} (importancia {v:.3f})" for i, v in s["important_nodes"]
+    )
+    tail = f"Los nodos más relevantes son {nodes_txt}." if nodes_txt else ""
+
+    if s["important_edges"]:
+        pieces = []
+        for e in s["important_edges"]:
+            if len(e) == 3:
+                u, v, w = e
+                pieces.append(f"arista {u}-{v} ({w:.3f})")
+            else:
+                pieces.append(f"arista con relevancia {float(e):.3f}")
+        tail += " Las aristas más relevantes son " + ", ".join(pieces) + "."
+
+    if s["counterfactual"]:
+        n = len(s["important_edges"])
+        new_class = s["predicted_class"]
+        change = (
+            f"la clase {s['original_class']} a la clase {new_class}"
+            if new_class is not None
+            else f"la clase {s['original_class']}"
+        )
+        tail += (
+            f" Se necesitaron {n} cambios"
+            f" (aristas/features eliminadas) para cambiar la predicción de"
+            f" {change}."
+        )
+    if tail:
+        head += " " + tail.strip()
+    return head.strip() or "Sin datos suficientes para describir la explicación."
+
+
+def _prompt(summary: dict[str, Any]) -> str:
+    return (
+        "Eres un asistente que explica predicciones de GNNs en lenguaje natural. "
+        "Dado este resumen de una explicación (JSON), escribe un párrafo breve "
+        "en español (2-4 oraciones) describiendo qué hace el modelo y qué "
+        "evidencia respalda su predicción. Resumen:\n"
+        + json.dumps(summary, ensure_ascii=False, indent=2)
+    )
+
+
+def narrate(
+    explanation,
+    llm: Callable[[str], str] | None = None,
+    data: Any | None = None,
+    top_k: int = 5,
+) -> str:
+    """Narrates an explanation. With `llm` (a `prompt -> text` callable) it uses the
+    generative model's output; otherwise it falls back to deterministic
+    template-based narration."""
+    summary = summarize(explanation, data, top_k)
+    deterministic = describe(explanation, data, top_k)
+    if llm is None:
+        return deterministic
+    try:
+        return llm(_prompt(summary)).strip()
+    except Exception as exc:  # noqa: BLE001
+        return f"{deterministic}\n\n[LLM no disponible: {exc}]"
+
+
+class Narrator:
+    """Reusable narrator; lets you inject the LLM just once."""
+
+    def __init__(self, llm: Callable[[str], str] | None = None, top_k: int = 5):
+        self.llm = llm
+        self.top_k = top_k
+
+    def describe(self, explanation, data: Any | None = None) -> str:
+        return describe(explanation, data, self.top_k)
+
+    def narrate(self, explanation, data: Any | None = None) -> str:
+        return narrate(explanation, self.llm, data, self.top_k)

graph_explain/visualization/__init__.py

@@ -0,0 +1,4 @@
+from .interactive import visualize_interactive
+from .static import show, visualize_static
+
+__all__ = ["show", "visualize_interactive", "visualize_static"]