city2graph#

city2graph logo
city2graph logo

city2graph is a Python library for converting geospatial datasets into graphs for GNN with integrated interface of GeoPandas, NetworkX, and Pytorch Geometric across multiple domains (e.g. streets, transportations, OD matrices, POI proximities, etc.). It enables researchers and practitioners to seamlessly develop advanced GeoAI and geographic data science applications.

Overview scope of city2graph

Features#

  • Construct graphs from morphological datasets (e.g. buildings, streets, and land use from OpenStreetMap (OSM), Overture Maps, and others)

  • Construct graphs from transportation datasets (e.g. public transport of buses, trams, and trains from GTFS)

  • Construct graphs from contiguity datasets (e.g. land use, land cover, and administrative boundaries)

  • Construct graphs from mobility datasets (e.g. bike-sharing, migration, and pedestrian flows)

  • Convert geospatial data (GeoPandas / NetworkX) into tensors (PyTorch Geometric’s Data and HeteroData) for graph representation learning, such as Graph Neural Networks (GNNs)

Keywords#

GeoAI, Graph Neural Networks, GNNs, PyTorch Geometric, Geospatial Analysis, Urban Analytics, Spatial Data Science, Urban Mobility, Transportation Networks, Geospatial Foundation Models, Digital Twin, Urban Informatics, Geographic Data Science, Graph Representation Learning, Urban Planning and Design, Urban Morphology.

PyPI version conda-forge Version PyPI Downloads DOI License Platform codecov Ruff

Quickstart#

Install city2graph using pip (recommended):

pip install city2graph

For graph neural network functionality (PyTorch, PyTorch Geometric):

pip install "city2graph[cpu]"  # CPU only
pip install "city2graph[cu128]"  # For CUDA 12.8 (GPU)

Supported CUDA options: cu118, cu124, cu126, cu128

Or install with conda (core functionality only):

conda install -c conda-forge city2graph

To add PyTorch and PyTorch Geometric (conda):

conda install -c conda-forge pytorch pytorch_geometric

For CUDA-enabled PyTorch (conda):

conda install -c conda-forge pytorch=2.7.1=*cuda128*
conda install -c conda-forge pytorch_geometric

Warning

As conda is not officially supported by PyTorch and PyTorch Geometric anymore, pip is recommended for full PyTorch support. See Installation for details.

Examples#

Morphology

morphological_graph = city2graph.morphological_graph(
   buildings_gdf,
   segments_gdf,
   center_point,
   distance=500
 )
A morphological graph in Liverpool

A morphological graph of 500m walking distance in Liverpool#

>> For details, see Morphological Graph from Overture Maps with city2graph

Transportation

sample_gtfs_path = Path("./itm_london_gtfs.zip")
gtfs_data = city2graph.load_gtfs(sample_gtfs_path)

travel_summary_nodes, travel_summary_edges = city2graph.travel_summary_graph(
   gtfs_data, calendar_start="20250601", calendar_end="20250601")
A bus transportation graph in London

A travel summary graph of bus transportation between stops in London#

>> For details, see Transportation Network Analysis with city2graph

Proximity

fixed_radius_graph = city2graph.fixed_radius_graph(poi_gdf, radius=100)

wax_l1_nodes, wax_l1_edges = city2graph.waxman_graph(poi_gdf,
                                 distance_metric="manhattan",
                                 r0=100,
                                 beta=0.5)

wax_l2_nodes, wax_l2_edges = city2graph.waxman_graph(poi_gdf,
                                 distance_metric="euclidean",
                                 r0=100,
                                 beta=0.5)

wax_net_nodes, wax_net_edges = city2graph.waxman_graph(poi_gdf,
                                 distance_metric="network",
                                 r0=100,
                                 beta=0.5,
                                 network_gdf=segments_gdf.to_crs(epsg=6677))
Waxman graph of points of interest in Liverpool 
nodes_dict = {
   "restaurants": poi_gdf,
   "hospitals": hospital_gdf,
   "commercial": commercial_gdf
}

# Generate proximity edges between layers using KNN method
proximity_nodes, proximity_edges = city2graph.bridge_nodes(
   nodes_dict,
   proximity_method="knn",
   k=5,
   distance_metric="euclidean"
)
Bridge nodes connecting different layers of POIs

>> For details, see Generating Various Types of Graphs by Proximity

Citation#

If you use city2graph in your research, please cite it as follows:

@software{sato2025city2graph,
  title = {city2graph: Transform geospatial relations into graphs for spatial network analysis and Graph Neural Networks},
  author = {Sato, Yuta},
  year = {2025},
  url = {https://github.com/c2g-dev/city2graph},
  doi = {10.5281/zenodo.15858845},
}

You can also use the DOI to cite a specific version: DOI

Alternatively, you can find the citation information in the CITATION.cff file in the repository, which follows the Citation File Format standard.

Documentation#

Contents:

Indices and tables#

GeoGraphic Data Science Lab