City2Graph: Geospatial Graphs for Network Analysis and GNNs

City2Graph is a Python library that turns buildings, streets, public transport feeds, origin–destination matrices, zones, and points of interest into spatial and heterogeneous graphs. It bridges GeoPandas, NetworkX, and PyTorch Geometric so the same geospatial data can support network analysis, urban research, and Graph Neural Networks (GNNs). See the documentation for installation, tutorials, and the Python API reference.

Features

• Morphology: Graphs of buildings, streets, and tessellated urban fabric from OpenStreetMap and Overture Maps.
• Transportation: GTFS public transport and GBFS shared-mobility feeds loaded into DuckDB, with GTFS aggregated into stop-to-stop transit graphs.
• Mobility: Origin–destination matrices and flow data — migration, bike-sharing, pedestrian counts — as weighted spatial graphs.
• Proximity and Contiguity: KNN, Delaunay, Gilbert, and Waxman graphs plus queen/rook contiguity, under Euclidean, Manhattan, or network distances.
• Heterogeneous Graphs and Metapaths: Multiple node and edge types in one graph, with metapath-derived edges composing relations across them.
• GNN-ready Tensors: Round-trip conversion between GeoDataFrames, NetworkX, and PyTorch Geometric Data/HeteroData.

Installation

Using pip

Basic Installation

City2Graph supports Python 3.12–3.14. The simplest way to install it is via pip:

pip install city2graph

This installs the core functionality without PyTorch and PyTorch Geometric.

With PyTorch (CPU)

If you need the Graph Neural Networks functionality, install with the cpu option:

pip install "city2graph[cpu]"

This will install PyTorch and PyTorch Geometric with CPU support, suitable for development and small-scale processing.

With PyTorch + CUDA (GPU)

For GPU acceleration, you can install City2Graph with a specific CUDA version extra. For example, for CUDA 13.0:

pip install "city2graph[cu130]"

Supported CUDA versions are cu126, cu128, and cu130. The cpu, cu126, and cu130 extras use PyTorch 2.13 or newer. Because PyTorch no longer publishes CUDA 12.8 wheels past 2.11, cu128 uses PyTorch 2.11.

Using conda

Basic Installation

You can also install City2Graph using conda from conda-forge:

conda install -c conda-forge city2graph

This installs the core functionality without PyTorch and PyTorch Geometric.

With PyTorch (CPU)

To use PyTorch and PyTorch Geometric with City2Graph installed from conda-forge, you need to manually add these libraries to your environment:

# Install city2graph
conda install -c conda-forge city2graph

# Then install PyTorch and PyTorch Geometric
conda install -c conda-forge pytorch pytorch_geometric

With PyTorch + CUDA (GPU)

For GPU support, you should select the appropriate PyTorch variant by specifying the version and CUDA build string. For example, to install PyTorch 2.13.0 with CUDA 13.0 support:

# Install city2graph
conda install -c conda-forge city2graph

# Then install PyTorch with CUDA support
conda install -c conda-forge pytorch=2.13.0=*cuda130*
conda install -c conda-forge pytorch_geometric

You can browse available CUDA-enabled builds on the conda-forge PyTorch files page and substitute the desired version and CUDA variant in your install command. Make sure that the versions of PyTorch and PyTorch Geometric you install are compatible with each other and with your system.

⚠️ Important: conda is not officially supported by PyTorch and PyTorch Geometric anymore, and only conda-forge distributions are available for them. We recommend using pip or uv for the most streamlined installation experience if you need PyTorch functionality.

For Development

See the Contributing Guide for the canonical development setup, testing, code quality, documentation, and pull request instructions.

Citation

City2Graph is described in a peer-reviewed article. Any use of City2Graph in research or software must cite the following paper, published in Computers, Environment and Urban Systems:

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. https://doi.org/10.1016/j.compenvurbsys.2026.102492

@article{sato2026city2graph,
  title = {City2Graph: A Python library for Heterogeneous Graph Neural Networks and spatial analysis in urban systems},
  author = {Sato, Yuta and Pietrostefani, Elisabetta and Mahabir, Ron and Arribas-Bel, Daniel},
  journal = {Computers, Environment and Urban Systems},
  volume = {130},
  pages = {102492},
  year = {2026},
  issn = {0198-9715},
  doi = {10.1016/j.compenvurbsys.2026.102492},
  url = {https://www.sciencedirect.com/science/article/pii/S0198971526000943},
}

The same citation is recorded in the CITATION.cff file in this repository, which follows the Citation File Format standard.

Contributing

Contributions are welcome. The Contributing Guide contains the complete development and quality requirements.

Documentation

City2Graph uses MkDocs for current documentation (v0.2.0+) and keeps Sphinx for legacy releases (v0.1.0–v0.1.7).

• Legacy tags (v0.1.*): Read the Docs builds docs/source via Sphinx.
• Everything else (branches / newer tags): Read the Docs builds via MkDocs (mkdocs.yml).

This is controlled in .readthedocs.yaml using READTHEDOCS_VERSION_TYPE and READTHEDOCS_VERSION_NAME.