GraphToolbox: A Configurable Python Framework for Graph Neural Network Forecasting

Unifying graph construction, model selection, training, aggregation, and interpretability in a single PyTorch Geometric pipeline

Eloi Campagne; Yvenn Amara-Ouali; Yannig Goude; Argyris Kalogeratos· 2026· DOI 10.48550/arXiv.2609.24609

The core problem

Electricity forecasting frequently involves spatially related signals observed across regions, substations, and feeders. Graph Neural Networks (GNNs) offer a natural representation for these relations, but building a complete GNN forecasting experiment is laborious because graph construction, model selection, training, aggregation, and interpretation are typically handled by incompatible tools. The authors present **GraphToolbox**, an open-source Python framework that unifies these stages in one configuration-driven pipeline built on PyTorch Geometric. The framework addresses the fragmentation of the GNN experimentation workflow by providing a single interface for data-driven graph construction, model instantiation, training, online expert aggregation, forecasting interpretability, and significance testing on cached forecasts. The paper evaluates the pipeline in two case studies: French regional load and net-load forecasting.

On French regional load, the 48 convolutions included in the complete forecasting sweep fall in a band from 1.14% to 1.60% error. Online aggregation lowers this to 0.98%. The graph models improve on classical additive and boosting baselines. On net-load, direct graph models are less accurate than a classical additive model. Forecasting each physical component separately improves the graph models but does not close the gap to the additive model. Both comparisons use the same experimental interface, illustrating the role of GraphToolbox in systematic architectural evaluation. The error metrics are likely reported as MAPE or similar; the exact metric is not specified in the abstract. The results highlight that while GNNs can be effective for regional load, their advantage is not universal, and component-wise forecasting may be beneficial for net-load.

Electricity forecasting frequently involves spatially related signals observed across regions, substations, and feeders. Graph Neural Networks (GNNs) offer a natural representation for these relations, but building a complete GNN forecasting experiment is laborious because graph construction, model selection, training, aggregation, and interpretation are typically handled by incompatible tools. The authors present **GraphToolbox**, an open-source Python framework that unifies these stages in one configuration-driven pipeline built on PyTorch Geometric. The framework addresses the fragmentation of the GNN experimentation workflow by providing a single interface for data-driven graph construction, model instantiation, training, online expert aggregation, forecasting interpretability, and significance testing on cached forecasts. The paper evaluates the pipeline in two case studies: French regional load and net-load forecasting.

GraphToolbox is built on PyTorch Geometric and PyTorch Geometric Temporal. Its core components include:

The two case studies demonstrate the utility of GraphToolbox for systematic evaluation of GNN architectures in electricity forecasting. The framework's ability to instantiate a large number of convolutions (51 out of 65) and combine them with recurrent cells enables comprehensive benchmarking. The online expert aggregation component proves valuable, reducing error from the best individual model's 1.14% to 0.98% on regional load. The net-load case reveals that direct graph models may underperform classical additive models, but decomposing the problem into physical components can improve GNN performance. This suggests that the choice of graph representation and target variable is crucial. The interpretability and significance testing tools allow researchers to understand model behavior and validate improvements. GraphToolbox addresses a key gap in the GNN forecasting ecosystem by providing an integrated, configurable pipeline. Future work could extend the framework to other domains and incorporate more advanced aggregation techniques. The framework is open-source and built on widely used libraries, facilitating adoption and reproducibility.

CS practitioners and researchers

Opening member content…