A comprehensive visualization library for Graph Neural Networks (GNNs) that enables interactive exploration and explanation of GNN models directly in computational notebooks. This library provides multiple visualization widgets for understanding graph structures, model architectures, and intermediate feature representations.
We have published the public version to Python Package Index, use
pip install gnn-expto install the package.
This repository is configured for PyPI Trusted Publishing with GitHub Actions. Publishing is handled by .github/workflows/publish-pypi.yml, which builds the frontend assets, creates the Python distributions, and uploads them to PyPI through GitHub OIDC.
To finish the one-time PyPI setup, add a Trusted Publisher for:
- PyPI project:
gnn-exp - GitHub owner:
HarryLuUMN - GitHub repository:
gnn-exp - Workflow name:
Publish Python Package - Environment name:
pypi
After that, publishing can be triggered either by creating a GitHub Release or by manually running the workflow from the Actions tab.
- Visualize graphs with both node-link and matrix views
- Support for large graphs with subgraph extraction
- Hoop-based subgraph sampling for focused visualization
- Interactive exploration of graph structures
- Edit graph structures directly in the notebook
- Add, remove, and modify nodes and edges
- Export edited graphs to JSON format
- Real-time visualization updates
- Visualize intermediate layer features and activations
- Matrix view of feature transformations across layers
- Support for multiple GNN tasks:
- Node Classification: Visualize node-level predictions
- Edge Prediction: Visualize link prediction tasks
- Graph Classification: Visualize graph-level tasks
- Interactive layer expansion to explore inner computations
- Subgraph-based feature visualization for large graphs
Clone the repository and install in development mode:
git clone https://github.com/HarryLuUMN/gnn-exp.git
cd gnn-expWe recommend using uv for development, which automatically manages virtual environments and dependencies:
# Install Python dependencies
uv sync
# Run example notebook
uv run jupyter lab example.ipynbAlternatively, use a traditional virtual environment:
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
jupyter lab example.ipynbThe widget front-end code bundles JavaScript dependencies. After setting up Python, install JavaScript dependencies:
npm installFor development with hot-reloading, run in a separate terminal:
npm run devThis will automatically rebuild JavaScript as you make changes to files in js/.
from gnn_explorer import GraphVisualizer
# Create a visualizer instance
w = GraphVisualizer()
w.add_data(dataFile="test_data/karate_dataset.json")
w # Display in notebook# Single hub node subgraph extraction
w = GraphVisualizer()
w.add_data(dataFile="test_data/twitch.json")
w.subgraph_hoop_visualizer(hubNode=0, hoopNum=3)
w
# Multiple hub nodes
w = GraphVisualizer()
w.add_data(dataFile="test_data/twitch.json")
w.multiple_subgraph_hoop_visualizer(hubNodes=[0, 1], hoopNum=1)
wfrom gnn_explorer import GraphEditor
editor = GraphEditor()
editor.add_data(dataFile="test_data/karate_dataset.json")
editor # Display editor in notebook
# Export edited graph
editor.export_data_to_json("test_data/edited_graph.json")import torch
import torch.nn as nn
from torch_geometric.nn import GCNConv
from gnn_explorer import GNNVisualizer
# Define your GNN model
class GCN(torch.nn.Module):
def __init__(self, dataset):
super().__init__()
self.conv1 = GCNConv(dataset.num_features, 4)
self.act1 = nn.Tanh()
self.conv2 = GCNConv(4, 4)
self.act2 = nn.Tanh()
self.classifier = nn.Linear(4, dataset.num_classes)
self.softmax = nn.Softmax(dim=1)
def forward(self, x, edge_index):
h = self.act1(self.conv1(x, edge_index))
h = self.act2(self.conv2(h, edge_index))
out = self.softmax(self.classifier(h))
return out
# Create model and data
model = GCN(dataset)
data = dataset[0]
# Visualize model
visualizer = GNNVisualizer()
visualizer.add_model(
data=data,
model=model,
subgraphSample=False,
forward_fn=None,
queries=[[12, 18]], # Node IDs to highlight
mode='node' # 'node', 'edge', or 'graph'
)
visualizer # Display in notebookgnn-explorer/
├── src/gnn_explorer/ # Python package
│ ├── graph_visualizer.py # Graph visualization widget
│ ├── graph_editor.py # Graph editing widget
│ ├── gnn_visualizer.py # GNN model visualization widget
│ └── static/ # Compiled JavaScript/CSS assets
├── js/ # TypeScript/React source code
│ ├── graph_visualizer/ # Graph visualization frontend
│ ├── graph_editor/ # Graph editor frontend
│ └── gnn_visualizer/ # GNN visualizer frontend
├── test_data/ # Example datasets
├── example.ipynb # Example notebook
└── README.md # This file
The JavaScript code is built using esbuild. To build once:
npm run buildTo watch for changes during development:
npm run devRun TypeScript type checking:
npm run typecheckFor development, enable hot module reloading in your notebook:
%load_ext autoreload
%autoreload 2
%env ANYWIDGET_HMR=1Changes made to files in js/ will be automatically reflected in the notebook when using npm run dev.
- Python >= 3.8
- Node.js >= 16 (for development)
- JupyterLab or Jupyter Notebook
- PyTorch Geometric (for GNN model visualization)
- GCNConv: Graph Convolutional Network layers
- Linear: Fully connected layers
- Activation Functions: ReLU, Tanh, Sigmoid, Softmax, and more
MIT License - see LICENSE file for details.
- Yilin Lu (lu000661@umn.edu)
- Qianwen Wang (qianwen@umn.edu)
- Homepage: https://github.com/HarryLuUMN/gnn-exp
- Repository: https://github.com/HarryLuUMN/gnn-exp
If you use this library in your research, please cite:
@software{gnn_explorer,
title = {GNN Explorer: Visual Exploration and Explanation of Graph Neural Networks},
author = {Lu, Yilin and Wang, Qianwen},
url = {https://pypi.org/project/gnn-exp/0.1.0/},
journal = {Python Package Index}
year = {2024}
}