2026-08-13
City2Graph turns buildings, streets, transit, POIs into heterogeneous graphs for PyTorch Geometric; on Liverpool clustering, heterogeneous GNNs lift silhouette from 0.19 to 0.39.
Urban data is heterogeneous by nature: buildings, streets, transit stops, points of interest, and administrative zones, each connected in different ways. Graph neural networks are a natural fit, and heterogeneous graph models, which can distinguish what kind of thing connects to what kind, fit a complex system like a city better than homogeneous models that treat every node as the same type.
The bottleneck is preprocessing. Building the graph is nobody's favorite task. Each data domain, morphology, transit, mobility, proximity, has its own parsing conventions, and feeding the finished graph to PyTorch Geometric means writing more conversion code to turn it into tensors. The graph is then reshaped again as the work moves from mapping to centrality to training, and the glue code is rewritten every time. The result is that heterogeneous models, the more capable tool, rarely reach real city studies.
City2Graph is a library, not a new architecture. Its three design choices each target a part of that pain.
First, one interface covers four data domains: morphology turns buildings, streets, and tessellation cells into a morphological graph; transit ingests a GTFS feed and emits a stop-to-stop travel-time graph; mobility converts an origin-destination matrix into a weighted flow graph; proximity produces KNN, Waxman, Delaunay, or contiguity graphs. Graph construction stops being a preprocessing project and becomes a few lines.
Second, geometry is preserved end to end, and the same graph round-trips between GeoPandas, NetworkX, PyTorch Geometric Data and HeteroData, and rustworkx. Explore it in NetworkX, run heavy algorithms in rustworkx, train in PyG, and map the results, without rewriting conversion code for each tool. This is the part people keep rewriting.
Third, metapath construction (addmetapaths) materializes composite relations across node types as edges, such as an area reached from an area through multimodal transit. Heterogeneous architectures like HAN learn precisely from metapaths plus attention, and without a standard way to build them, these models are hard to deploy. PyTorch itself is optional; core construction and analysis run on GeoPandas and NetworkX alone.
The case study clusters urban functions across 1,624 census Output Areas in Liverpool, using land use and POIs from Overture Maps as node features. Three relations are built: spatial contiguity (4,782 edges), 15-minute walk accessibility (28,265 edges), and 15-minute multimodal accessibility (69,403 edges). The comparison runs under a graph autoencoder (GAE) frame with two encoders: homogeneous GAT, on the contiguity graph only, and heterogeneous HAN, with semantic attention over metapaths and a DistMult decoder per relation. Everything runs on an Apple M2 CPU with no GPU.
Four independent metrics (mean ± SD; heterogeneous models are all HAN-GAE):
| Model | Silhouette up | Davies-Bouldin down | Calinski-Harabasz up | Contiguity modularity up |
| PCA baseline | 0.19 ± 0.01 | 1.76 | 139 | 0.09 |
| GAT-GAE (homogeneous) | 0.19 ± 0.01 | 1.54 | 178 | 0.60 |
| HAN-GAE Walk | 0.37 ± 0.06 | 1.01 | 435 | 0.77 |
| HAN-GAE Multi | 0.39 ± 0.04 | 0.90 | 738 | 0.75 |
| HAN-GAE All | 0.38 ± 0.04 | 0.93 | 612 | 0.79 |
The heterogeneous models lead across all four families: silhouette roughly doubles (0.19 to about 0.39), Davies-Bouldin is nearly halved, and Calinski-Harabasz is about four times higher. The most telling number is modularity, which measures how well the clusters align with the underlying spatial network. On the multimodal accessibility graph, HAN-GAE All reaches 0.28 against 0.08 for homogeneous GAT. The clusters the heterogeneous model learns are not just next to each other; they follow the walk-plus-transit accessibility structure and track the defined accessibility patterns.
A reverse signal: the S variants, with node features removed and only graph structure kept, collapse to near-zero modularity and two clusters. The functional signal in a city lives in land use and POI features; pure topology does not separate functions.
For anyone in GeoAI or urban computing, it drops the cost of using heterogeneous-graph GNNs from writing two weeks of preprocessing to a few lines. This is an infrastructure paper: the value is standardization and reproducibility, not a new architecture. The full Liverpool pipeline reproduces on a laptop CPU, the code is BSD, the data is CC-BY, and the workflow is pinned with uv and archived on Zenodo. It fills a gap next to OSMnx, which targets OpenStreetMap street networks: City2Graph adds buildings, transit, mobility, proximity, and heterogeneous workflows, and the two complement each other.
Validation covers one city and one task, functional clustering. Every metric is an unsupervised internal measure of cluster coherence; there is no external ground truth, so the numbers tell you clusters are coherent, not that they are correct. The silhouette standard deviation is not small (±0.06). The chosen K varies widely, from 22 to 44 clusters for the heterogeneous models against 5 for homogeneous, so this is not a fixed-K comparison, and whether 44 clusters over 1,624 areas are interpretable is left open. The machine-learning content is not new; the paper uses existing GAT and HAN architectures, and the contribution sits in engineering and pipeline. Finally, because the signal rests on node features, this is not a pure graph-structure win.