city2graph operating router

Use this skill for the public city2graph package when a task turns geospatial features or local mobility/transit data into graph tables, graph libraries, or PyTorch Geometric objects. The package is GeoDataFrame-first: preserve stable IDs in indexes, preserve CRS, and inspect typed output dictionaries before converting representations.

Route by the user's starting point

• Graph representation, metadata, NetworkX/rustworkx/PyG, heterogeneous relations, or metapaths: read graph-conversion.
• Point/polygon spatial relations, proximity, contiguity, reachability, isochrones, tessellation, clipping, dual graphs, or topology cleanup: read spatial-topology.
• Building footprints plus movement segments, tessellation barriers, place/movement composition, or multi-distance morphology: read urban-morphology.
• OD matrices, local GTFS/GBFS feeds, dated stop legs, or transit summary graphs: read mobility-and-transport.
• Overture area/place resolution, controlled layer acquisition, clipping, connector splitting, or passable segment preprocessing: read data-ingestion.

For compound tasks, start with the ingestion or graph-construction route that matches the input, then hand the resulting GeoDataFrame tables to urban-morphology, spatial-topology, or graph-conversion as appropriate. The sibling skills are the detailed operating graph; this file stays a router.

Shared operating contract

1. Inspect the input representation and decide whether it is homogeneous or typed. Do not merge node types whose ID namespaces are intentionally separate.
2. Establish a CRS before metric operations. Use WGS84 for Overture download bounds, but use a suitable projected CRS for lengths, distances, buffers, tessellation, network budgets, and morphology.
3. Keep GeoDataFrame indexes as the canonical node/edge ID contract: node IDs come from node indexes, and edge endpoints are the first two levels of an edge MultiIndex. Verify endpoint membership and CRS consistency before conversion.
4. Make direction, reciprocal-edge, multigraph-key, self-loop, threshold, geometry, and optional-dependency choices explicit. Do not infer them from a downstream graph class after the fact.
5. Prefer local fixtures and in-memory data for reproducible checks. Live Overture/Nominatim/GTFS/GBFS access, remote releases, and large downloads are runtime prerequisites rather than required offline verification.
6. Preserve metadata and provenance: record package version, source data/feed paths, CRS, ID columns, filters, warning conditions, and parameters. Keep graph_metadata on PyG objects and graph metadata on NetworkX objects when round-tripping.
7. Treat as_nx compatibility arguments as deprecated where the package says so; prefer returning GeoDataFrames and then calling the shared conversion utilities.

Installation and capability gates

Install the public package in a fresh environment with the smallest capability set that matches the task:

python -m pip install city2graph
# Add CPU PyTorch Geometric support only when tensor conversion is needed:
python -m pip install 'city2graph[cpu]'

A minimal core import check is:

python -c "import city2graph; print(city2graph.__version__)"

For the PyG route, also import torch and torch_geometric, then run a tiny CPU conversion before selecting any other device. Probe optional dependencies before use rather than claiming that every installation supports every backend. The CPU PyG route is covered by the companion verification artifacts; CUDA, ROCm, and MPS are optional and must not be inferred from a CPU import.

Cross-cutting installation, CRS, schema, optional-dependency, data-source, and representation failures are summarized in references/troubleshooting.md. Package snapshot and routing metadata are in references/repo-provenance.md and references/repo-routing-metadata.json.

Handoff checklist

Before handing a result to analysis or a downstream graph library, confirm:

• the selected sub-skill owns the workflow and its references were read;
• every non-empty layer has the intended CRS and compatible geometry types;
• node and edge IDs/index names are stable and endpoints resolve;
• output relation keys, directionality, edge counts, weights, and geometry semantics match the request;
• optional dependencies and device selection were probed explicitly;
• warnings, empty/fallback results, external-service assumptions, and any unverified backend are recorded rather than hidden.

This generated skill is self-contained and does not require the original repository checkout, its notebooks, its test fixtures, or a live external service at runtime.