GraphToolbox

Graph neural network forecasting, one configuration at a time

GraphToolbox is a Python framework on PyTorch Geometric for forecasting time series observed on the nodes of a graph, such as regional electricity load. One configuration-driven pipeline covers graph construction, the choice among the convolution operators of PyTorch Geometric, training, reconciliation, expert aggregation, significance testing and interpretability, so that a benchmark changes one choice at a time.

How it works

GraphToolbox pipeline

Solid arrows carry data from raw series to forecasts and diagnostics. Dashed boxes are the configuration dictionaries of each stage, so that swapping the graph, the convolution or the training regime amounts to editing one field.

Features

Data and graphs

DataClass and GraphDataset build lagged, scaled node samples with train, validation and test splits. GraphBuilder derives the adjacency from coordinates or from the series (spatial distance, correlation, precision, GL3SR, dynamic time warping), any precomputed adjacency is loaded by name, and a graph can be selected on validation error.

graphtoolbox.data
Models

myGNN runs 53 of the 65 convolutions of PyTorch Geometric through one adapter, TemporalGNN the recurrent cells of PyTorch Geometric Temporal, and AdditiveGraphModel an additive graph network whose forecast splits into feature-group contributions.

graphtoolbox.models
Training

Trainer handles early stopping, forecasting metrics and MinT reconciliation, Optimizer runs Optuna searches over the model and the graph, and RollingTrainer refits on rolling windows or updates a trained model every day.

graphtoolbox.training
Reconciliation

MinT makes the node forecasts sum to a forecast of their total, fitted by the framework or supplied by the user, with a diagonal or a shrunk full error covariance.

graphtoolbox.training.reconciliation
Expert aggregation

Online aggregation (MLpol, EWA, BOA) across architectures or seeds, on the total or node by node, following the rules of the opera package.

graphtoolbox.aggregation
Evaluation

Diebold-Mariano tests with Holm correction, moving-block bootstrap and Model Confidence Set, computed on cached forecasts.

graphtoolbox.evaluation
Interpretability

Attention matched to edges, occlusion influence, accumulated local effects, and maps of edge attributions.

graphtoolbox.interpretability
Baselines

Reusable references for comparison: ARIMA-X, GAM fitted per forecast slot, an LSTM with covariates, XGBoost, Chronos-Bolt and Chronos-2.

graphtoolbox.models.baseline

Examples from the paper

The figures below come from the benchmark on French regional load and net-load of Campagne et al. (2026), run with GraphToolbox.

RMSE of the 46 operators of the load sweep

National RMSE of the 46 operators of the load sweep on the 2019 test year, with block-bootstrap standard errors. Filled markers belong to the 90% Model Confidence Set. Built with myGNN, Trainer and graphtoolbox.evaluation.

MLpol weights and cumulative RMSE over 2019

Top, daily MLpol weights of the five operators with the largest average weight. Bottom, cumulative RMSE of MLpol, the uniform average and the best single operator. Built with graphtoolbox.aggregation.Aggregation.

Experts with the largest MLpol weight in each French region

MLpol run separately in each of the 12 regions: the three experts with the largest mean weight, the heaviest in bold and as the fill colour.

Attention of GATv2 against occlusion influence on the French regions

Attention of a GATv2 on the French regions, set against the occlusion influence of each neighbour on the forecast. Built with attention_by_snapshot, occlusion_influence and neighbourhood_deviation.

Feature-group contributions to the net-load forecast

Contributions of the feature groups of an AdditiveGraphModel to the national net-load forecast during 4 to 10 February 2019. They sum to the forecast minus a constant baseline.

Installation

Clone the repository and install the package and 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}.html

Without these packages, DynamicEdgeConv, GravNetConv, XConv, PANConv, and SplineConv are unavailable. FusedGATConv additionally requires dgNN, which is not available on all platforms.

Convolutions

GraphToolbox benchmarks the entire torch_geometric.nn.conv collection 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 dgNN package, not available on all platforms)

  • ⚪ Skipped (requires CUDA-specific dependencies or device-restricted libraries)

Convolution Type

Status

Convolutions

Propagation

🟢

SimpleConv, GCNConv, ChebConv, SGConv, SSGConv, APPNP, GCN2Conv, ARMAConv, TAGConv, LGConv, ClusterGCNConv, MixHopConv, PANConv

Attention

🟢

GATConv, GATv2Conv, SuperGATConv, TransformerConv, AGNNConv, RGATConv, FAConv, DNAConv, GPSConv, PointTransformerConv

Gating and modulation

🟢

GatedGraphConv, ResGatedGraphConv, FiLMConv

Relational and edge-conditioned

🟢

RGCNConv, FastRGCNConv, NNConv, CGConv, GMMConv, SplineConv, FeaStConv, PDNConv, GINEConv

Point-cloud and dynamic graphs

🟢

EdgeConv, DynamicEdgeConv, GravNetConv, XConv

Other aggregators

🟢

SAGEConv, GraphConv, MFConv, LEConv, PNAConv, GENConv, EGConv, GINConv, GeneralConv, DirGNNConv, AntiSymmetricConv, SignedConv, WLConv, WLConvContinuous

Missing optional deps

🔴

FusedGATConv (dgNN)

Heterogeneous graphs

⚪

HANConv, HGTConv, HEATConv, HeteroConv

Point-cloud

⚪

PointNetConv, PointGNNConv, PPFConv

CuGraph (CUDA only)

⚪

CuGraphGATConv, CuGraphRGCNConv, CuGraphSAGEConv

Hypergraph

⚪

HypergraphConv

Status

Count

Percentage

🟢

53

81.5 %

🔴

1

1.5 %

⚪

11

16.9 %

Total Tested

65

100 %

Counts follow torch_geometric.nn.conv.__all__ in PyTorch Geometric 2.6.1; the aliases ECConv (NNConv) and PointConv (PointNetConv) are not counted twice.

FusedGATConv is not broken; it requires the dgNN package which is not available on all platforms. 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.

Usage

A GATv2 forecasting the next 48 half-hours of regional load on the DTW graph, reconciled with a national XGBoost forecast:

from torch_geometric.nn import GATv2Conv

from graphtoolbox.data import DataClass, GraphDataset
from graphtoolbox.models import myGNN
from graphtoolbox.training import Trainer

data_kwargs = {
    "node_var": "Region",                    # one node per region
    "features_to_lag": {"load": (1, 48)},    # load of the previous day
    "dummies": ["Instant", "JourSemaine"],   # one-hot calendar
    "day_inf_train": "2015-01-01", "day_sup_train": "2018-01-01",
    "day_inf_val": "2018-01-01", "day_sup_val": "2018-12-31",
    "day_inf_test": "2019-01-01", "day_sup_test": "2019-12-31",
}
dataset_kwargs = {
    "adj_matrix": "dtw",                     # graph read from graph_folder/dtw/
    "features_base": ["temp", "nebu", "wind", "Instant", "JourSemaine"]
                     + [f"load_l{t}" for t in range(1, 49)],
    "target_base": "load",
}
data = DataClass(path_train="train.csv", path_test="test.csv",
                 data_kwargs=data_kwargs, folder_config=".")
common = dict(data=data, dataset_kwargs=dataset_kwargs, out_channels=48,
              graph_folder="../graph_representations")
train = GraphDataset(period="train", **common)
scalers = dict(scalers_feat=train.scalers_feat, scalers_target=train.scalers_target)
val, test = (GraphDataset(period=p, **scalers, **common) for p in ("val", "test"))

model = myGNN(in_channels=train.num_node_features, num_layers=2, hidden_channels=64,
              out_channels=48, conv_class=GATv2Conv)   # any PyG convolution
trainer = Trainer(model=model, dataset_train=train, dataset_val=val, dataset_test=test,
                  batch_size=32, model_kwargs={"lr": 1e-3, "num_epochs": 300},
                  reconcile=True, top_level_model="xgb")
pred, target, edge_index, edge_weight = trainer.train(patience=30, plot_loss=False)
trainer.evaluate()

Reconciliation

MinT reconciliation makes the node forecasts sum to a forecast of their total, weighting each series by its errors on held-out data. With reconcile=True, the Trainer fits a top-level model (top_level_model="xgb", "ridge", "rf" or "gam") on the lags, the calendar and the national mean of the covariates, or takes an external forecast through top_forecasts_val and top_forecasts_test. reconcile_covariance="diag" (default) weights the series by their validation error variances; "shrink" uses their full error covariance, shrunk toward its diagonal with the Schafer-Strimmer intensity.

trainer = Trainer(model=model, dataset_train=graph_dataset_train,
                  dataset_val=graph_dataset_val, dataset_test=graph_dataset_test,
                  batch_size=16, reconcile=True, top_level_model="xgb",
                  reconcile_covariance="shrink")

Cached forecasts can be reconciled without a model:

from graphtoolbox.training.reconciliation import reconcile

# base [nodes, T] and top [T] to reconcile; their errors on a validation period.
coherent = reconcile(base, top, base_errors_val, top_errors_val, covariance="shrink")
total = coherent[-1]          # coherent forecast of the total

Expert Aggregation

The graphtoolbox.aggregation module combines several competing forecasts into a single one whose weights adapt over time, in the spirit of the opera package (Gaillard & Goude). It is useful for blending the GNN forecast with external experts such as a top-level XGBoost or GAM model, either sequentially (online) or as a static combiner fitted on a history.

The estimator consumes a matrix of expert forecasts of shape [T, K] (T time steps, K experts) and the observations [T], and exposes the full weight trajectory in weights_ (handy for interpretability) as well as the final convex weights in coefficients_ for out-of-sample reuse.

import numpy as np
from graphtoolbox.aggregation import Aggregation

# Toy example: 4 experts of increasing noise around a signal.
rng = np.random.default_rng(0)
T, K = 1000, 4
y = np.sin(np.linspace(0, 30, T)) + 0.5 * np.linspace(0, 1, T)
experts = y[:, None] + rng.normal(0, [0.1, 0.3, 0.6, 1.0], size=(T, K))

# MLpol is parameter-free and a robust default.
agg = Aggregation(model="MLpol", loss="square").run(experts, y)

print(agg.summary())          # aggregated vs best/mean expert loss
forecast = agg.prediction_    # aggregated forecast, shape [T]
weight_path = agg.weights_    # weight trajectory, shape [T, K]

# EWA and BOA take a learning rate, auto-calibrated when y is given.
ewa = Aggregation(model="EWA").run(experts, y)
print("calibrated eta:", ewa.learning_rate_)

Fit on a history and reuse the learned static weights on unseen experts:

agg = Aggregation(model="MLpol").run(experts[:800], y[:800])
future = agg.predict(experts[800:])   # applies agg.coefficients_

For a genuine streaming setting, alternate partial_fit (to obtain the forecast for the current step) and update (to feed back the observation):

agg = Aggregation(model="BOA", learning_rate=1.0).reset(n_experts=K)
preds = []
for t in range(T):
    preds.append(agg.partial_fit(experts[t]))  # forecast at time t
    agg.update(y[t])                            # reveal observation

When forecasts are served in batches rather than one step at a time, use block_size, which follows opera’s predict / update split. A day-ahead forecast delivered as daily blocks of 48 half-hours commits each block with the weights known at its start; once the block is observed the weights then advance step by step within it before the next block:

agg = Aggregation(model="MLpol").run(experts, y, block_size=48)

Available rules are "MLpol" (default, parameter-free), "EWA" and "BOA" (adaptive, learning-rate based), plus the "uniform" mean and the "best" single-expert oracle as baselines.

Baselines and interpretability

Classical forecasting baselines are reusable from graphtoolbox.models.baseline: per-slot ARIMA-X and GAM fitting, the covariate-conditioned LSTM, XGBoost, Chronos-Bolt and Chronos-2. Dataset assembly, the paper-specific formulas, and the pooled and per-node XGBoost and MLP baselines of the paper remain in examples.

graphtoolbox.interpretability exposes the attribution tools: attention_by_snapshot returns the attention of every layer and snapshot, matched to edges; occlusion_influence measures the change of a node’s forecast when the inputs of another node are replaced by a baseline; neighbourhood_deviation and sender_variance_share summarize them; additive_ale_from_dataset computes accumulated local effects through an AdditiveGraphModel; compute_edge_masks runs GNNExplainer; and plot_ale_group_importance renders grouped ALE diagnostics. The complete reproduction commands and cached output locations are listed in the reproducibility guide.

Changelog

Release notes are maintained in the project changelog.

Contributing

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

License

This project is licensed under the GPL License - see the LICENSE file for details.

Documentation

graphtoolbox

GraphToolbox: graph machine learning utilities for time-series forecasting.