River ST-GNN Forecast: code and trained weights for river-stage forecasting in Ascension Parish, Louisiana

Abstract

River ST-GNN Forecast provides research code and trained weights for the manuscript "An operational river-stage forecasting system using spatiotemporal graph neural network (ST-GNN) in Ascension Parish, Louisiana", prepared for submission to Hydrology and Earth System Sciences (HESS). The software compares a spatiotemporal graph neural network (ST-GNN), a GRU with identity adjacency, and a nodewise LSTM in a managed, low-gradient drainage network. The models use 72 hours of historical observations to forecast river stage over the next 24 hours at 15-minute intervals across 68 gauges, including 51 scored in-parish gauges and 17 supporting boundary gauges. This GitHub-synced v1.0.0 release contains data preparation and feature construction, graph construction, chronological training, inference, rainfall-forcing preparation, operational postprocessing, evaluation, and the original figure and table recipes. It also includes trained checkpoints, node order, normalization statistics, training histories, model lineage and checksums; configuration files; environment requirements; reproduction instructions; and development scripts retained for provenance. The code and weights are distributed under the Apache License 2.0. The study selects training duration and graph configuration using 2023-2024 training data and chronological validation in 2025. Final models are reinitialized and fitted to eligible pre-2026 data, then held fixed for evaluation at 5,832 hourly forecast origins from January to August 2026. The three training seeds are 101, 202 and 303. The 927 event-only origins are defined by parish pump operation at issue time. Hindcasts use observed future rainfall with postprocessing off; simulated operational forecasts use archived issue-time HRRR rainfall with continuity blending, stale-data handling, and rainfall-dependent rise caps. A standalone Python script reproduces the paired uncertainty analysis from the companion evaluation data using NumPy, with 10,000 paired resampling replicates over gauges and 72-hour blocks. The original training and inference workflow requires the documented input-data layout and dependencies. The complete raw training matrix, private Parish HEC-RAS terrain and mesh files, operational credentials, server addresses, and the Parish operational rainfall downloader are not distributed. The supplied checkpoints depend on Ascension Parish gauge order, graphs and normalization statistics; application to another watershed requires its own inputs and model fitting. Source repository: https://github.com/awesomemfg/River_ST_GNN_Forecast. Release snapshot: https://github.com/awesomemfg/River_ST_GNN_Forecast/tree/v1.0.0. Companion evaluation data and derived graphs: https://doi.org/10.5281/zenodo.23086107. The companion data support scoring and uncertainty calculations; retraining requires additional original telemetry and meteorological inputs.