graph-explain 0.7.0__py3-none-any.whl

graph_explain/__init__.py

@@ -0,0 +1,79 @@
+from .backends import DGLAdapter, PyGAdapter, get_backend
+from .core import (
+    Explainer,
+    Explanation,
+    compare,
+    get_algorithm,
+    instantiate,
+    register,
+    report_html,
+)
+from .core.evaluation import (
+    evaluate_fidelity_minus,
+    evaluate_fidelity_plus,
+    evaluate_gea,
+    evaluate_gea_graph,
+    evaluate_sparsity,
+    evaluate_stability,
+)
+from .methods import (
+    AttentionExplainer,
+    Counterfactual,
+    DeepLift,
+    GNNExplainer,
+    GNNGatedLRP,
+    GradXInput,
+    GraphLIME,
+    GuidedBackprop,
+    IntegratedGradients,
+    NodeMask,
+    PGExplainer,
+    RandomBaseline,
+    Saliency,
+    SubgraphX,
+)
+from .narration import Narrator, describe, narrate, summarize
+from .visualization import show, visualize_interactive, visualize_static
+
+__version__ = "0.7.0"
+
+__all__ = [
+    "AttentionExplainer",
+    "Counterfactual",
+    "DGLAdapter",
+    "DeepLift",
+    "Explainer",
+    "Explanation",
+    "GNNExplainer",
+    "GNNGatedLRP",
+    "GradXInput",
+    "GraphLIME",
+    "GuidedBackprop",
+    "IntegratedGradients",
+    "Narrator",
+    "NodeMask",
+    "PGExplainer",
+    "PyGAdapter",
+    "RandomBaseline",
+    "Saliency",
+    "SubgraphX",
+    "__version__",
+    "compare",
+    "describe",
+    "evaluate_fidelity_minus",
+    "evaluate_fidelity_plus",
+    "evaluate_gea",
+    "evaluate_gea_graph",
+    "evaluate_sparsity",
+    "evaluate_stability",
+    "get_algorithm",
+    "get_backend",
+    "instantiate",
+    "narrate",
+    "register",
+    "report_html",
+    "show",
+    "summarize",
+    "visualize_interactive",
+    "visualize_static",
+]

graph_explain/backends/__init__.py

@@ -0,0 +1,4 @@
+from .base import Backend, PyGAdapter, get_backend
+from .dgl import DGLAdapter
+
+__all__ = ["Backend", "DGLAdapter", "PyGAdapter", "get_backend"]

graph_explain/backends/base.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from inspect import signature
+from typing import Any
+
+import torch
+
+
+class Backend(ABC):
+    name: str = "base"
+
+    @abstractmethod
+    def num_nodes(self, data: Any) -> int: ...
+
+    @abstractmethod
+    def node_features(self, data: Any) -> torch.Tensor: ...
+
+    @abstractmethod
+    def edge_index(self, data: Any) -> torch.Tensor: ...
+
+    @abstractmethod
+    def edge_weight(self, data: Any) -> torch.Tensor | None: ...
+
+    @abstractmethod
+    def node_labels(self, data: Any) -> torch.Tensor | None: ...
+
+    @abstractmethod
+    def to_networkx(self, data: Any): ...
+
+    def supports_edge_weight(self, model: Any) -> bool:
+        try:
+            params = signature(model.forward).parameters
+        except (TypeError, ValueError):
+            return False
+        return "edge_weight" in params
+
+    def forward(
+        self,
+        model: Any,
+        x: torch.Tensor,
+        edge_index: torch.Tensor,
+        edge_weight: torch.Tensor | None = None,
+        node_mask: torch.Tensor | None = None,
+        **model_kwargs: Any,
+    ) -> torch.Tensor:
+        x_masked = x
+        if node_mask is not None:
+            expand = (-1,) * x_masked.dim()
+            node_mask = node_mask.to(x_masked.dtype)
+            x_masked = x_masked * node_mask.view((node_mask.shape[0], *expand[1:]))
+        if edge_weight is not None and not self.supports_edge_weight(model):
+            raise ValueError(
+                "El modelo no acepta edge_weight. Los métodos por perturbación de "
+                "aristas requieren modelos GNN con soporte para edge_weight "
+                "(p.ej. GCNConv, GATConv)."
+            )
+        kwargs: dict = {}
+        if edge_weight is not None:
+            kwargs["edge_weight"] = edge_weight
+        kwargs.update(model_kwargs)
+        return model(x_masked, edge_index, **kwargs)
+
+
+class PyGAdapter(Backend):
+    name = "pyg"
+
+    def num_nodes(self, data: Any) -> int:
+        return int(data.num_nodes)
+
+    def node_features(self, data: Any) -> torch.Tensor:
+        return data.x
+
+    def edge_index(self, data: Any) -> torch.Tensor:
+        return data.edge_index
+
+    def edge_weight(self, data: Any) -> torch.Tensor | None:
+        return getattr(data, "edge_weight", None)
+
+    def node_labels(self, data: Any) -> torch.Tensor | None:
+        return getattr(data, "y", None)
+
+    def to_networkx(self, data: Any):
+        from torch_geometric.utils import to_networkx
+
+        return to_networkx(data, to_undirected=True)
+
+
+def get_backend(name: str) -> Backend:
+    if name == "pyg":
+        return PyGAdapter()
+    if name == "dgl":
+        from ..backends.dgl import DGLAdapter
+
+        return DGLAdapter()
+    raise ValueError(f"Backend desconocido: {name}. Disponibles: ['pyg', 'dgl']")
+
+
+def default_mask_type(model: Any, data: Any) -> tuple[str | None, str | None]:
+    edge_mask_type = "object" if getattr(data, "edge_index", None) is not None else None
+    x = getattr(data, "x", None)
+    node_mask_type = "attributes" if x is not None else None
+    return node_mask_type, edge_mask_type

graph_explain/backends/dgl.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import Any
+
+import torch
+
+from .base import Backend
+
+_FEATURE_KEYS = ("feat", "x", "features")
+_LABEL_KEYS = ("label", "y", "labels")
+_WEIGHT_KEYS = ("w", "weight", "edge_weight")
+
+
+def _first_available(mapping: dict, keys: tuple[str, ...], default):
+    for k in keys:
+        if k in mapping:
+            return mapping[k]
+    return default
+
+
+class DGLAdapter(Backend):
+    """Adapter for `dgl.DGLGraph` graphs and DGL models.
+
+    Data convention: node features live in `ndata['feat']`, labels in
+    `ndata['label']` and edge weights in `edata['w']` ('x'/'weight' are also
+    accepted). The DGL model must read `g.ndata['feat']` and `g.edata['w']` in
+    its `forward(graph, feat)`.
+    """
+
+    name = "dgl"
+
+    def __init__(
+        self,
+        feat_key: str | None = None,
+        label_key: str | None = None,
+        edge_weight_key: str | None = None,
+    ):
+        self.feat_key = feat_key
+        self.label_key = label_key
+        self.edge_weight_key = edge_weight_key
+
+    @staticmethod
+    def _require_dgl():
+        try:
+            import dgl
+        except ImportError as exc:
+            raise ImportError(
+                "El backend 'dgl' requiere la librería DGL (pip install dgl). "
+                "Además, DGL necesita una versión de PyTorch con librerías "
+                "precompiladas de graphbolt (ver docs de instalación de DGL)."
+            ) from exc
+        return dgl
+
+    def num_nodes(self, data: Any) -> int:
+        if callable(getattr(data, "num_nodes", None)):
+            return int(data.num_nodes())
+        return int(data.num_nodes)
+
+    def node_features(self, data: Any) -> torch.Tensor:
+        ndata: dict = getattr(data, "ndata", {})
+        feat = ndata.get(self.feat_key) if self.feat_key else ndata.get("feat")
+        if feat is None:
+            feat = _first_available(ndata, _FEATURE_KEYS, None)
+        if feat is None:
+            raise ValueError(
+                "El grafo DGL no tiene features de nodo (ndata['feat']/['x'])."
+            )
+        return feat
+
+    def edge_index(self, data: Any) -> torch.Tensor:
+        u, v = data.edges()
+        return torch.stack([u, v], dim=0)
+
+    def edge_weight(self, data: Any) -> torch.Tensor | None:
+        edata: dict = getattr(data, "edata", {})
+        w = edata.get(self.edge_weight_key) if self.edge_weight_key else edata.get("w")
+        if w is None:
+            w = _first_available(edata, _WEIGHT_KEYS, None)
+        return w
+
+    def node_labels(self, data: Any) -> torch.Tensor | None:
+        ndata: dict = getattr(data, "ndata", {})
+        lab = ndata.get(self.label_key) if self.label_key else ndata.get("label")
+        if lab is None:
+            lab = _first_available(ndata, _LABEL_KEYS, None)
+        return lab
+
+    def to_networkx(self, data: Any):
+        return data.to_networkx()
+
+    def supports_edge_weight(self, model: Any) -> bool:
+        return True
+
+    def forward(
+        self,
+        model: Any,
+        x: torch.Tensor,
+        edge_index: torch.Tensor,
+        edge_weight: torch.Tensor | None = None,
+        node_mask: torch.Tensor | None = None,
+        **model_kwargs: Any,
+    ) -> torch.Tensor:
+        dgl = self._require_dgl()
+        x_masked = x
+        if node_mask is not None:
+            expand = (-1,) * x_masked.dim()
+            node_mask = node_mask.to(x_masked.dtype)
+            x_masked = x_masked * node_mask.view((node_mask.shape[0], *expand[1:]))
+        num_nodes = max(int(x_masked.size(0)), int(edge_index.max().item()) + 1)
+        g = dgl.graph(
+            (edge_index[0], edge_index[1]),
+            num_nodes=num_nodes,
+        )
+        g.ndata["feat"] = x_masked
+        g.ndata["x"] = x_masked
+        if edge_weight is not None:
+            g.edata["w"] = edge_weight
+            g.edata["weight"] = edge_weight
+        kwargs: dict = {}
+        kwargs.update(model_kwargs)
+        return model(g, x_masked, **kwargs)

graph_explain/benchmarks/__init__.py

@@ -0,0 +1,3 @@
+from .synthetic import ba_shapes, build_data
+
+__all__ = ["ba_shapes", "build_data"]

graph_explain/benchmarks/synthetic.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import networkx as nx
+import numpy as np
+import torch
+
+
+def _house_motif(offset: int, anchor_in_motif: int = 3):
+    edges_motif = [
+        (0, 1),
+        (0, 2),
+        (1, 2),
+        (1, 3),
+        (2, 4),
+        (3, 4),
+    ]
+    edges = [(u + offset, v + offset) for u, v in edges_motif]
+    labels = {}
+    for i in range(5):
+        labels[i + offset] = 0
+    labels[offset + anchor_in_motif] = 1
+    labels[offset + 0] = 2
+    for i in range(5):
+        if i != anchor_in_motif and i != 0:
+            labels[i + offset] = 3
+    return edges, labels
+
+
+def ba_shapes(
+    base_nodes: int = 300,
+    num_houses: int = 80,
+    m: int = 5,
+    seed: int = 0,
+    num_features: int = 10,
+    feature_style: str = "degree",
+) -> tuple[
+    torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor
+]:
+    rng = np.random.default_rng(seed)
+    g = nx.barabasi_albert_graph(base_nodes, m, seed=seed)
+    g = g.to_undirected()
+
+    node_count = base_nodes
+    labels: dict[int, int] = {}
+
+    anchors = rng.choice(base_nodes, size=num_houses, replace=False)
+    for i, anchor in enumerate(anchors):
+        edges_m, lab = _house_motif(node_count)
+        g.add_nodes_from(range(node_count, node_count + 5))
+        g.add_edges_from(edges_m)
+        g.add_edge(anchor, node_count + 3)
+        labels.update(lab)
+        node_count += 5
+
+    degrees = np.array([d for _, d in g.degree()], dtype=np.float64)
+    max_deg = int(degrees.max()) + 1
+    feat_dim = max(max_deg, num_features)
+    if feature_style == "random":
+        x = rng.normal(0.0, 1.0, size=(node_count, num_features)).astype(np.float32)
+    else:
+        x = np.zeros((node_count, feat_dim), dtype=np.float32)
+        x[np.arange(node_count), np.minimum(degrees.astype(np.int64), feat_dim - 1)] = (
+            1.0
+        )
+
+    edge_index = torch.tensor(np.array(g.edges(), dtype=np.int64).T, dtype=torch.long)
+    edge_index = torch.cat([edge_index, edge_index.flip(0)], dim=1)
+    y = torch.zeros(node_count, dtype=torch.long)
+    for n, l in labels.items():
+        y[n] = l
+    x = torch.from_numpy(x)
+
+    house_anchors = torch.from_numpy(anchors)
+
+    perm = rng.permutation(node_count)
+    train_mask = torch.zeros(node_count, dtype=torch.bool)
+    test_mask = torch.zeros(node_count, dtype=torch.bool)
+    split = int(0.3 * node_count)
+    train_mask[perm[:split]] = True
+    test_mask[perm[split:]] = True
+    train_mask[list(anchors)] = True
+    test_mask[list(anchors)] = True
+
+    return x, edge_index, y, train_mask, test_mask, house_anchors
+
+
+def build_data(
+    base_nodes: int = 300,
+    num_houses: int = 80,
+    m: int = 5,
+    seed: int = 0,
+    num_features: int = 10,
+    feature_style: str = "degree",
+):
+    from torch_geometric.data import Data
+
+    x, edge_index, y, train_mask, test_mask, house_anchors = ba_shapes(
+        base_nodes=base_nodes,
+        num_houses=num_houses,
+        m=m,
+        seed=seed,
+        num_features=num_features,
+        feature_style=feature_style,
+    )
+    return Data(
+        x=x,
+        edge_index=edge_index,
+        y=y,
+        train_mask=train_mask,
+        test_mask=test_mask,
+        house_anchors=house_anchors,
+        base_nodes=base_nodes,
+        num_houses=num_houses,
+    )
+
+
+def build_graph_classification(
+    num_pos: int = 20,
+    num_neg: int = 20,
+    base_nodes_range: tuple[int, int] = (15, 30),
+    m: int = 2,
+    seed: int = 0,
+    num_features: int = 8,
+    feature_style: str = "random",
+):
+    """Graph classification dataset with a known 'house' motif.
+
+    Returns a list of graph-level `Data` with a binary label `y` (1 if the graph
+    contains the house motif). Each graph carries `gt_edge_mask` (bool over the
+    directed edges, both directions included) and `gt_nodes` with the motif
+    nodes (+ hub).
+    """
+    from torch_geometric.data import Data
+
+    rng = np.random.default_rng(seed)
+    graphs: list[Data] = []
+    for cls in (1, 0):
+        count = num_pos if cls == 1 else num_neg
+        for _ in range(count):
+            base = int(rng.integers(base_nodes_range[0], base_nodes_range[1] + 1))
+            tree_seed = int(rng.integers(0, 2**31 - 1))
+            g = nx.barabasi_albert_graph(base, m, seed=tree_seed)
+            g = g.to_undirected()
+
+            gt_nodes: list[int] = []
+            gt_edges: list[tuple[int, int]] = []
+            if cls == 1:
+                offset = g.number_of_nodes()
+                anchor = int(rng.integers(0, base))
+                edges_m, _ = _house_motif(offset)
+                g.add_nodes_from(range(offset, offset + 5))
+                g.add_edges_from(edges_m)
+                g.add_edge(anchor, offset + 3)
+                gt_nodes = list(range(offset, offset + 5)) + [anchor]
+                gt_edges = list(edges_m) + [(anchor, offset + 3)]
+
+            if feature_style == "degree":
+                degrees = np.array([d for _, d in g.degree()], dtype=np.float64)
+                feat_dim = max(int(degrees.max()) + 1, num_features)
+                x = np.zeros((g.number_of_nodes(), feat_dim), dtype=np.float32)
+                x[
+                    np.arange(g.number_of_nodes()),
+                    np.minimum(degrees.astype(np.int64), feat_dim - 1),
+                ] = 1.0
+            else:
+                x = rng.normal(
+                    0.0,
+                    1.0,
+                    size=(g.number_of_nodes(), num_features),
+                ).astype(np.float32)
+
+            edge_index = torch.tensor(
+                np.array(g.edges(), dtype=np.int64).T, dtype=torch.long
+            )
+            edge_index = torch.cat([edge_index, edge_index.flip(0)], dim=1)
+
+            gt_pairs = set(gt_edges) | {(v, u) for u, v in gt_edges}
+            gt_edge_mask = torch.zeros(edge_index.size(1), dtype=torch.bool)
+            if cls == 1:
+                for i, (s, d) in enumerate(
+                    zip(edge_index[0].tolist(), edge_index[1].tolist())
+                ):
+                    if (s, d) in gt_pairs:
+                        gt_edge_mask[i] = True
+
+            graphs.append(
+                Data(
+                    x=torch.from_numpy(x),
+                    edge_index=edge_index,
+                    y=torch.tensor([cls], dtype=torch.long),
+                    num_nodes=g.number_of_nodes(),
+                    gt_edge_mask=gt_edge_mask,
+                    gt_nodes=sorted(gt_nodes),
+                )
+            )
+    return graphs
+
+
+def ground_truth_edges_graph(data) -> list[int]:
+    """(Directed) indices of the motif edges for a graph of the dataset."""
+    mask = getattr(data, "gt_edge_mask", None)
+    if mask is None:
+        return []
+    return mask.nonzero(as_tuple=False).flatten().tolist()
+
+
+HOUSE_SIZE = 5
+
+
+def ground_truth_nodes(data, node: int) -> list[int]:
+    base_nodes = int(getattr(data, "base_nodes", 0))
+    if base_nodes <= 0:
+        return []
+    node = int(node)
+    if node >= base_nodes:
+        house_idx = (node - base_nodes) // HOUSE_SIZE
+        return list(
+            range(
+                base_nodes + house_idx * HOUSE_SIZE,
+                base_nodes + (house_idx + 1) * HOUSE_SIZE,
+            )
+        )
+    anchors = data.house_anchors
+    if anchors is not None and anchors.numel() and node in anchors.tolist():
+        idx = int((anchors == node).nonzero(as_tuple=False).flatten()[0])
+        members = list(
+            range(base_nodes + idx * HOUSE_SIZE, base_nodes + (idx + 1) * HOUSE_SIZE)
+        )
+        return members + [node]
+    return []
+
+
+def ground_truth_edge_ids(data, node: int, edge_index) -> list[int]:
+    import torch
+
+    gt_nodes = set(ground_truth_nodes(data, node))
+    if not gt_nodes:
+        return []
+    src = edge_index[0]
+    dst = edge_index[1]
+    both = torch.isin(src, torch.as_tensor(list(gt_nodes))) & torch.isin(
+        dst, torch.as_tensor(list(gt_nodes))
+    )
+    if torch.is_tensor(both):
+        return both.nonzero(as_tuple=False).flatten().tolist()
+    return [i for i, ok in enumerate(both) if ok]