Metadata-Version: 2.4
Name: city2graph
Version: 1.0.0
Summary: A Python library for Geospatial Graph Neural Networks and GeoAI for Urban Analytics with PyTorch Geometric. Convert geospatial data to graphs for spatiotemporal analysis, urban mobility studies, and more.
Project-URL: Homepage, https://github.com/c2g-dev/city2graph
Project-URL: Documentation, https://city2graph.net
Project-URL: Bug Tracker, https://github.com/c2g-dev/city2graph/issues
Author-email: Yuta Sato <y.sato@liverpool.ac.uk>
License: BSD-3-Clause
License-File: LICENSE
Keywords: Digital Twin,GNNs,GeoAI,Geographic Data Science,Geospatial Analysis,Geospatial Foundation Models,Graph Neural Networks,Graph Representation Learning,PyTorch Geometric,Spatial Data Science,Spatial Knowledge Graphs,Spatiotemporal Analysis,Transportation Networks,Urban Analytics,Urban Informatics,Urban Mobility,Urban Planning and Design
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: <3.15,>=3.12
Requires-Dist: duckdb>=1.1.0
Requires-Dist: geopandas>=1.1.1
Requires-Dist: geopy>=2.4.0
Requires-Dist: libpysal>=4.12.1
Requires-Dist: momepy>=1.0.0
Requires-Dist: networkx>=2.8
Requires-Dist: numpy>=1.24
Requires-Dist: overturemaps>=0.18.1
Requires-Dist: pandas>=2.0
Requires-Dist: pyproj>=3.5
Requires-Dist: rustworkx>=0.17.1
Requires-Dist: scipy>=1.10.0
Requires-Dist: shapely>=2.1.0
Provides-Extra: cpu
Requires-Dist: torch-geometric>=2.8.0; extra == 'cpu'
Requires-Dist: torch>=2.13.0; extra == 'cpu'
Requires-Dist: torchvision>=0.28.0; extra == 'cpu'
Provides-Extra: cu126
Requires-Dist: torch-geometric>=2.8.0; extra == 'cu126'
Requires-Dist: torch>=2.13.0; extra == 'cu126'
Requires-Dist: torchvision>=0.28.0; extra == 'cu126'
Provides-Extra: cu128
Requires-Dist: torch-geometric>=2.8.0; extra == 'cu128'
Requires-Dist: torch>=2.11.0; extra == 'cu128'
Requires-Dist: torchvision>=0.26.0; extra == 'cu128'
Provides-Extra: cu130
Requires-Dist: torch-geometric>=2.8.0; extra == 'cu130'
Requires-Dist: torch>=2.13.0; extra == 'cu130'
Requires-Dist: torchvision>=0.28.0; extra == 'cu130'
Description-Content-Type: text/markdown

# City2Graph: Geospatial Graphs for Network Analysis and GNNs

[![City2Graph](https://city2graph.net/latest/assets/logos/social_preview_city2graph.png)](https://city2graph.net/latest/)

**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](https://geopandas.org/), [NetworkX](https://networkx.org/), and
[PyTorch Geometric](https://pytorch-geometric.readthedocs.io/en/latest/) so the
same geospatial data can support network analysis, urban research, and Graph
Neural Networks (GNNs). See the
[documentation](https://city2graph.net/latest/) for installation, tutorials,
and the Python API reference.

[![PyPI version](https://badge.fury.io/py/city2graph.svg)](https://badge.fury.io/py/city2graph/) [![conda-forge Version](https://anaconda.org/conda-forge/city2graph/badges/version.svg)](https://anaconda.org/conda-forge/city2graph/) [![PyPI Downloads](https://static.pepy.tech/badge/city2graph)](https://pepy.tech/projects/city2graph) [![DOI](https://img.shields.io/badge/DOI-10.1016%2Fj.compenvurbsys.2026.102492-blue?logo=doi&logoColor=white)](https://doi.org/10.1016/j.compenvurbsys.2026.102492) [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://github.com/c2g-dev/city2graph/blob/main/LICENSE)
[![Platform](https://anaconda.org/conda-forge/city2graph/badges/platforms.svg
)](https://anaconda.org/conda-forge/city2graph) [![codecov](https://codecov.io/gh/c2g-dev/city2graph/graph/badge.svg?token=2R449G75Z0)](https://codecov.io/gh/c2g-dev/city2graph) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

## Features

[![City2Graph workflow from geospatial data to graph analysis](https://city2graph.net/latest/assets/figures/scope.png)](https://city2graph.net/latest/)

- **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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
# 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:

```bash
# 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](https://anaconda.org/conda-forge/pytorch/files) 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](docs/contributing.md) for the canonical development
setup, testing, code quality, documentation, and pull request instructions.

## Citation

If you use City2Graph in your research, please cite the paper published in
*Computers, Environment and Urban Systems*:

[![City2Graph paper in Computers, Environment and Urban Systems](https://city2graph.net/latest/assets/figures/CEUS_thumbnail.jpg)](https://doi.org/10.1016/j.compenvurbsys.2026.102492)

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

```bibtex
@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},
}
```

To cite a specific release of the software instead, use the archived version DOI: [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15858845.svg)](https://doi.org/10.5281/zenodo.15858845)

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

## Contributing

Contributions are welcome. The [Contributing Guide](docs/contributing.md)
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`.

[![GeoGraphic Data Science Lab](https://github.com/user-attachments/assets/569b9550-9a48-461d-a408-18d7a5dfc78c)](https://www.liverpool.ac.uk/geographic-data-science/)
