How c2g-dev/city2graph works
City2Graph is a pure-Python geospatial graph-construction library. Its architecture is centered on transforming geographic tabular data into graph objects that can be consumed by spatial analysis workflows, NetworkX, and optionally PyTorch Geometric.
1. Core package boundary
The city2graph/ package is the runtime library. __init__.py exposes the public API, while the domain modules underneath implement different graph-generation strategies. There is no server or service layer; the repo is a library plus docs/tests.
2. Shared graph model and conversion layer
base.py and graph.py appear to define the shared internal graph abstractions and common conversion/normalization logic. This is the main boundary between geospatial inputs and graph outputs, and it is where a diagram should place the “core representation” of nodes, edges, attributes, and graph metadata.
3. Spatial data helpers
data.py and utils.py provide supporting functions for loading, validating, and transforming inputs, plus general utilities reused across the domain modules. These are the glue layer used before or after graph construction.
4. Proximity and contiguity subsystem
proximity.py builds graphs from spatial closeness and adjacency relationships. Based on the README, this includes proximity-based graph generation, multi-center distance filtering, and layered isochrone-style relationships. This subsystem likely accepts GeoPandas geometries and emits edge lists/graphs.
5. Morphology subsystem
morphology.py handles graphs derived from urban form features such as buildings or other morphological entities. The docs include an example for building graphs from Overture Maps, which suggests this module operates on parcel/building-style geospatial layers and constructs morphology-driven connectivity.
6. Transportation subsystem
transportation.py is the transit-network branch. The README specifically calls out GTFS feeds queried through DuckDB, so this module is the main bridge from transport schedule data to graph structures for route/service/accessibility analysis.
7. Mobility subsystem
mobility.py models movement flows such as OD matrices, bike-sharing, migration, and pedestrian flows. This subsystem converts mobility matrices or flow tables into graph representations, distinct from purely spatial adjacency graphs.
8. Metapath / heterogeneous-graph augmentation
metapath.py adds higher-level graph logic for heterogeneous or multi-relational analysis. The notebook add_metapaths.ipynb indicates this module enriches existing graphs with metapath-based relationships for downstream GNN or network analysis.
9. External technology boundaries
The library integrates with GeoPandas for geospatial inputs, NetworkX for graph operations, and PyTorch Geometric for tensor/ML workflows. PyTorch/PyG are optional extras, which creates a clear boundary between general graph construction and GNN-specific consumption.
10. Package distribution and environment
pyproject.toml, uv.lock, Dockerfile, and docker-compose.yml define packaging and reproducible development environments. The README also shows install extras for CPU/CUDA variants, so deployment is mostly via Python packaging rather than a separate runtime.
11. Documentation and examples as first-class architecture
docs/ contains MkDocs-based documentation, API references for each module, and notebook examples for the main workflows: proximity graphs, OD matrices, GTFS, metapaths, and morphology. This indicates the library is designed around user-driven notebook experimentation as much as scripted use.
12. Test structure and quality gates
tests/ mirrors the domain modules with unit tests for each subsystem plus fixtures in tests/data/. GitHub Actions workflows run build/test/deploy/documentation jobs, and pre-commit/Ruff are used as quality gates. This suggests the architecture is intentionally modular, with each graph-building domain verified independently.
A good architecture diagram for this repo should show: geospatial/mobility/transit inputs on the left; the shared core graph model in the center; domain-specific constructors around it; and export paths to NetworkX/PyTorch Geometric on the right, with docs/tests/CI as supporting system boundaries.
Main entry points: base.py Core model · test_graph.py Tests · __init__.py Public API · index.md Examples
Components 19
Core library
Public API, shared model, and conversion layer.
- Public API · Exports the main user-facing constructors and symbols.
city2graph/__init__.py - Core model · Shared internal representation for nodes, edges, and graph metadata.
city2graph/base.py - Graph ops · Common graph normalization, conversion, and interoperability logic.
city2graph/graph.py - Data helpers · Loading, validation, and transformation helpers for geospatial inputs.
city2graph/data.py - Utilities · General reusable helper functions used across the package.
city2graph/utils.py
Graph builders
Domain-specific constructors for different geospatial and mobility workflows.
- Proximity · Builds graphs from closeness, adjacency, and distance-based relationships.
city2graph/proximity.py - Morphology · Constructs graphs from buildings and other morphological geospatial layers.
city2graph/morphology.py - Transportation · Transforms GTFS-style transit data into graph structures for analysis.
city2graph/transportation.py - Mobility · Converts OD matrices and movement flows into graph representations.
city2graph/mobility.py - Metapaths · Adds metapath-based relationships for heterogeneous graph analysis.
city2graph/metapath.py
External integrations
Third-party graph and geospatial ecosystems used by the library.
- GeoPandas · Primary geospatial dataframe and geometry source for graph construction.
- GTFS/DuckDB · Transit schedule and route data queried through DuckDB.
- Flow tables · OD matrices, bike-share, migration, and pedestrian flow inputs.
- NetworkX · Core graph library used as a downstream graph consumer.
- PyG · Optional PyTorch Geometric export path for GNN workflows.
Support system
Documentation, tests, packaging, and CI around the library.
- Docs · MkDocs documentation and notebooks for the main workflows.
docs/index.md - Examples · Workflow examples for proximity, morphology, GTFS, mobility, and metapaths.
docs/examples/index.md - Tests · Module-level tests and fixtures covering the main graph builders.
tests/test_graph.py - CI/CD · GitHub Actions, packaging, and release/deployment automation.
.github/workflows/test.yml
Connections 31
- GeoPandas → Data helpers: prepare · Geospatial tabular inputs are validated and normalized before graph building.
- GTFS/DuckDB → Data helpers: prepare · Transit source data is loaded and shaped for the transportation pipeline.
- Flow tables → Data helpers: prepare · Flow tables are cleaned and reshaped into graph-ready records.
- Data helpers → Core model: normalize · Input helpers feed the shared graph model boundary.
- Utilities → Core model: support · Utilities assist graph model creation and manipulation.
- Core model → Graph ops: convert · The core representation is converted into interoperable graph objects.
- Proximity → Core model: build · Proximity relationships are expressed through the shared graph model.
- Morphology → Core model: build · Morphology-derived connectivity is mapped into the core representation.
- Transportation → Core model: build · Transit data is transformed into graph objects via the shared model.
- Mobility → Core model: build · Mobility flows are turned into graph structures using the common model.
- Metapaths → Core model: augment · Metapath relationships extend the shared graph representation.
- Graph ops → NetworkX: export · Graphs can be consumed by NetworkX workflows.
- Graph ops → PyG: export · Graphs can optionally be exported for PyTorch Geometric.
- Public API → Proximity: expose · The public API surfaces the proximity builder.
- Public API → Morphology: expose · The public API surfaces the morphology builder.
- Public API → Transportation: expose · The public API surfaces the transportation builder.
- Public API → Mobility: expose · The public API surfaces the mobility builder.
- Public API → Metapaths: expose · The public API surfaces metapath augmentation tools.
- Docs → Public API: document · Docs describe the public API and module boundaries.
- Examples → Proximity: demonstrate · Examples show the proximity workflow in notebooks.
- Examples → Transportation: demonstrate · Examples show the GTFS workflow in notebooks.
- Examples → Mobility: demonstrate · Examples show the mobility workflow in notebooks.
- Examples → Metapaths: demonstrate · Examples show metapath enrichment in notebooks.
- Tests → Core model: verify · Tests cover the shared graph model and conversions.
- Tests → Proximity: verify · Tests cover proximity graph generation.
- Tests → Morphology: verify · Tests cover morphology graph generation.
- Tests → Transportation: verify · Tests cover transportation graph generation.
- Tests → Mobility: verify · Tests cover mobility graph generation.
- Tests → Metapaths: verify · Tests cover metapath augmentation.
- CI/CD → Docs: publish · Automation builds and publishes the documentation site.
- CI/CD → Tests: run · Automation runs the test suite and quality gates.