sampa-project/contextual-gcn-sparse

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.

• Code: SAMPA-Project/contextual-gcn-sparse-uremovic
• Data: 10.5281/zenodo.17091212

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