DOCSEARCHbyAlgolia
Submit Docs

city2graph

repository·main·Indexed 23 days ago

https://github.com/c2g-dev/city2graph

A Python library for Geospatial Graph Neural Networks and GeoAI for Urban Analytics using PyTorch Geometric. It converts geospatial data—such as buildings, streets, and transit feeds—into spatial and heterogeneous graphs, bridging GeoPandas, NetworkX, and PyTorch Geometric. Key features include morphological graph creation, GTFS/GBFS transportation network loading, mobility flow representation, and proximity-based graph generation (KNN, Delaunay, etc.).

Tokens
29.6K
Snippets
59
Records
145
Agent score
79%

What's inside city2graph

  1. Overview of City2Graph

    main

    City2Graph is a Python library designed to transform geospatial data into spatial and heterogeneous graphs for network analysis, urban research, and Graph Neural Networks (GNNs). It acts as a bridge between several key geospatial and graph libraries:

    • GeoPandas: For geospatial data manipulation.
    • NetworkX: For traditional network analysis.
    • PyTorch Geometric: For Graph Neural Networks (GNNs).

    Key capabilities include:

    • Morphology: Creating graphs from buildings, streets, and urban fabric (OSM/Overture Maps).
    • Transportation: Loading GTFS and GBFS feeds into DuckDB and aggregating them into transit graphs.
    • Mobility: Representing origin-destination matrices and flow data as weighted spatial graphs.
    • Proximity/Contiguity: Generating KNN, Delaunay, Gilbert, and Waxman graphs, or queen/rook contiguity under various distance metrics (Euclidean, Manhattan, or network).
    • Heterogeneous Graphs: Supporting multiple node and edge types with metapath-derived relations.
    • GNN Integration: Providing round-trip conversion between GeoDataFrames, NetworkX, and PyTorch Geometric Data/HeteroData tensors.

  2. Use the Transportation Module for GTFS and GBFS data

    main

    The city2graph.transportation module provides tools to ingest public transport and shared-mobility data into DuckDB. It supports loading GTFS (General Transit Feed Specification) archives and GBFS (General Bikeshare Feed Specification) JSON feeds.

    Key capabilities include:

    • Loading GTFS public transport archives.
    • Loading GBFS shared-mobility JSON feeds.
    • Deriving stop-to-stop origin–destination (OD) pairs.
    • Aggregating GTFS schedules into transportation network graphs.

  3. Generate spatial graphs with the Proximity module

    main

    The city2graph.proximity module provides functions to generate proximity-based graph networks from spatial data. It allows you to create edges between geometries using various spatial relationship algorithms, which is useful for POI (Point of Interest) and zone analysis.

    Available graph generation methods include:

    • knn_graph: K-Nearest Neighbors graph.
    • delaunay_graph: Delaunay triangulation.
    • gabriel_graph: Gabriel graph.
    • relative_neighborhood_graph: Relative Neighborhood Graph.
    • euclidean_minimum_spanning_tree: Euclidean Minimum Spanning Tree.
    • fixed_radius_graph: Graph based on a fixed distance radius.
    • waxman_graph: Waxman graph model.
    • contiguity_graph: Graph based on contiguity relations.

    Additionally, the module supports node manipulation functions:

    • bridge_nodes: For creating connections between disparate spatial groups.
    • group_nodes: For aggregating nodes into spatial groups.

  4. Load and process geospatial data with the Data module

    main

    The city2graph.data module is used to load and process geospatial data for graph construction. It primarily focuses on extracting data from Overture Maps, including buildings, roads, places, and administrative boundaries.

    Key functions available in this module:

    • load_overture_data: Loads raw geospatial data from Overture Maps.
    • process_overture_segments: Processes segments extracted from Overture data.
    • get_boundaries: Retrieves administrative or spatial boundaries.

  5. Supported data inputs for City2Graph

    main

    City2Graph can convert a wide variety of geospatial data formats into graph representations. Supported inputs include:

    • Urban Features: Buildings, street segments, tessellations, and Overture Maps features.
    • Mobility & Transit: GTFS and GBFS feeds, and Origin-Destination (OD) matrices or flow edge lists.
    • Spatial Entities: Points of interest (POI), polygonal zones, and general points/polygons.
    • Existing Graphs: GeoDataFrames, NetworkX graphs, PyTorch Geometric (PyG) objects, or rustworkx graphs.

  6. Create morphological graphs with the Morphology module

    main
    The city2graph.morphology module is used to generate morphological graphs from urban form data. These graphs capture the spatial relationships between different urban elements, specifically distinguishing between place spaces (such as tessellation cells or building footprints) and movement spaces (such as street segments).

  7. Use the Metapath module to add edges to heterogeneous graphs

    main

    The city2graph.metapath module allows you to add metapath-derived edges to heterogeneous graphs. This is specifically useful for preparing data for Graph Neural Network (GNN) architectures that rely on metapath aggregation, such as Heterogeneous Graph Attention Networks (HAN) or Heterogeneous Graph Transformer (HGT).

    Key functions include:

    • add_metapaths: Adds edges based on defined metapaths.
    • add_metapaths_by_weight: Adds edges based on metapaths while incorporating edge weights.

  8. Relationship between City2Graph and OSMnx

    main

    City2Graph and OSMnx are complementary tools rather than competitors:

    • OSMnx: A specialized toolkit for downloading and analyzing OpenStreetMap street networks.
    • City2Graph: Uses street data (which can come from OSMnx) and combines it with other layers like buildings, Overture Maps, transit, and mobility data to create complex heterogeneous or proximity graphs.

  9. Convert between GeoPandas, NetworkX, and PyTorch Geometric

    main

    City2Graph supports round-trip conversion between different graph and spatial representations, including heterogeneous graphs. This allows you to perform spatial analysis in GeoPandas, run fast graph algorithms in NetworkX or rustworkx, and then convert to PyTorch Geometric for GNN training.

    For specific function signatures, refer to the Graph conversion API.

  10. Determine if PyTorch is required for your workflow

    main

    PyTorch is not a required dependency for the core City2Graph functionality.

    • Core Installation: Uses GeoPandas, NetworkX, and rustworkx for building and analyzing geospatial graphs.
    • Optional Installation: PyTorch and PyTorch Geometric are only needed if you intend to use GNN-ready Data and HeteroData tensors.

  11. Code quality standards for City2Graph

    main

    All code, comments, docstrings, and documentation must be in English. The project enforces the following standards:

    • Linting & Formatting: Uses Ruff. Formatter line length is 100 characters (linting allows up to 140 where clean rewrites are not possible).
    • Typing: Uses mypy with strict type checking. All public functions must include type hints.
    • Docstrings: Uses numpydoc validation. Public modules, functions, classes, and methods must use NumPy-style docstrings.
    • Indentation: Use four spaces.

  12. Build morphological graphs from Overture Maps or OSM

    main
    Use City2Graph to model urban form by creating heterogeneous graphs containing buildings, tessellation cells (private and public space), and street networks. This workflow is suitable for analyzing urban fabric and can export the resulting graphs to NetworkX or PyTorch Geometric for downstream analysis or GNN training.