Code, checkpoints, and data for "Self-Supervised Satellite Region Representations Make Mobility Flow Cross-City Transfer More Robust to Incomplete OpenStreetMap Data" (submitted to ICASSP 2027).
ngsat augments the physics-informed OD-flow transfer model
NeuroGravity with a frozen
12-dimensional satellite region embedding, learned by a permutation-invariant
masked set autoencoder over AlphaEarth cells. It changes the base model in
exactly one place (the node input, h_i^0 = [x_i || z_i]) and makes zero-shot
cross-city transfer more accurate with intact OpenStreetMap features and
markedly more robust when they are missing.
| Path | Content |
|---|---|
Code/ngsat/ |
ngsat: region encoder, tokenizer, SSL pretraining, transfer runner |
Code/ng/ |
frozen copy of NeuroGravity (MIT; see Code/ng/PROVENANCE.md) |
checkpoints/region_encoder/ |
region encoder (trained on the 19 test cities, no LOO) + precomputed embeddings for all 19 cities |
checkpoints/ngsat_boston/ |
one Boston-trained ngsat ensemble (20 rounds x 3 models) that serves every target city |
Data_ng/ |
the six Italian benchmark cities (features + ISTAT-2011 commuting flows); UK data is not redistributable, see Data_ng/README.md |
results/ |
consolidated numbers behind the paper's commuting table, plus the released model's measured performance |
scripts/evaluate_transfer.py |
zero-shot evaluation of the released ensemble on any city under Data_ng/ |
Not released: the proprietary mobile-phone (CDR) OD data and everything derived from it (Boston training flows, CDR target cities). Training from scratch therefore requires your own source-city flow data; everything else (evaluation, transfer to new cities) works out of the box.
conda create -n ngsat python=3.8 -y && conda activate ngsat
pip install -r requirements.txt # PyTorch 2.0 + cu118 wheels, PyG 2.3
# Zero-shot transfer of the released ensemble to Genova (ISTAT commuting):
python scripts/evaluate_transfer.py --city GENOVA --device cuda:0 --rates 0 0.5 0.9Expected output at --rates 0: R2=0.85-level per-city scores; six-city
means are tabulated in results/release_model_measured.json.
Six-city mean zero-shot transfer R2 of the released checkpoint set, OSM category absence at rate rho (30 mask draws per rate):
| Benchmark | rho=0 | rho=0.5 | rho=0.9 |
|---|---|---|---|
| CDR cell-phone OD (6 cities) | 0.560 | 0.546 | 0.485 |
| Italy (ISTAT-2011 commuting) | 0.701 | 0.945 | 0.977 |
| UK (2011 Census commuting, LSOA) | 0.039 | -0.015 | -0.056 |
At the LSOA scale every method has uniformly low R2 (see the paper); CPC
values and per-city numbers for all blocks are in
results/release_model_measured.json.
Two protocols, stated explicitly: the paper evaluates under a strict
leave-one-city-out protocol (the encoder never sees the target city; 10
matched training replicates; those numbers live in results/results_it10b.json
and results/results_ituk_10draw.json). The released model is a single
deployment artifact whose encoder saw the imagery (never the flows) of all 19
test cities; it was selected as the most balanced of 3 training draws, and the
table above is its actual measured performance. The two sets of numbers agree
within between-training noise.
- Export AlphaEarth embeddings for your region grid (100 m componentwise
mean pyramid, renormalized; see
Code/ngsat/data/aef_grid.py). - Build
Data_ng/<CITY>/raw_data/attr_sat_df.csv(+ region geojson) in the same schema as the released Italian cities. - Encode regions with the released encoder, then run
scripts/evaluate_transfer.py --city <CITY>(predictions are written as npz next to the metrics).
Paper reference will be added upon publication. Please also cite NeuroGravity and the AlphaEarth Foundations dataset ("produced by Google and Google DeepMind").
Code is MIT (see LICENSE). Data files carry their own licenses, documented
in Data_ng/README.md (ISTAT: CC-BY; AlphaEarth-derived features:
CC-BY 4.0).
 Jinming Yang |
 Zongyuan Huang |
 Peiyan Sun |
 Shengyuan Xu |
 Shaoyu Huang |
Supervisors
 Yanyan Xu |
 Marta C. González |
 Yaohui Jin |