graph-explain 0.7.0__py3-none-any.whl

graph_explain/methods/counterfactual/counterfactual.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+from collections import deque
+from typing import Any
+
+import torch
+import torch.nn.functional as F
+
+from ...core.explanation import Explanation
+from ...core.registry import register
+from ..base import ExplanationAlgorithm
+
+
+def _softmax(logits, c: int) -> float:
+    return float(F.softmax(logits[None], dim=-1)[0, c].item())
+
+
+@register("counterfactual", "counterfactual_explainer", "cf")
+class Counterfactual(ExplanationAlgorithm):
+    """Counterfactual explanation: minimal perturbation that changes the prediction.
+
+    Finds the minimal set of edges (mode='edge') or feature coordinates
+    (mode='feature') whose removal/re-scaling makes the node's prediction change
+    class (or reach `flip_to`). The search is greedy and deterministic: at each
+    step it removes the candidate element that most reduces `P(original class)`;
+    if the class does not change within `max_steps` steps it returns the current
+    state (prediction unchanged).
+
+    The returned importance marks the modified elements (edges 0/1, nodes from
+    their incidence on removed edges, changed features 0/1), with
+    `prediction_explanation` = logits after the perturbation.
+    """
+
+    def __init__(
+        self,
+        mode: str = "edge",
+        flip_to: int | None = None,
+        max_steps: int = 10,
+        hops: int = 2,
+        eps: float = 0.0,
+        seed: int = 0,
+    ):
+        if mode not in ("edge", "feature"):
+            raise ValueError("mode debe ser 'edge' o 'feature'.")
+        self.mode = mode
+        self.flip_to = flip_to
+        self.max_steps = int(max_steps)
+        self.hops = int(hops)
+        self.eps = float(eps)
+        torch.manual_seed(seed)
+
+    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()
+        node = self._single_node(index)
+        x = backend.node_features(data).detach().clone()
+        edge_index = backend.edge_index(data)
+        edge_weight = backend.edge_weight(data)
+        num_nodes = int(x.size(0))
+
+        orig_logits = backend.forward(model, x, edge_index, edge_weight=edge_weight)
+        orig_class = int(orig_logits[node].argmax().item())
+        flip_class = target_class if self.flip_to is None else self.flip_to
+        target_new = None if flip_class is None else int(flip_class)
+
+        device = x.device
+        if self.mode == "edge":
+            edge_importance, final_logits = self._flip_edges(
+                backend,
+                model,
+                x,
+                edge_index,
+                edge_weight,
+                node,
+                orig_class,
+                target_new,
+                device,
+            )
+            return self._build(
+                backend,
+                data,
+                node,
+                orig_class,
+                orig_logits,
+                final_logits,
+                node_importance=torch.bincount(
+                    torch.cat(
+                        [
+                            edge_index[0][edge_importance.bool()],
+                            edge_index[1][edge_importance.bool()],
+                        ]
+                    ),
+                    minlength=num_nodes,
+                ).float(),
+                edge_importance=edge_importance,
+                feature_importance=None,
+            )
+        feature_importance, _final_x, final_logits = self._flip_features(
+            backend,
+            model,
+            x,
+            edge_index,
+            edge_weight,
+            node,
+            orig_class,
+            target_new,
+            device,
+        )
+        return self._build(
+            backend,
+            data,
+            node,
+            orig_class,
+            orig_logits,
+            final_logits,
+            node_importance=torch.zeros(num_nodes).index_fill(
+                0, torch.tensor([node], device=device), 1.0
+            ),
+            edge_importance=None,
+            feature_importance=feature_importance,
+        )
+
+    # ------------------------------------------------------------------ búsquedas
+    def _flip_edges(
+        self,
+        backend,
+        model,
+        x,
+        edge_index,
+        edge_weight,
+        node,
+        orig_class,
+        target_new,
+        device,
+    ):
+        num_nodes = int(x.size(0))
+        weight = (
+            edge_weight.detach().clone()
+            if edge_weight is not None
+            else torch.ones(edge_index.size(1), device=device)
+        )
+        candidates = self._candidate_edges(edge_index, num_nodes, node, self.hops)
+        removed: list[int] = []
+        pred = backend.forward(model, x, edge_index, edge_weight=weight)[node]
+
+        def flipped(logits, tc):
+            pred_cls = int(logits.argmax().item())
+            return pred_cls == tc if tc is not None else pred_cls != orig_class
+
+        for _ in range(self.max_steps):
+            if flipped(pred, target_new):
+                break
+            remaining = [e for e in candidates if e not in removed]
+            if not remaining:
+                break
+            best_e, best_logits, best_p = None, None, None
+            with torch.no_grad():
+                for e in remaining:
+                    w = weight.clone()
+                    w[e] = 0.0
+                    lg = backend.forward(model, x, edge_index, edge_weight=w)[node]
+                    p = float(_softmax(lg, orig_class))
+                    if best_p is None or p < best_p:
+                        best_e, best_logits, best_p = e, lg, p
+            if best_e is None or (
+                best_p is not None
+                and best_p >= float(_softmax(pred, orig_class)) - self.eps
+            ):
+                break
+            removed.append(best_e)
+            weight[best_e] = 0.0
+            pred = best_logits
+
+        importance = torch.zeros(edge_index.size(1), device=device)
+        importance[removed] = 1.0
+        return importance, pred.detach()
+
+    def _flip_features(
+        self,
+        backend,
+        model,
+        x,
+        edge_index,
+        edge_weight,
+        node,
+        orig_class,
+        target_new,
+        device,
+    ):
+        baseline = x.mean(dim=0, keepdim=True)
+        x_cur = x.detach().clone()
+        changed: list[int] = []
+        pred = backend.forward(model, x_cur, edge_index, edge_weight=edge_weight)[node]
+
+        def flipped(logits, tc):
+            pred_cls = int(logits.argmax().item())
+            return pred_cls == tc if tc is not None else pred_cls != orig_class
+
+        for _ in range(self.max_steps):
+            if flipped(pred, target_new):
+                break
+            best_c, best_logits, best_p = None, None, None
+            with torch.no_grad():
+                for c in range(x.size(1)):
+                    if c in changed:
+                        continue
+                    xn = x_cur.clone()
+                    xn[node, c] = baseline[0, c]
+                    lg = backend.forward(
+                        model, xn, edge_index, edge_weight=edge_weight
+                    )[node]
+                    p = float(_softmax(lg, orig_class))
+                    if best_p is None or p < best_p:
+                        best_c, best_logits, best_p = c, lg, p
+            if best_c is None or (
+                best_p is not None
+                and best_p >= float(_softmax(pred, orig_class)) - self.eps
+            ):
+                break
+            changed.append(best_c)
+            x_cur[node, best_c] = baseline[0, best_c]
+            pred = best_logits
+
+        importance = torch.zeros(x.size(1), device=device)
+        importance[changed] = 1.0
+        return importance, x_cur, pred.detach()
+
+    # ------------------------------------------------------------------ utilidades
+    @staticmethod
+    def _single_node(index) -> int:
+        if index is None:
+            return 0
+        if isinstance(index, (list, tuple)):
+            index = index[0]
+        return int(torch.as_tensor(index).reshape(-1)[0].item())
+
+    @staticmethod
+    def _candidate_edges(edge_index, num_nodes: int, node: int, hops: int) -> list[int]:
+        adj: dict[int, list[int]] = {}
+        for u, v in zip(edge_index[0].tolist(), edge_index[1].tolist()):
+            adj.setdefault(u, []).append(v)
+        distance = {node: 0}
+        queue = deque([node])
+        while queue:
+            cur = queue.popleft()
+            if distance[cur] >= hops:
+                continue
+            for nb in adj.get(cur, []):
+                if nb not in distance:
+                    distance[nb] = distance[cur] + 1
+                    queue.append(nb)
+        near = set(distance)
+        edges = []
+        for e in range(edge_index.size(1)):
+            u = int(edge_index[0, e].item())
+            v = int(edge_index[1, e].item())
+            if u in near or v in near:
+                edges.append(e)
+        return edges
+
+    def _build(
+        self,
+        backend,
+        data,
+        node,
+        orig_class,
+        orig_logits,
+        final_logits,
+        node_importance,
+        edge_importance,
+        feature_importance,
+    ) -> Explanation:
+        metadata = {
+            "backend": backend,
+            "backing_data": data,
+            "counterfactual": True,
+            "original_class": orig_class,
+        }
+        return Explanation(
+            node_importance=node_importance.detach().cpu(),
+            edge_importance=edge_importance.detach().cpu()
+            if edge_importance is not None
+            else None,
+            feature_importance=(
+                feature_importance.detach().cpu()
+                if feature_importance is not None
+                else None
+            ),
+            prediction_original=orig_logits[node].detach().cpu(),
+            prediction_explanation=final_logits.detach().cpu(),
+            node_idx=node,
+            target_class=int(final_logits.argmax().item())
+            if final_logits.numel()
+            else None,
+            metadata=metadata,
+            mask_threshold=0.5,
+        )

graph_explain/methods/feature/graph_lime.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+import torch
+
+from ...core.explanation import Explanation
+from ...core.registry import register
+from ..base import ExplanationAlgorithm
+
+
+@register("graph_lime", "glime", "gl")
+class GraphLIME(ExplanationAlgorithm):
+    """GraphLIME: feature attribution via weighted local regression.
+
+    Fits a linear regression (ridge, closed form) over the k-hop neighbors'
+    features, weighting each neighbor by its similarity to the target node's
+    feature (Gaussian kernel). The coefficients explain the probability
+    (softmax) of the target class; node importance matches the kernel
+    similarity.
+    """
+
+    def __init__(
+        self,
+        hops: int = 2,
+        lambda_: float = 1.0,
+        sigma: float | None = None,
+        normalize: bool = True,
+        **kwargs,
+    ):
+        self.hops = hops
+        self.lambda_ = lambda_
+        self.sigma = sigma
+        self.normalize = normalize
+
+    def explain(
+        self,
+        backend: Any,
+        model: Any,
+        data: Any,
+        index: 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))
+
+        nodes = self._to_node_ids(index, num_nodes)
+        root = int(nodes[0])
+        with torch.no_grad():
+            logits = backend.forward(model, x, edge_index)
+        if logits.dim() != 2:
+            raise ValueError(
+                "GraphLIME requiere predicciones node-level (logits (N, C))."
+            )
+        target = target_class
+        if target is None:
+            target = int(logits[root].argmax().item())
+        target = max(0, min(int(target), logits.size(1) - 1))
+
+        probs = torch.softmax(logits, dim=-1)[:, target].detach().cpu()
+
+        neighbors = self._khop_neighbors(edge_index, root, self.hops)
+        if root not in neighbors:
+            neighbors.append(root)
+        nb = torch.tensor(neighbors, dtype=torch.long)
+        x_nb = x[nb].detach().cpu()
+        y = probs[nb]
+
+        dists = torch.norm(x_nb - x[root : root + 1].detach().cpu(), dim=-1)
+        sigma = self.sigma
+        if sigma is None:
+            tail = dists[1:]
+            sigma = float(tail.mean().item()) if tail.numel() else 1.0
+            sigma = max(sigma, 1e-4)
+        weights = torch.exp(-(dists**2) / (2.0 * sigma**2))
+
+        coef = self._ridge(x_nb, y, weights, self.lambda_)
+
+        node_importance = torch.zeros(num_nodes)
+        node_importance[nb] = weights
+        node_importance = node_importance.cpu()
+
+        if self.normalize and coef.numel():
+            denom = coef.abs().max()
+            if denom > 1e-12:
+                coef = coef / denom
+
+        return Explanation(
+            node_importance=node_importance,
+            edge_importance=None,
+            feature_importance=coef,
+            prediction_original=logits[root].detach().cpu(),
+            prediction_explanation=None,
+            node_idx=root,
+            target_class=target,
+            metadata={"neighborhood": neighbors},
+        )
+
+    @staticmethod
+    def _ridge(
+        x: torch.Tensor, y: torch.Tensor, weights: torch.Tensor, lambda_: float
+    ) -> torch.Tensor:
+        ones = torch.ones(x.size(0), 1)
+        X = torch.cat([x, ones], dim=-1).double()
+        yw = (y * weights).double()
+        Xw = X * weights.unsqueeze(-1).double()
+        n_features = X.size(1)
+        gram = Xw.t() @ X + lambda_ * torch.eye(n_features, dtype=torch.double)
+        beta = torch.linalg.solve(gram, X.t() @ yw)
+        return beta[:-1].float()
+
+    @staticmethod
+    def _khop_neighbors(edge_index: torch.Tensor, node: int, hops: int) -> list[int]:
+        adj: dict[int, set[int]] = defaultdict(set)
+        src = edge_index[0].tolist()
+        dst = edge_index[1].tolist()
+        for s, d in zip(src, dst):
+            adj[s].add(d)
+            adj[d].add(s)
+        seen = {node}
+        frontier = {node}
+        for _ in range(hops):
+            nxt: set[int] = set()
+            for n in frontier:
+                nxt |= adj.get(n, set())
+            frontier = nxt - seen
+            seen |= frontier
+        return sorted(seen)
+
+    @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)

graph_explain/methods/gradient/grad_x_input.py

@@ -0,0 +1,110 @@
+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("grad_x_input", "gradient_x_input", "gx")
+class GradXInput(ExplanationAlgorithm):
+    """Gradient x Input: attribution as gradient scaled by the activation.
+
+    The importance of each feature (and of each edge, if the backend supports
+    edge weights) is the gradient of the target-class logit multiplied by the
+    input-baseline difference (zero baseline by default). Node importance is the
+    sum of `abs(grad * Δx)` over features.
+    """
+
+    graph_level = True
+
+    def __init__(
+        self,
+        baseline: str = "zero",
+        edge_grads: bool = True,
+        node_mask_type: str | None = "attributes",
+        **kwargs,
+    ):
+        self.baseline_name = baseline
+        self.edge_grads = edge_grads
+        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)
+        edge_index = backend.edge_index(data)
+        num_nodes = int(x.size(0))
+
+        nodes = self._to_node_ids(index, num_nodes)
+        with torch.no_grad():
+            logits = backend.forward(model, x, edge_index)
+        if logits.dim() != 2:
+            raise ValueError(
+                "GradXInput 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))
+
+        x_in = x.detach().clone().requires_grad_(True)
+        ew = None
+        compute_edge = self.edge_grads and backend.supports_edge_weight(model)
+        if compute_edge:
+            ew = torch.ones(
+                edge_index.size(1), dtype=torch.float32, device=x.device
+            ).requires_grad_(True)
+
+        out = backend.forward(model, x_in, edge_index, edge_weight=ew)
+        if out.dim() != 2:
+            raise ValueError("GradXInput requiere predicciones node-level.")
+        score = out[nodes, target_cls].sum()
+        model.zero_grad()
+        score.backward()
+
+        grad_x = x_in.grad.detach()
+        baseline = torch.zeros_like(x_in)
+        contrib = grad_x * (x_in - baseline)
+
+        node_importance = contrib.abs().sum(dim=-1)
+        feature_importance = contrib.detach()
+
+        edge_importance = None
+        if compute_edge and ew is not None and ew.grad is not None:
+            edge_importance = ew.grad.detach().abs()
+
+        return Explanation(
+            node_importance=node_importance.cpu(),
+            edge_importance=(
+                edge_importance.cpu() if edge_importance is not None else None
+            ),
+            feature_importance=(
+                feature_importance.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,
+        )
+
+    @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)

graph_explain/methods/gradient/guided_backprop.py

@@ -0,0 +1,117 @@
+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
+
+
+@register("guided_backprop", "guided-backprop", "gbp")
+class GuidedBackprop(ExplanationAlgorithm):
+    """Guided Backpropagation: gradients guided by the ReLU mask.
+
+    During backpropagation the gradient is filtered: it only propagates where
+    the ReLU activation was positive (negative gradients are discarded),
+    highlighting the features that positively contribute to the class. Temporary
+    hooks are registered on the `nn.ReLU` modules; if the model has none, it
+    falls back to standard gradients (metadata `guided=False`).
+    """
+
+    graph_level = True
+
+    def __init__(self, fallback_to_gradient: bool = True, **kwargs):
+        self.fallback_to_gradient = fallback_to_gradient
+
+    def explain(
+        self,
+        backend: Any,
+        model: Any,
+        data: Any,
+        index: 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))
+
+        nodes = self._to_node_ids(index, num_nodes)
+        root = int(nodes[0])
+        with torch.no_grad():
+            logits = backend.forward(model, x, edge_index)
+        if logits.dim() != 2:
+            raise ValueError(
+                "GuidedBackprop requiere predicciones node-level (logits (N, C))."
+            )
+        target = target_class
+        if target is None:
+            target = int(logits[root].argmax().item())
+        target = max(0, min(int(target), logits.size(1) - 1))
+
+        relus = [m for m in model.modules() if isinstance(m, nn.ReLU)]
+        hooks, guided = [], False
+        if relus and self.fallback_to_gradient:
+            guided = True
+            for module in relus:
+                fw = module.register_forward_hook(self._mask_forward)
+                bw = module.register_full_backward_hook(self._guide_backward)
+                hooks.extend((fw, bw))
+
+        try:
+            x_in = x.detach().clone().requires_grad_(True)
+            out = backend.forward(model, x_in, edge_index)
+            if out.dim() != 2:
+                raise ValueError("GuidedBackprop requiere predicciones node-level.")
+            score = out[root, target]
+            model.zero_grad()
+            score.backward()
+            grad = (
+                x_in.grad.detach() if x_in.grad is not None else torch.zeros_like(x_in)
+            )
+        finally:
+            for hook in hooks:
+                hook.remove()
+
+        node_importance = grad.abs().sum(dim=-1)
+        return Explanation(
+            node_importance=node_importance.cpu(),
+            edge_importance=None,
+            feature_importance=grad.cpu(),
+            prediction_original=logits[root].detach().cpu(),
+            prediction_explanation=None,
+            node_idx=root,
+            target_class=target,
+            metadata={"guided": guided},
+        )
+
+    @staticmethod
+    def _mask_forward(module, inp, out):
+        mask = torch.where(out > 0, torch.ones_like(out), torch.zeros_like(out))
+        module._gbp_mask = mask.detach()
+
+    @staticmethod
+    def _guide_backward(module, grad_input, grad_output):
+        mask = module._gbp_mask
+        if mask is None or not grad_output or grad_output[0] is None:
+            return grad_input
+        g = grad_output[0]
+        if g.shape != mask.shape:
+            return grad_input
+        guided = (g * mask).clamp(min=0)
+        if len(grad_input) == 1:
+            return (guided,)
+        return grad_input
+
+    @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)