City2Graph: A Python library for Heterogeneous Graph Neural Networks and spatial analysis in urban systems [R]

City2Graph is a Python library I built that turns geospatial data into analysis-ready graphs, and the paper describing it has just been published, so I wanted to share it here.

import city2graph as c2g # buildings + street segments -> heterogeneous morphological graph nodes, edges = c2g.morphological_graph(buildings, segments) # straight into PyTorch Geometric data = c2g.gdf_to_pyg(nodes, edges) 

What it covers:

• Morphology: graphs of buildings, streets, and tessellated urban fabric from OpenStreetMap and Overture Maps
• Transportation: GTFS and GBFS feeds loaded through DuckDB, with GTFS aggregated into stop-to-stop transit graphs
• Mobility: OD matrices and flow data (migration, bike-sharing, pedestrian counts) as weighted spatial graphs
• Proximity and contiguity: KNN, Delaunay, Gilbert, Waxman, plus queen/rook contiguity, under Euclidean, Manhattan, or network distances
• Heterogeneous graphs and metapaths: several node and edge types in one graph, with metapath-derived edges composing relations across them
• Conversion: round trips between GeoDataFrames, NetworkX, rustworkx, and PyTorch Geometric Data/HeteroData, with geometries and attributes kept intact

It sets out why urban data is better treated as heterogeneous graphs than as flat feature tables, how the morphological, transport, mobility, and proximity constructions relate to each other, and how the library keeps geometry and graph structure consistent across conversions. If you use the library in research, that is the citation.

Paper

Sato, Y., Pietrostefani, E., Mahabir, R., & Arribas-Bel, D. (2026). City2Graph: A Python library for Heterogeneous Graph Neural Networks and spatial analysis in urban systems. Computers, Environment and Urban Systems, 130, 102492.

Happy to answer questions about the design, and issues or PRs are very welcome. I am especially keen to hear which data sources people want supported next.