GraphToolbox is a Python package designed for graph machine learning focused on time-series forecasting. It provides tools for data handling, model building, training, evaluation, and visualization.
- Data handling and preprocessing for graph datasets.
- Various graph neural network models including Graph Convolutional Networks (GCNs), GraphSAGE and Graph Attention Networks (GATs).
- Training and evaluation utilities for graph-based models.
- Visualization tools for graph data and model results.
We benchmarked the entire collection of torch_geometric.nn.conv layers against myGNN, evaluating whether each operator can be instantiated and run end-to-end with standard node-feature inputs and a homogeneous graph structure.
Legend:
- 🟢 = Working (fully compatible with
myGNN) - 🔴 = Skipped (requires the
dgNNpackage, not available on all platforms) - ⚪️ = Skipped (requires CUDA-specific dependencies or device-restricted libraries)
| Convolution Type | Status | Convolutions |
|---|---|---|
| GCN / Spectral | 🟢 | GCNConv, ChebConv, SGConv, SSGConv, LGConv, GCN2Conv, ClusterGCNConv, FAConv |
| Attention-based | 🟢 | GATConv, GATv2Conv, SuperGATConv, TransformerConv, AGNNConv, DNAConv |
| MPNN / Aggregation | 🟢 | SAGEConv, GENConv, GraphConv, MFConv, LEConv, SimpleConv, EGConv, GravNetConv |
| MLP-based (GIN-style) | 🟢 | GINConv, GINEConv |
| Edge-conditioned | 🟢 | NNConv, ECConv, CGConv, GMMConv, GeneralConv, XConv |
| Recurrent / Gated | 🟢 | GatedGraphConv, ARMAConv, TAGConv |
| Residual / Deep | 🟢 | DirGNNConv, AntiSymmetricConv, FiLMConv, ResGatedGraphConv, PDNConv |
| Spectral / Poly | 🟢 | MixHopConv, GPSConv, FeaStConv, SplineConv, PANConv |
| Dynamic aggregators | 🟢 | PNAConv, EdgeConv, DynamicEdgeConv |
| Relational | 🟢 | RGCNConv, RGATConv, FastRGCNConv |
| Graph-level | 🟢 | WLConv, SignedConv |
| Missing optional deps | 🔴 | FusedGATConv (dgNN) |
| Heterogeneous graphs | ⚪️ | HANConv, HGTConv, HEATConv, HeteroConv |
| Point-cloud | ⚪️ | PointNetConv, PointConv, PointGNNConv, PointTransformerConv, PPFConv |
| CuGraph (CUDA only) | ⚪️ | CuGraphGATConv, CuGraphRGCNConv, CuGraphSAGEConv |
| Hypergraph | ⚪️ | HypergraphConv |
Detailed statistics per status:
| Status | Count | Percentage |
|---|---|---|
| 🟢 | 51 | 78.5 % |
| 🔴 | 1 | 1.5 % |
| ⚪️ | 13 | 20.0 % |
| Total Tested | 65 | 100 % |
FusedGATConv is not broken; it requires the dgNN package which is not available on all platforms. Installing it will make it pass.
Installing torch-cluster, torch-sparse, and torch-spline-conv unlocked DynamicEdgeConv, GravNetConv, XConv, PANConv, and SplineConv.
If you spot a missing convolution, find an incompatibility, or want to help extend support, contributions are warmly welcomed! Feel free to open an issue or submit a PR so we can improve these results.
To install GraphToolbox, clone the repository and install the dependencies:
git clone git@github.com:eloicampagne/GraphToolbox.git
cd GraphToolbox
pip install .To unlock the full set of supported convolutions, install the optional PyTorch Geometric extensions that match your PyTorch and platform versions. Replace ${TORCH} and ${CUDA} with the appropriate values (e.g. 2.5.1 and cpu):
pip install torch-scatter torch-sparse torch-cluster torch-spline-conv \
-f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.htmlWithout these packages, DynamicEdgeConv, GravNetConv, XConv, PANConv, and SplineConv are unavailable. FusedGATConv additionally requires dgNN, which is not available on all platforms.
Here is a basic example of how to use GraphToolbox:
from graphtoolbox.data.dataset import *
from graphtoolbox.training.trainer import Trainer
from graphtoolbox.utils.helper_functions import *
from torch_geometric.nn.models import *
# Load datasets
out_channels = 48
data = DataClass(path_train='./train.csv',
path_test='./test.csv',
data_kwargs=data_kwargs,
folder_config='.')
graph_dataset_train = GraphDataset(data=data, period='train',
graph_folder='../graph_representations',
dataset_kwargs=dataset_kwargs,
out_channels=out_channels)
graph_dataset_val = GraphDataset(data=data, period='val',
scalers_feat=graph_dataset_train.scalers_feat,
scalers_target=graph_dataset_train.scalers_target,
graph_folder='../graph_representations',
dataset_kwargs=dataset_kwargs,
out_channels=out_channels)
graph_dataset_test = GraphDataset(data=data, period='test',
scalers_feat=graph_dataset_train.scalers_feat,
scalers_target=graph_dataset_train.scalers_target,
graph_folder='../graph_representations',
dataset_kwargs=dataset_kwargs,
out_channels=out_channels)
# Initialize model
conv_class = GATConv
conv_kwargs = {'heads': 2}
params = {'num_layers': 3,
'hidden_channels': 364,
'lr': 1e-3,
'batch_size': 16,
'adj_matrix': 'gl3sr',
'lam_reg': 0}
model = myGNN(
in_channels=graph_dataset_train.num_node_features,
num_layers=params["num_layers"],
hidden_channels=params["hidden_channels"],
out_channels=out_channels,
conv_class=conv_class,
conv_kwargs=conv_kwargs
)
# Initialize trainer
trainer = Trainer(
model=model,
dataset_train=graph_dataset_train,
dataset_val=graph_dataset_val,
dataset_test=graph_dataset_test,
batch_size=params["batch_size"],
return_attention=False,
model_kwargs={'lr': params["lr"], 'num_epochs': 200},
lam_reg=params["lam_reg"]
)
# Train model
pred_model_test, target_test, edge_index, attention_weights = trainer.train(
plot_loss=True,
force_training=True,
save=False,
patience=75
)
# Evaluate model
trainer.evaluate()Contributions are welcome! Please fork the repository and submit a pull request.
Special thanks to all contributors of the GraphToolbox project:
- Eloi Campagne
- Itai Zehavi
If you use the GraphToolbox in your work, please cite the corresponding paper:
@article{campagne2025graph,
author = {Campagne, Eloi and Amara-Ouali, Yvenn and Goude, Yannig and Kalogeratos, Argyris},
title = {Graph Neural Networks for Electricity Load Forecasting},
journal={arXiv preprint arXiv:2507.03690},
year = {2025},
}This project is licensed under the GPL License - see the LICENSE file for details.