graph-explain 0.7.2__tar.gz → 0.8.0__tar.gz

{graph_explain-0.7.2 → graph_explain-0.8.0}/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

{graph_explain-0.7.2/src/graph_explain.egg-info → graph_explain-0.8.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: graph-explain
-Version: 0.7.2
+Version: 0.8.0
 Summary: Explainability library for graph-based models (GNN)
 Author: graph-explain contributors
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Tzinny-dev/graph-explain
 Project-URL: Repository, https://github.com/Tzinny-dev/graph-explain
-Project-URL: Documentation, https://github.com/Tzinny-dev/graph-explain#readme
+Project-URL: Documentation, https://tzinny-dev.github.io/graph-explain/
 Keywords: gnn,explainability,xai,graph,neural-networks,interpretability
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
@@ -41,6 +41,7 @@ Requires-Dist: plotly>=5.15; extra == "all"
 Requires-Dist: pyvis>=0.3; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
 Provides-Extra: docs
@@ -52,6 +53,14 @@ Dynamic: license-file
 
 # graph-explain
 
+[![CI](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml/badge.svg)](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml)
+[![docs](https://github.com/Tzinny-dev/graph-explain/actions/workflows/docs.yml/badge.svg)](https://tzinny-dev.github.io/graph-explain/)
+[![coverage](https://tzinny-dev.github.io/graph-explain/_static/badges/coverage.svg)](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml)
+[![mypy](https://img.shields.io/badge/mypy-checked-blue)](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/graph-explain.svg)](https://pypi.org/project/graph-explain/)
+[![Python](https://img.shields.io/pypi/pyversions/graph-explain.svg)](https://pypi.org/project/graph-explain/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Tzinny-dev/graph-explain/blob/main/LICENSE)
+
 Explainability library for graph-based models (Graph Neural Networks).
 Explains a GNN's predictions in terms of **important nodes, edges and subgraphs**,
 with built-in metrics and visualization.
@@ -120,6 +129,9 @@ pip install -e .[all]
 Optional extras: `pyg` (PyTorch Geometric), `dgl` (DGL backend),
 `interactive` (plotly/pyvis).
 
+> 📚 **Documentation**: full API reference and guides at
+> https://tzinny-dev.github.io/graph-explain/
+
 ## Quick start
 
 ```python
@@ -127,16 +139,18 @@ from graph_explain import Explainer, GNNExplainer, Saliency
 from graph_explain.benchmarks.synthetic import build_data
 from graph_explain.visualization import show
 
-data = build_data(base_nodes=300, num_houses=80)   # BA-Shapes with ground truth
-model = GCN(in_channels=data.x.size(1))            # your trained GNN
+data = build_data(base_nodes=300, num_houses=80)  # BA-Shapes with ground truth
+model = GCN(in_channels=data.x.size(1))  # your trained GNN
 model.eval()
 
 explainer = Explainer(algorithm=GNNExplainer(epochs=150))
 expl = explainer.explain_node(data, model, node_idx=42)
 
 print(expl.evaluate(metrics=["fidelity", "sparsity"]))
-print(expl.evaluate(metrics=["sparsity"], local=True))  # sparsity over the node's k-hop subgraph
-show(expl, show_labels=True)                       # highlight the explanatory subgraph
+print(
+    expl.evaluate(metrics=["sparsity"], local=True)
+)  # sparsity over the node's k-hop subgraph
+show(expl, show_labels=True)  # highlight the explanatory subgraph
 ```
 
 ## Sparsity tuning notes
@@ -269,9 +283,15 @@ meaningless metrics are marked as `skipped`/`None` without aborting the rest:
 ```python
 from graph_explain import compare, report_html
 
-results = compare(data, model, node=42, methods=None,   # None = all
-                  num_perturbations=5, epochs=200)
-report_html(results, "bench.html")                      # self-contained HTML report
+results = compare(
+    data,
+    model,
+    node=42,
+    methods=None,  # None = all
+    num_perturbations=5,
+    epochs=200,
+)
+report_html(results, "bench.html")  # self-contained HTML report
 ```
 
 The CLI ships an equivalent subcommand:
@@ -307,7 +327,9 @@ In Python:
 from graph_explain import Explainer, evaluate_gea_graph
 from graph_explain.benchmarks.synthetic import build_graph_classification
 
-graphs = build_graph_classification(num_pos=8, num_neg=8, seed=0)  # binary y, gt_edge_mask
+graphs = build_graph_classification(
+    num_pos=8, num_neg=8, seed=0
+)  # binary y, gt_edge_mask
 model = ...  # GraphGCN (task_level="graph")
 
 expl = Explainer(algorithm=GradXInput()).explain_graph(graphs[0], model)
@@ -320,19 +342,9 @@ Node-only methods (`GraphLIME`, `NodeMask`, `Attention`, `GNNGatedLRP`,
 
 ## Roadmap
 
-- [x] Phase 2: PGExplainer, SubgraphX, Integrated Gradients
-- [x] Phase 2: interactive visualization (pyvis → HTML)
-- [x] Phase 3: full metrics (fidelity±, stability, GEA)
-- [x] Phase 3: DGL backend (adapter; integration validated with DGL 2.1 + torch 2.2.1)
-- [x] Phase 4: GNN-LRP (layer-wise relevance for GCNs; validates the house motif in BA-Shapes)
-- [x] Phase 4: counterfactual explanations (minimal edge/feature removal that changes the class)
-- [x] Phase 4: LLM narration (`describe` deterministic + pluggable `narrate` LLM)
-- [x] Phase 5: full CLI (all methods, metrics, narration and JSON export)
-- [x] Phase 6: more methods (DeepLIFT rescale, Attention/GAT, Gradient×Input)
-- [x] Phase 7: comparative benchmark (`compare` + CLI `bench` subcommand, table and JSON/HTML reports)
-- [x] Phase 8: more methods (GraphLIME, NodeMask, GuidedBackprop and Random baseline)
-- [x] Phase 10: graph-level explanations (graph-classification dataset with house
-  motif, graph-level GEA, CLI/bench without `--node` and `graph_level` flag)
+Planned ideas (real-world Datasets, more methods, robustness metrics) are
+tracked as issues in the repository — see
+https://github.com/Tzinny-dev/graph-explain/issues
 
 ## License
 

{graph_explain-0.7.2 → graph_explain-0.8.0}/README.md

@@ -1,5 +1,13 @@
 # graph-explain
 
+[![CI](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml/badge.svg)](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml)
+[![docs](https://github.com/Tzinny-dev/graph-explain/actions/workflows/docs.yml/badge.svg)](https://tzinny-dev.github.io/graph-explain/)
+[![coverage](https://tzinny-dev.github.io/graph-explain/_static/badges/coverage.svg)](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml)
+[![mypy](https://img.shields.io/badge/mypy-checked-blue)](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/graph-explain.svg)](https://pypi.org/project/graph-explain/)
+[![Python](https://img.shields.io/pypi/pyversions/graph-explain.svg)](https://pypi.org/project/graph-explain/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Tzinny-dev/graph-explain/blob/main/LICENSE)
+
 Explainability library for graph-based models (Graph Neural Networks).
 Explains a GNN's predictions in terms of **important nodes, edges and subgraphs**,
 with built-in metrics and visualization.
@@ -68,6 +76,9 @@ pip install -e .[all]
 Optional extras: `pyg` (PyTorch Geometric), `dgl` (DGL backend),
 `interactive` (plotly/pyvis).
 
+> 📚 **Documentation**: full API reference and guides at
+> https://tzinny-dev.github.io/graph-explain/
+
 ## Quick start
 
 ```python
@@ -75,16 +86,18 @@ from graph_explain import Explainer, GNNExplainer, Saliency
 from graph_explain.benchmarks.synthetic import build_data
 from graph_explain.visualization import show
 
-data = build_data(base_nodes=300, num_houses=80)   # BA-Shapes with ground truth
-model = GCN(in_channels=data.x.size(1))            # your trained GNN
+data = build_data(base_nodes=300, num_houses=80)  # BA-Shapes with ground truth
+model = GCN(in_channels=data.x.size(1))  # your trained GNN
 model.eval()
 
 explainer = Explainer(algorithm=GNNExplainer(epochs=150))
 expl = explainer.explain_node(data, model, node_idx=42)
 
 print(expl.evaluate(metrics=["fidelity", "sparsity"]))
-print(expl.evaluate(metrics=["sparsity"], local=True))  # sparsity over the node's k-hop subgraph
-show(expl, show_labels=True)                       # highlight the explanatory subgraph
+print(
+    expl.evaluate(metrics=["sparsity"], local=True)
+)  # sparsity over the node's k-hop subgraph
+show(expl, show_labels=True)  # highlight the explanatory subgraph
 ```
 
 ## Sparsity tuning notes
@@ -217,9 +230,15 @@ meaningless metrics are marked as `skipped`/`None` without aborting the rest:
 ```python
 from graph_explain import compare, report_html
 
-results = compare(data, model, node=42, methods=None,   # None = all
-                  num_perturbations=5, epochs=200)
-report_html(results, "bench.html")                      # self-contained HTML report
+results = compare(
+    data,
+    model,
+    node=42,
+    methods=None,  # None = all
+    num_perturbations=5,
+    epochs=200,
+)
+report_html(results, "bench.html")  # self-contained HTML report
 ```
 
 The CLI ships an equivalent subcommand:
@@ -255,7 +274,9 @@ In Python:
 from graph_explain import Explainer, evaluate_gea_graph
 from graph_explain.benchmarks.synthetic import build_graph_classification
 
-graphs = build_graph_classification(num_pos=8, num_neg=8, seed=0)  # binary y, gt_edge_mask
+graphs = build_graph_classification(
+    num_pos=8, num_neg=8, seed=0
+)  # binary y, gt_edge_mask
 model = ...  # GraphGCN (task_level="graph")
 
 expl = Explainer(algorithm=GradXInput()).explain_graph(graphs[0], model)
@@ -268,20 +289,10 @@ Node-only methods (`GraphLIME`, `NodeMask`, `Attention`, `GNNGatedLRP`,
 
 ## Roadmap
 
-- [x] Phase 2: PGExplainer, SubgraphX, Integrated Gradients
-- [x] Phase 2: interactive visualization (pyvis → HTML)
-- [x] Phase 3: full metrics (fidelity±, stability, GEA)
-- [x] Phase 3: DGL backend (adapter; integration validated with DGL 2.1 + torch 2.2.1)
-- [x] Phase 4: GNN-LRP (layer-wise relevance for GCNs; validates the house motif in BA-Shapes)
-- [x] Phase 4: counterfactual explanations (minimal edge/feature removal that changes the class)
-- [x] Phase 4: LLM narration (`describe` deterministic + pluggable `narrate` LLM)
-- [x] Phase 5: full CLI (all methods, metrics, narration and JSON export)
-- [x] Phase 6: more methods (DeepLIFT rescale, Attention/GAT, Gradient×Input)
-- [x] Phase 7: comparative benchmark (`compare` + CLI `bench` subcommand, table and JSON/HTML reports)
-- [x] Phase 8: more methods (GraphLIME, NodeMask, GuidedBackprop and Random baseline)
-- [x] Phase 10: graph-level explanations (graph-classification dataset with house
-  motif, graph-level GEA, CLI/bench without `--node` and `graph_level` flag)
+Planned ideas (real-world Datasets, more methods, robustness metrics) are
+tracked as issues in the repository — see
+https://github.com/Tzinny-dev/graph-explain/issues
 
 ## License
 
-MIT
+MIT

{graph_explain-0.7.2 → graph_explain-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graph-explain"
-version = "0.7.2"
+version = "0.8.0"
 description = "Explainability library for graph-based models (GNN)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -41,14 +41,14 @@ dependencies = [
 [project.urls]
 Homepage = "https://github.com/Tzinny-dev/graph-explain"
 Repository = "https://github.com/Tzinny-dev/graph-explain"
-Documentation = "https://github.com/Tzinny-dev/graph-explain#readme"
+Documentation = "https://tzinny-dev.github.io/graph-explain/"
 
 [project.optional-dependencies]
 pyg = ["torch>=2.0", "torch-geometric>=2.5"]
 dgl = ["torch>=2.0", "dgl>=2.0"]
 interactive = ["plotly>=5.15", "pyvis>=0.3"]
 all = ["torch>=2.0", "torch-geometric>=2.5", "dgl>=2.0", "plotly>=5.15", "pyvis>=0.3"]
-dev = ["pytest>=7.0", "ruff>=0.5", "build>=1.0"]
+dev = ["pytest>=7.0", "pytest-cov>=5.0", "ruff>=0.5", "build>=1.0"]
 docs = ["sphinx>=7.2", "sphinx-rtd-theme>=2.0"]
 publish = ["twine>=5.0"]
 
@@ -61,9 +61,38 @@ where = ["src"]
 [tool.setuptools.package-data]
 graph_explain = ["py.typed"]
 
+[tool.mypy]
+mypy_path = "src"
+files = ["src/graph_explain"]
+ignore_missing_imports = true
+check_untyped_defs = true
+warn_unused_ignores = false
+exclude = ["build/", "docs/"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# Coverage runs in the dedicated `coverage` CI job (see .github/workflows/ci.yml).
+# Locally: `python -m pytest --cov=graph_explain` picks up this config.
+[tool.coverage.run]
+branch = true
+source = ["graph_explain"]
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+precision = 0
+exclude_also = [
+  "if TYPE_CHECKING:",
+  'if __name__ == "__main__":',
+  'except ImportError:',
+  'raise NotImplementedError',
+]
+[tool.coverage.json]
+pretty_print = false
+[tool.coverage.html]
+directory = "docs/_build/coverage"
+[tool.coverage.paths]
+source = ["src/graph_explain/", "*/site-packages/graph_explain/"]
 
 [tool.ruff]
 line-length = 88
-target-version = "py310"
+target-version = "py310"

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/__init__.py

@@ -35,7 +35,7 @@ from .methods import (
 from .narration import Narrator, describe, narrate, summarize
 from .visualization import show, visualize_interactive, visualize_static
 
-__version__ = "0.7.2"
+__version__ = "0.8.0"
 
 __all__ = [
     "AttentionExplainer",

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/benchmarks/synthetic.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import networkx as nx
 import numpy as np
 import torch
+from numpy.typing import NDArray
 
 
 def _house_motif(offset: int, anchor_in_motif: int = 3):
@@ -56,23 +57,23 @@ def ba_shapes(
     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)
+        x_np = 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
-        )
+        x_np = np.zeros((node_count, feat_dim), dtype=np.float32)
+        x_np[
+            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)
+    x = torch.from_numpy(x_np)
 
     house_anchors = torch.from_numpy(anchors)
 
-    perm = rng.permutation(node_count)
+    perm: NDArray[np.integer] = 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)

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/core/benchmark.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import Any
+
 import torch
 
 from ..narration import summarize
@@ -105,7 +107,7 @@ def compare(
 
     for name in methods:
         cls = get_algorithm(name)
-        entry = {
+        entry: dict[str, Any] = {
             "method": name,
             "class": cls.__name__,
             "node": node,
@@ -172,6 +174,7 @@ def compare(
             lambda expl=expl_arg: float(evaluate_sparsity(expl, local=True))
         )
         if stability:
+            assert node is not None  # stability is disabled for graph-level
 
             def _again(d, name=name):
                 algo_r = instantiate(name, **_method_kwargs(epochs, lr, seed, top_k))

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/core/evaluation.py

@@ -322,7 +322,7 @@ def _local_scope(explanation, hops: int) -> tuple[list[int], list[int]]:
         edge_index = explanation.metadata.get("edge_index")
         num_nodes = num_nodes or explanation.metadata.get("num_nodes")
     if edge_index is None or num_nodes is None:
-        return None, None
+        return [], []
     node_idx = int(explanation.node_idx)
     visited = {node_idx}
     frontier = {node_idx}

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/core/explanation.py

@@ -42,7 +42,7 @@ class Explanation:
             raise ValueError(
                 "La explicación se creó sin backend/backing_data en metadata"
             )
-        G = nx.Graph()
+        G: nx.Graph = nx.Graph()
         keep_edges = []
         if self.edge_importance is not None:
             edge_index = backend.edge_index(data)

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/core/registry.py

@@ -4,11 +4,13 @@ import inspect
 from collections.abc import Callable
 from typing import Any
 
-_ALGORITHMS: dict[str, type] = {}
+from ..methods.base import ExplanationAlgorithm
+
+_ALGORITHMS: dict[str, type[ExplanationAlgorithm]] = {}
 _ALIASES: dict[str, str] = {}
 
 
-def _accepted_params(cls: type) -> set[str]:
+def _accepted_params(cls: type[ExplanationAlgorithm]) -> set[str]:
     try:
         sig = inspect.signature(cls.__init__)
     except (TypeError, ValueError):
@@ -23,7 +25,7 @@ def _accepted_params(cls: type) -> set[str]:
 
 
 def register(name: str, *aliases: str) -> Callable[[type], type]:
-    def decorator(cls: type) -> type:
+    def decorator(cls: type[ExplanationAlgorithm]) -> type[ExplanationAlgorithm]:
         _ALGORITHMS[name] = cls
         for alias in aliases:
             _ALIASES[alias] = name
@@ -33,7 +35,7 @@ def register(name: str, *aliases: str) -> Callable[[type], type]:
     return decorator
 
 
-def get_algorithm(name: str) -> type:
+def get_algorithm(name: str) -> type[ExplanationAlgorithm]:
     registered = _ALGORITHMS.get(name) or _ALGORITHMS.get(_ALIASES.get(name, ""))
     if registered is None:
         from ..methods import _available_methods

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/methods/attention/attention.py

@@ -114,7 +114,7 @@ class AttentionExplainer(ExplanationAlgorithm):
             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,
+            node_idx=int(nodes[0]) if nodes.shape[0] == 1 else None,
             target_class=target_cls,
         )
 

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/methods/base.py

@@ -3,8 +3,6 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import Any
 
-import torch
-
 
 class ExplanationAlgorithm(ABC):
     name = "base"
@@ -16,7 +14,7 @@ class ExplanationAlgorithm(ABC):
         backend: Any,
         model: Any,
         data: Any,
-        index: int | list[int] | torch.Tensor,
+        index: Any = None,
         target_class: int | None = None,
         **kwargs,
     ) -> Any: ...

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/methods/gradient/grad_x_input.py

@@ -96,7 +96,7 @@ class GradXInput(ExplanationAlgorithm):
             ),
             prediction_original=logits[nodes[0]].detach().cpu(),
             prediction_explanation=None,
-            node_idx=int(nodes[0]) if nodes.shape[0] == 1 else index,
+            node_idx=int(nodes[0]) if nodes.shape[0] == 1 else None,
             target_class=target_cls,
         )
 

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/methods/gradient/guided_backprop.py

@@ -54,7 +54,8 @@ class GuidedBackprop(ExplanationAlgorithm):
         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
+        guided = False
+        hooks: list[torch.utils.hooks.RemovableHandle] = []
         if relus and self.fallback_to_gradient:
             guided = True
             for module in relus:

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/methods/gradient/integrated_gradients.py

@@ -29,7 +29,7 @@ class IntegratedGradients(ExplanationAlgorithm):
         backend: Any,
         model: Any,
         data: Any,
-        index: int | list[int] | torch.Tensor,
+        index: int | torch.Tensor | None = None,
         target_class: int | None = None,
         **kwargs,
     ) -> Explanation:
@@ -94,7 +94,7 @@ class IntegratedGradients(ExplanationAlgorithm):
             feature_importance=feature_importance.cpu(),
             prediction_original=logits[idx[0]].detach().reshape(1, -1).cpu(),
             prediction_explanation=None,
-            node_idx=int(idx[0].item()) if isinstance(index, int) else index,
+            node_idx=int(idx[0].item()) if isinstance(index, int) else None,
             target_class=target_class,
         )
 

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/methods/gradient/saliency.py

@@ -28,7 +28,7 @@ class Saliency(ExplanationAlgorithm):
         backend: Any,
         model: Any,
         data: Any,
-        index: int | list[int] | torch.Tensor,
+        index: int | torch.Tensor | None = None,
         target_class: int | None = None,
         **kwargs,
     ) -> Explanation:
@@ -88,6 +88,10 @@ class Saliency(ExplanationAlgorithm):
             edge_importance=None,
             prediction_original=prediction_original.cpu(),
             prediction_explanation=None,
-            node_idx=int(idx[0].item()) if isinstance(index, int) else index,
+            node_idx=(
+                int(idx[0].item())
+                if isinstance(index, int)
+                else (None if index is None else int(index[0]))
+            ),
             target_class=target_class,
         )

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/methods/perturbation/gnn_explainer.py

@@ -38,7 +38,7 @@ class GNNExplainer(ExplanationAlgorithm):
         backend: Any,
         model: Any,
         data: Any,
-        index: int | torch.Tensor,
+        index: int | torch.Tensor | None = None,
         target_class: int | None = None,
         **kwargs,
     ) -> Explanation:
@@ -148,15 +148,22 @@ class GNNExplainer(ExplanationAlgorithm):
         node_full = self._scatter_node(node_mask, sub_nodes, full_num_nodes)
         edge_full = self._scatter_edge(edge_mask, sub_edge_mask, full_edge_count)
 
+        node_idx = None
+        if index is not None:
+            if torch.is_tensor(index):
+                node_idx = int(index[0])
+            elif isinstance(index, int):
+                node_idx = int(index)
+            else:
+                node_idx = int(index[0])
+
         return Explanation(
             node_importance=node_full,
             edge_importance=edge_full,
             feature_importance=None,
             prediction_original=pred_orig.cpu(),
             prediction_explanation=pred_masked.cpu(),
-            node_idx=None
-            if sub_graph_level
-            else (int(index[0]) if torch.is_tensor(index) else int(index)),
+            node_idx=node_idx,
             target_class=target_class,
             metadata={
                 "sub_nodes": sub_nodes,

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/methods/perturbation/pg_explainer.py

@@ -53,7 +53,7 @@ class PGExplainer(ExplanationAlgorithm):
         backend: Any,
         model: Any,
         data: Any,
-        index: int | torch.Tensor | None,
+        index: int | torch.Tensor | None = None,
         target_class: int | None = None,
         **kwargs,
     ) -> Explanation:

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/methods/perturbation/subgraphx.py

@@ -52,7 +52,7 @@ class SubgraphX(ExplanationAlgorithm):
         backend: Any,
         model: Any,
         data: Any,
-        index: int | torch.Tensor | None,
+        index: int | torch.Tensor | None = None,
         target_class: int | None = None,
         **kwargs,
     ) -> Explanation:
@@ -370,7 +370,7 @@ class SubgraphX(ExplanationAlgorithm):
         sel = set(selected)
         seen = set()
         comps = 0
-        adj = {}
+        adj: dict[int, set[int]] = {}
         src = edge_index[0].tolist()
         dst = edge_index[1].tolist()
         for u, v in zip(src, dst):

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/methods/relevance/deeplift.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, cast
 
 import torch
 from torch import nn
@@ -117,7 +117,7 @@ class DeepLift(ExplanationAlgorithm):
             ),
             prediction_original=logits[nodes[0]].detach().cpu(),
             prediction_explanation=None,
-            node_idx=int(nodes[0]) if nodes.shape[0] == 1 else index,
+            node_idx=int(nodes[0]) if nodes.shape[0] == 1 else None,
             target_class=target_cls,
         )
 
@@ -242,7 +242,7 @@ class DeepLift(ExplanationAlgorithm):
                 else torch.ones(ei.size(1), device=x.device)
             )
         src, dst = ei[0], ei[1]
-        W = conv.lin.weight  # (out, in)
+        W = cast(Any, conv.lin).weight  # (out, in)
 
         mul_agg = mul @ W  # (N, F_in)
 

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain/methods/relevance/gnn_lrp.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, cast
 
 import torch
 from torch import nn
@@ -127,7 +127,7 @@ class GNNGatedLRP(ExplanationAlgorithm):
             ),
             prediction_original=logits[nodes[0]].detach().cpu(),
             prediction_explanation=None,
-            node_idx=int(nodes[0]) if nodes.shape[0] == 1 else index,
+            node_idx=int(nodes[0]) if nodes.shape[0] == 1 else None,
             target_class=target_cls,
         )
 
@@ -210,7 +210,7 @@ class GNNGatedLRP(ExplanationAlgorithm):
         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)
+        r_agg = self._linear_lrp(cast(Any, 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,)

{graph_explain-0.7.2 → graph_explain-0.8.0/src/graph_explain.egg-info}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: graph-explain
-Version: 0.7.2
+Version: 0.8.0
 Summary: Explainability library for graph-based models (GNN)
 Author: graph-explain contributors
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Tzinny-dev/graph-explain
 Project-URL: Repository, https://github.com/Tzinny-dev/graph-explain
-Project-URL: Documentation, https://github.com/Tzinny-dev/graph-explain#readme
+Project-URL: Documentation, https://tzinny-dev.github.io/graph-explain/
 Keywords: gnn,explainability,xai,graph,neural-networks,interpretability
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
@@ -41,6 +41,7 @@ Requires-Dist: plotly>=5.15; extra == "all"
 Requires-Dist: pyvis>=0.3; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
 Provides-Extra: docs
@@ -52,6 +53,14 @@ Dynamic: license-file
 
 # graph-explain
 
+[![CI](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml/badge.svg)](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml)
+[![docs](https://github.com/Tzinny-dev/graph-explain/actions/workflows/docs.yml/badge.svg)](https://tzinny-dev.github.io/graph-explain/)
+[![coverage](https://tzinny-dev.github.io/graph-explain/_static/badges/coverage.svg)](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml)
+[![mypy](https://img.shields.io/badge/mypy-checked-blue)](https://github.com/Tzinny-dev/graph-explain/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/graph-explain.svg)](https://pypi.org/project/graph-explain/)
+[![Python](https://img.shields.io/pypi/pyversions/graph-explain.svg)](https://pypi.org/project/graph-explain/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Tzinny-dev/graph-explain/blob/main/LICENSE)
+
 Explainability library for graph-based models (Graph Neural Networks).
 Explains a GNN's predictions in terms of **important nodes, edges and subgraphs**,
 with built-in metrics and visualization.
@@ -120,6 +129,9 @@ pip install -e .[all]
 Optional extras: `pyg` (PyTorch Geometric), `dgl` (DGL backend),
 `interactive` (plotly/pyvis).
 
+> 📚 **Documentation**: full API reference and guides at
+> https://tzinny-dev.github.io/graph-explain/
+
 ## Quick start
 
 ```python
@@ -127,16 +139,18 @@ from graph_explain import Explainer, GNNExplainer, Saliency
 from graph_explain.benchmarks.synthetic import build_data
 from graph_explain.visualization import show
 
-data = build_data(base_nodes=300, num_houses=80)   # BA-Shapes with ground truth
-model = GCN(in_channels=data.x.size(1))            # your trained GNN
+data = build_data(base_nodes=300, num_houses=80)  # BA-Shapes with ground truth
+model = GCN(in_channels=data.x.size(1))  # your trained GNN
 model.eval()
 
 explainer = Explainer(algorithm=GNNExplainer(epochs=150))
 expl = explainer.explain_node(data, model, node_idx=42)
 
 print(expl.evaluate(metrics=["fidelity", "sparsity"]))
-print(expl.evaluate(metrics=["sparsity"], local=True))  # sparsity over the node's k-hop subgraph
-show(expl, show_labels=True)                       # highlight the explanatory subgraph
+print(
+    expl.evaluate(metrics=["sparsity"], local=True)
+)  # sparsity over the node's k-hop subgraph
+show(expl, show_labels=True)  # highlight the explanatory subgraph
 ```
 
 ## Sparsity tuning notes
@@ -269,9 +283,15 @@ meaningless metrics are marked as `skipped`/`None` without aborting the rest:
 ```python
 from graph_explain import compare, report_html
 
-results = compare(data, model, node=42, methods=None,   # None = all
-                  num_perturbations=5, epochs=200)
-report_html(results, "bench.html")                      # self-contained HTML report
+results = compare(
+    data,
+    model,
+    node=42,
+    methods=None,  # None = all
+    num_perturbations=5,
+    epochs=200,
+)
+report_html(results, "bench.html")  # self-contained HTML report
 ```
 
 The CLI ships an equivalent subcommand:
@@ -307,7 +327,9 @@ In Python:
 from graph_explain import Explainer, evaluate_gea_graph
 from graph_explain.benchmarks.synthetic import build_graph_classification
 
-graphs = build_graph_classification(num_pos=8, num_neg=8, seed=0)  # binary y, gt_edge_mask
+graphs = build_graph_classification(
+    num_pos=8, num_neg=8, seed=0
+)  # binary y, gt_edge_mask
 model = ...  # GraphGCN (task_level="graph")
 
 expl = Explainer(algorithm=GradXInput()).explain_graph(graphs[0], model)
@@ -320,19 +342,9 @@ Node-only methods (`GraphLIME`, `NodeMask`, `Attention`, `GNNGatedLRP`,
 
 ## Roadmap
 
-- [x] Phase 2: PGExplainer, SubgraphX, Integrated Gradients
-- [x] Phase 2: interactive visualization (pyvis → HTML)
-- [x] Phase 3: full metrics (fidelity±, stability, GEA)
-- [x] Phase 3: DGL backend (adapter; integration validated with DGL 2.1 + torch 2.2.1)
-- [x] Phase 4: GNN-LRP (layer-wise relevance for GCNs; validates the house motif in BA-Shapes)
-- [x] Phase 4: counterfactual explanations (minimal edge/feature removal that changes the class)
-- [x] Phase 4: LLM narration (`describe` deterministic + pluggable `narrate` LLM)
-- [x] Phase 5: full CLI (all methods, metrics, narration and JSON export)
-- [x] Phase 6: more methods (DeepLIFT rescale, Attention/GAT, Gradient×Input)
-- [x] Phase 7: comparative benchmark (`compare` + CLI `bench` subcommand, table and JSON/HTML reports)
-- [x] Phase 8: more methods (GraphLIME, NodeMask, GuidedBackprop and Random baseline)
-- [x] Phase 10: graph-level explanations (graph-classification dataset with house
-  motif, graph-level GEA, CLI/bench without `--node` and `graph_level` flag)
+Planned ideas (real-world Datasets, more methods, robustness metrics) are
+tracked as issues in the repository — see
+https://github.com/Tzinny-dev/graph-explain/issues
 
 ## License
 

{graph_explain-0.7.2 → graph_explain-0.8.0}/src/graph_explain.egg-info/requires.txt

@@ -12,6 +12,7 @@ pyvis>=0.3
 
 [dev]
 pytest>=7.0
+pytest-cov>=5.0
 ruff>=0.5
 build>=1.0