Virtual-node GCRNN — pretrained checkpoints
Pretrained checkpoints for GCRNNVirtual, the virtual-node graph convolutional recurrent network proposed in:
Niko Uremović, Domen Mongus, Aleksander Pur, Niko Lukač. Contextualized spatio-temporal graph-based method for forecasting sparse geospatial sensor networks. Expert Systems with Applications, vol. 294, p. 128779, 2025.
What this model does
Sparse sensor networks (weather stations, traffic counters, air-quality monitors, ...) leave large unmeasured gaps between stations. Rather than forecasting at the observed stations and interpolating outward afterward, this model embeds virtual nodes — unobserved locations — directly into the graph and forecasts them end-to-end alongside the real stations, conditioned on contextual side-information (terrain/land-cover rasters for weather stations, road/traffic attributes for counters, settlement/emission/ vegetation features for air-quality stations).
The architecture is a multi-layer graph convolutional GRU (Chebyshev graph
convolutions) that encodes each real station's history, message-passes
learned hidden states over to virtual nodes via a second graph built for
the full (real + virtual) node set, and decodes a forecast horizon for both.
See models_impl/GConvGRU.py (GCRNNVirtual) in the code repo for the
exact implementation.
What's included
One checkpoint per k-fold split, per dataset — each trained with a subset of that dataset's nodes masked as "virtual" during training, so its virtual-node evaluation metrics reflect genuinely held-out stations/counters:
l=<layers>_k=<khops>_f=<filters>/kfold=<fold>.pt
| dataset | layers | khops | filters | folds |
|---|---|---|---|---|
| meteo | 3 | 2 | 128 | 0–8 |
| traffic | 3 | 2 | 192 | 0–9 |
| air | 3 | 2 | 64 | 0–7 |
Each .pt file is a plain torch.save(model.state_dict()) — there's no
bundled config, tokenizer, or processor; the architecture (feature counts,
history/horizon window) is fixed per dataset and defined in the
corresponding virtual_meteo.py / virtual_traffic.py / virtual_air.py
script in the code repo.
How to use
This is a plain PyTorch state_dict, not a transformers-compatible
model — loading it requires the model class and data pipeline from the code
repo:
git clone https://github.com/SAMPA-Project/contextual-gcn-sparse-uremovic
cd contextual-gcn-sparse-uremovic
pip install -e .
# download this HF repo's checkpoints into models/, and the data from
# Zenodo (10.5281/zenodo.17091212) into data/ — see DATA.md / MODELS.md
python inference_meteo.py --fold 0
inference_meteo.py / inference_traffic.py / inference_air.py load a
checkpoint, run it on that fold's test split, and report mean absolute
error overall and on the virtual (held-out) nodes only. See
MODELS.md
in the code repo for the full layout and CLI usage, and
DATA.md
for the data these models expect.
To load a checkpoint manually:
import torch
from models_impl.GConvGRU import GCRNNVirtual
model = GCRNNVirtual(
filters=128, layers=3, khops=2,
node_features=..., forecast_features=..., known_features=..., # see virtual_meteo.py
ctx_features=..., history=47, horizon=12,
)
model.load_state_dict(torch.load("meteo/l=3_k=2_f=128/kfold=0.pt", map_location="cpu"))
model.eval()
Citation
If you use these models, please cite the paper and, if you use the underlying data, the dataset:
@article{uremovic2025contextualized,
title={Contextualized spatio-temporal graph-based method for forecasting sparse geospatial sensor networks},
author={Uremovi{\'c}, Niko and Mongus, Domen and Pur, Aleksander and Luka{\v{c}}, Niko},
journal={Expert Systems with Applications},
volume={294},
pages={128779},
year={2025},
publisher={Elsevier}
}
Data: 10.5281/zenodo.17091212