# city2graph
[](http://city2graph.net/_static/social_preview.png)
**city2graph** is a Python library for converting urban geometry into graph representations, enabling advanced analysis of urban environments. For more information, please reach out to the document (https://city2graph.net).
[](https://pypi.org/project/city2graph/)
[](https://codecov.io/gh/c2g-dev/city2graph)
[](https://github.com/c2g-dev/city2graph/blob/main/LICENSE)
[](https://github.com/astral-sh/ruff)
## Features
[](http://city2graph.net/_static/scope.png)
- Construct graphs from morphological datasets (e.g. buildings, streets, and land use)
- Construct graphs from transportation datasets (e.g. public transport of buses, trams, and trains)
- Construct graphs from contiguity datasets (e.g. land use, land cover, and administrative boundaries)
- Construct graphs from mobility datasets (e.g. bike-sharing, migration, and pedestrian flows)
- Convert geospatial data into pytorch tensors for graph representation learning, such as Graph Neural Networks (GNNs)
## Installation
### Without PyTorch
The simplest way to install city2graph is via pip:
```bash
# Basic installation (without PyTorch)
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
# Install with PyTorch and PyTorch Geometric (CPU version)
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 12.8:
```bash
# e.g., for CUDA 12.8
pip install "city2graph[cu128]"
```
Supported CUDA versions are `cu118`, `cu124`, `cu126`, and `cu128`.
**Important:** The PyTorch Geometric extensions (`pyg_lib`, `torch_scatter`, etc.) are not included and must be installed separately. Please refer to the [PyTorch Geometric documentation](https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html) for instructions. Due to the low demand, `conda` distributions are deprecated for PyTorch and PyTorch Geometric. For the most reliable setup, we recommend using pip or uv as described above.
#### For Development
If you want to contribute to city2graph, you can set up a development environment using `uv`.
```bash
# Install uv if you haven't already done it
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone the repository
git clone https://github.com/c2g-dev/city2graph.git
cd 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:
```bash
# Add IPython kernel for interactive development
uv run ipython kernel install --name "your-env-name" --user
# Or start Jupyter Notebook
uv run jupyter notebook
```
#### Development Environment
The development dependencies include:
- `ipython`: Enhanced interactive Python shell with Jupyter kernel support
- `jupyter` and `notebook`: For running Jupyter notebooks with project-specific kernel
- `isort`: Code formatting tools
- `pytest` and `pytest-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.
## Using Docker Compose
Before using Docker Compose, ensure you have Docker and Docker Compose installed on your system:
```bash
# Check Docker installation
docker --version
# Check Docker Compose installation
docker compose version
```
If these commands don't work, you need to install Docker first:
- For macOS: Install [Docker Desktop](https://www.docker.com/products/docker-desktop)
- For Linux: Follow the [installation instructions](https://docs.docker.com/engine/install/) for your specific distribution
- For Windows: Install [Docker Desktop](https://www.docker.com/products/docker-desktop)
Once Docker is installed, clone the repository and start the containers:
```bash
# Clone the repository
git clone https://github.com/yu-ta-sato/city2graph.git
cd city2graph
# Build and run in detached mode
docker compose up -d
# Access Jupyter notebook at http://localhost:8888
# Stop containers when done
docker compose down
```
You can customize the services in the `docker-compose.yml` file according to your needs.
## Contributing
We welcome contributions to the city2graph project! To contribute:
1. **Fork and clone the repository:**
```bash
git clone https://github.com/<your-name>/city2graph.git
cd city2graph
git remote add upstream https://github.com/c2g-dev/city2graph.git
```
2. **Set up the development environment:**
```bash
uv sync --group dev --extra cpu
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
3. **Create a feature branch:**
```bash
git checkout -b feature/your-feature-name
```
4. **Make your changes and test:**
```bash
# Run pre-commit checks
uv run pre-commit run --all-files
# Run tests
uv 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 our [Contributing Guide](docs/source/contributing.rst).
## Code Quality
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "city2graph",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "graph-neural-networks, gtfs, mobility, overturemaps, pytorch-geometric, transportation, urban",
"author": null,
"author_email": "Yuta Sato <y.sato@liverpool.ac.uk>",
"download_url": "https://files.pythonhosted.org/packages/b8/33/653c8380b92c026f5386f062b3c006d70e0415820cf78e724feb66ad9e2c/city2graph-0.1.1.tar.gz",
"platform": null,
"description": "# city2graph\n\n[](http://city2graph.net/_static/social_preview.png)\n\n**city2graph** is a Python library for converting urban geometry into graph representations, enabling advanced analysis of urban environments. For more information, please reach out to the document (https://city2graph.net).\n\n[](https://pypi.org/project/city2graph/)\n[](https://codecov.io/gh/c2g-dev/city2graph)\n[](https://github.com/c2g-dev/city2graph/blob/main/LICENSE)\n[](https://github.com/astral-sh/ruff)\n\n## Features\n\n[](http://city2graph.net/_static/scope.png)\n\n\n- Construct graphs from morphological datasets (e.g. buildings, streets, and land use)\n- Construct graphs from transportation datasets (e.g. public transport of buses, trams, and trains)\n- Construct graphs from contiguity datasets (e.g. land use, land cover, and administrative boundaries)\n- Construct graphs from mobility datasets (e.g. bike-sharing, migration, and pedestrian flows)\n- Convert geospatial data into pytorch tensors for graph representation learning, such as Graph Neural Networks (GNNs)\n\n\n## Installation\n\n### Without PyTorch\n\nThe simplest way to install city2graph is via pip:\n\n```bash\n# Basic installation (without PyTorch)\npip install city2graph\n```\n\nThis installs the core functionality without PyTorch and PyTorch Geometric.\n\n### With PyTorch (CPU)\n\nIf you need the Graph Neural Networks functionality, install with the `cpu` option:\n\n```bash\n# Install with PyTorch and PyTorch Geometric (CPU version)\npip install \"city2graph[cpu]\"\n```\n\nThis will install PyTorch and PyTorch Geometric with CPU support, suitable for development and small-scale processing.\n\n### With PyTorch + CUDA (GPU)\n\nFor GPU acceleration, you can install city2graph with a specific CUDA version extra. For example, for CUDA 12.8:\n\n```bash\n# e.g., for CUDA 12.8\npip install \"city2graph[cu128]\"\n```\n\nSupported CUDA versions are `cu118`, `cu124`, `cu126`, and `cu128`.\n\n**Important:** The PyTorch Geometric extensions (`pyg_lib`, `torch_scatter`, etc.) are not included and must be installed separately. Please refer to the [PyTorch Geometric documentation](https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html) for instructions. Due to the low demand, `conda` distributions are deprecated for PyTorch and PyTorch Geometric. For the most reliable setup, we recommend using pip or uv as described above.\n\n#### For Development\n\nIf you want to contribute to city2graph, you can set up a development environment using `uv`.\n\n```bash\n# Install uv if you haven't already done it\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone the repository\ngit clone https://github.com/c2g-dev/city2graph.git\ncd city2graph\n\n# Install development dependencies with a PyTorch variant (e.g., cpu or cu128)\nuv sync --extra cpu --group dev\n```\n\nYou can then run commands within the managed environment:\n\n```bash\n# Add IPython kernel for interactive development\nuv run ipython kernel install\u200a--name \"your-env-name\"\u200a--user\n\n# Or start Jupyter Notebook\nuv run jupyter notebook\n```\n\n#### Development Environment\n\nThe development dependencies include:\n- `ipython`: Enhanced interactive Python shell with Jupyter kernel support\n- `jupyter` and `notebook`: For running Jupyter notebooks with project-specific kernel\n- `isort`: Code formatting tools\n- `pytest` and `pytest-cov`: Testing tools\n\nThe 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.\n\n## Using Docker Compose\n\nBefore using Docker Compose, ensure you have Docker and Docker Compose installed on your system:\n\n```bash\n# Check Docker installation\ndocker --version\n\n# Check Docker Compose installation\ndocker compose version\n```\n\nIf these commands don't work, you need to install Docker first:\n- For macOS: Install [Docker Desktop](https://www.docker.com/products/docker-desktop)\n- For Linux: Follow the [installation instructions](https://docs.docker.com/engine/install/) for your specific distribution\n- For Windows: Install [Docker Desktop](https://www.docker.com/products/docker-desktop)\n\nOnce Docker is installed, clone the repository and start the containers:\n\n```bash\n# Clone the repository\ngit clone https://github.com/yu-ta-sato/city2graph.git\ncd city2graph\n\n# Build and run in detached mode\ndocker compose up -d\n\n# Access Jupyter notebook at http://localhost:8888\n\n# Stop containers when done\ndocker compose down\n```\n\nYou can customize the services in the `docker-compose.yml` file according to your needs.\n\n## Contributing\n\nWe welcome contributions to the city2graph project! To contribute:\n\n1. **Fork and clone the repository:**\n ```bash\n git clone https://github.com/<your-name>/city2graph.git\n cd city2graph\n git remote add upstream https://github.com/c2g-dev/city2graph.git\n ```\n\n2. **Set up the development environment:**\n ```bash\n uv sync --group dev --extra cpu\n source .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n ```\n\n3. **Create a feature branch:**\n ```bash\n git checkout -b feature/your-feature-name\n ```\n\n4. **Make your changes and test:**\n ```bash\n # Run pre-commit checks\n uv run pre-commit run --all-files\n\n # Run tests\n uv run pytest --cov=city2graph --cov-report=html --cov-report=term\n ```\n\n5. **Submit a pull request** with a clear description of your changes.\n\nFor detailed contributing guidelines, code style requirements, and documentation standards, please see our [Contributing Guide](docs/source/contributing.rst).\n\n## Code Quality\n\nWe maintain strict code quality standards using:\n- **Ruff**: For linting and formatting\n- **mypy**: For static type checking\n- **numpydoc**: For docstring style validation\n\nAll contributions must pass pre-commit checks before being merged.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Transform geospatial relations into graphs for spatial analysis and GNNs.",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/c2g-dev/city2graph/issues",
"Documentation": "https://city2graph.net",
"Homepage": "https://github.com/c2g-dev/city2graph"
},
"split_keywords": [
"graph-neural-networks",
" gtfs",
" mobility",
" overturemaps",
" pytorch-geometric",
" transportation",
" urban"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1af7006ccd8a4a845b60e189ca313f4f01f21e7ddacbb31eb94fee1d20a35313",
"md5": "d8a5cb6d6d8123371e52cfca76e4025b",
"sha256": "b22d6efc2173f8b08690ec3b796b2b43a7581441c7845e723d7220f2e17bc23e"
},
"downloads": -1,
"filename": "city2graph-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8a5cb6d6d8123371e52cfca76e4025b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 95076,
"upload_time": "2025-07-11T23:28:03",
"upload_time_iso_8601": "2025-07-11T23:28:03.772461Z",
"url": "https://files.pythonhosted.org/packages/1a/f7/006ccd8a4a845b60e189ca313f4f01f21e7ddacbb31eb94fee1d20a35313/city2graph-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b833653c8380b92c026f5386f062b3c006d70e0415820cf78e724feb66ad9e2c",
"md5": "c42846d0e09be3f2ddbd45988b1d4eab",
"sha256": "1fcece53e4bdbce34ffed90ce316b08c2a2092a0a0746699066bf5dca3908a71"
},
"downloads": -1,
"filename": "city2graph-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "c42846d0e09be3f2ddbd45988b1d4eab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 55169036,
"upload_time": "2025-07-11T23:28:06",
"upload_time_iso_8601": "2025-07-11T23:28:06.971644Z",
"url": "https://files.pythonhosted.org/packages/b8/33/653c8380b92c026f5386f062b3c006d70e0415820cf78e724feb66ad9e2c/city2graph-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 23:28:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "c2g-dev",
"github_project": "city2graph",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "city2graph"
}
JSON
