Repository files navigation

City2Graph is a Python library for converting geospatial datasets into graph representations, providing an integrated interface forGeoPandas,NetworkX, andPyTorch 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. For more information, please visit thedocumentation.

• Graph Construction for GeoAI: Build graphs from diverse urban datasets, including buildings, streets, and land use, to power GeoAI and GNN applications.
• Transportation Network Modeling: Analyze public transport systems (buses, trams, trains) by constructing detailed transportation graphs with support of GTFS format.
• Proximity and Contiguity Analysis: Create graphs based on spatial proximity and adjacency for applications in urban planning and environmental analysis.
• Mobility Flow Analysis: Model and analyze urban mobility patterns from various data sources like bike-sharing, migration, and pedestrian flows.
• PyTorch Geometric Integration: Seamlessly convert geospatial data into PyTorch tensors for GNNs.

City2Graph usesMkDocs for current documentation (v0.2.0+) and keepsSphinx for legacy releases (v0.1.0–v0.1.7).

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

This is controlled in.readthedocs.yaml usingREADTHEDOCS_VERSION_TYPE andREADTHEDOCS_VERSION_NAME.

The simplest way to install City2Graph is via pip:

pip install city2graph

This installs the core functionality without PyTorch and PyTorch Geometric.

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

pip install"city2graph[cpu]"

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

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 arecu118,cu124,cu126,cu128, andcu130.

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.

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

# Install city2graphconda install -c conda-forge city2graph# Then install PyTorch and PyTorch Geometricconda install -c conda-forge pytorch pytorch_geometric

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

# Install city2graphconda install -c conda-forge city2graph# Then install PyTorch with CUDA supportconda install -c conda-forge pytorch=2.7.1=*cuda128*conda install -c conda-forge pytorch_geometric

You can browse available CUDA-enabled builds on theconda-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.

If you want to contribute to City2Graph, you can set up a development environment usinguv.

# Install uv if you haven't already done itcurl -LsSf https://astral.sh/uv/install.sh| sh# Clone the repositorygit clone https://github.com/c2g-dev/city2graph.gitcd city2graph# Install development dependencies with a PyTorch variant (e.g., cpu or cu128)uv sync --extra cpu --group dev

You can then run commands within the managed environment:

# Add IPython kernel for interactive developmentuv run ipython kernel install --name"your-env-name" --user# Or start Jupyter Notebookuv run jupyter notebook

The development dependencies include:

• ipython: Enhanced interactive Python shell with Jupyter kernel support
• jupyter andnotebook: For running Jupyter notebooks with project-specific kernel
• isort: Code formatting tools
• pytest andpytest-cov: Testing tools

The Jupyter kernel installation ensures that when you start Jupyter notebooks, you can select the "city2graph" kernel which has access to all your project dependencies in the correct virtual environment.

Before using Docker Compose, ensure you have Docker and Docker Compose installed on your system:

# Check Docker installationdocker --version# Check Docker Compose installationdocker compose version

If these commands don't work, you need to install Docker first:

• For macOS: InstallDocker Desktop
• For Linux: Follow theinstallation instructions for your specific distribution
• For Windows: InstallDocker Desktop

Once Docker is installed, clone the repository and start the containers:

# Clone the repositorygit clone https://github.com/yu-ta-sato/city2graph.gitcd city2graph# Build and run in detached modedocker compose up -d# Access Jupyter notebook at http://localhost:8888# Stop containers when donedocker compose down

You can customize the services in thedocker-compose.yml file according to your needs.

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:

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

We welcome contributions to the City2Graph project! To contribute:

1. Fork and clone the repository:

   git clone https://github.com/<your-name>/city2graph.gitcd city2graphgit remote add upstream https://github.com/c2g-dev/city2graph.git

2. Set up the development environment:

   uv sync --group dev --extra cpusource .venv/bin/activate# On Windows: .venv\Scripts\activate

3. Create a feature branch:

   git checkout -b feature/your-feature-name

4. Make your changes and test:

   # Run pre-commit checksuv run pre-commit run --all-files# Run testsuv run pytest --cov=city2graph --cov-report=html --cov-report=term

5. Submit a pull request with a clear description of your changes.

For detailed contributing guidelines, code style requirements, and documentation standards, please see ourContributing Guide.

We maintain strict code quality standards using:

• Ruff: For linting and formatting
• mypy: For static type checking
• numpydoc: For docstring style validation

All contributions must pass pre-commit checks before being merged.