IduEdu

IduEdu is an open-source Python toolkit for building and analyzing multimodal city networks from OpenStreetMap and local GTFS Schedule data. It downloads OSM data via Overpass, reads GTFS feeds, builds drive, walk, public-transport and intermodal networks, and stores them as UrbanGraph objects backed by GeoDataFrame node and edge tables.

Benchmark snapshot

The benchmark below isolates city-scale pedestrian graph construction, comparing IduEdu's tabular UrbanGraph representation with OSMnx's widely used NetworkX-backed workflow on the same area of interest for each city. Both simplification modes are shown because simplify changes the trade-off between graph-construction time and the size of the resulting graph.

Across these repeated B1 runs, IduEdu built pedestrian graphs in about 5.8-9.3x less time without simplification and 3.3-6.0x less time with simplification enabled. The resulting geospatial graph object had a 10-12x lower deterministic representation-size estimate. Edge-row counts are shown as a representation detail: UrbanGraph can keep bidirectional walking edges as one row with a direction flag, while NetworkX-style directed multigraphs store separate directed edge rows.

Full protocol notes, limitations and raw-result links are in the benchmark documentation.

Documentation

Full documentation is published at https://iduclub.github.io/IduEdu/. Migrating from the old NetworkX-first API? See the UrbanGraph migration guide. Runnable examples are available for graph construction, UrbanGraph basics, object projection, and shortest paths.

Features

• Store graph topology, geometry, CRS and edge weights in UrbanGraph, a GeoDataFrame-native graph model.
• Build drive and walk graphs from OpenStreetMap with local metric projection and optional simplification.
• Build static public-transport graphs directly from OSM relations for bus, trolleybus, tram and subway.
• Build static public-transport graphs from local GTFS Schedule directories or ZIP archives, using timetable headways for boarding weights and shapes or straight-line fallbacks for route geometry.
• Combine pedestrian and public-transport layers into one intermodal graph by projecting stops, platforms and station access points onto the walking network.
• Compute shortest paths and OD matrices with Numba-backed CSR routines, cutoff thresholds and adaptive graph reversal for unbalanced origin-destination sets.
• Work with connected, weakly connected and strongly connected UrbanGraph components.
• Convert to and from NetworkX through optional compatibility utilities.
• Snap geometries to graph nodes with nearest_nodes and validate custom graph edits.
• Store graphs as .urbangraph archives with parquet tables and metadata.
• Cache Overpass responses and query historical OSM snapshots.

Installation

pip install iduedu

IduEdu requires Python 3.11 or 3.12. The core package uses the standard geospatial stack including GeoPandas, Shapely, PyProj, NumPy, Pandas and SciPy. NetworkX utilities are optional compatibility helpers.

Use pip install "iduedu[io]" to enable .urbangraph parquet archive read/write helpers.

Quickstart

Build an intermodal graph

from iduedu import get_intermodal_graph

graph = get_intermodal_graph(
    osm_id=1114252,  # for example, Saint Petersburg's Vasileostrovsky District
    pt_kwargs={"transport_types": ["bus", "tram", "subway"]},
)

print(graph.nodes_gdf.head())
print(graph.edges_gdf.head())

Graph builders return UrbanGraph. Nodes are stored in graph.nodes_gdf; edges are stored in graph.edges_gdf and include u, v, geometry, length_meter and time_min.

OSM-based boarding waits are mode-specific defaults stored in TransportRegistry. GTFS boarding waits are derived from the selected feed schedule instead.

Build a public-transport graph from GTFS

from iduedu import get_gtfs_public_transport_graph

pt_graph = get_gtfs_public_transport_graph(
    "feed.zip",
    service_date="2026-08-04",
    start_time="07:00:00",
    end_time="10:00:00",
)

The source can be a GTFS directory or ZIP archive. See the GTFS guide for schedule aggregation, geometry fallbacks, single-departure handling and intermodal joining.

Compute an OD matrix

from iduedu import od_matrix

nodes = graph.nodes_gdf.index.to_list()

matrix = od_matrix(
    graph,
    origins_nodes=nodes[:5],
    destination_nodes=nodes[5:15],
    weight="time_min",
    threshold=30,
)

print(matrix)

Use weight="time_min" for travel time in minutes or weight="length_meter" for distance in meters. Pairs without a path, or outside threshold, are returned as inf.

Work with graph components

from iduedu import largest_component, subgraph_by_nodes

component_nodes = largest_component(graph)
main_graph = subgraph_by_nodes(graph, component_nodes)

Public API

Common entry points are available directly from iduedu:

• Builders: get_drive_graph, get_walk_graph, get_public_transport_graph, get_gtfs_public_transport_graph, get_intermodal_graph.
• Graph model: UrbanGraph, UrbanGraphChanges.
• Editing and transforms: clip_urban_graph, join_urban_graphs, project_objects2urban_graph, relabel_urban_graph, simplify_multiedges, to_directed, to_undirected.
• Graph utilities: nearest_nodes, validate_graph, UrbanGraph.nearest_nodes, UrbanGraph.validate.
• Graph IO: read_urban_graph, write_urban_graph, UrbanGraph.read, UrbanGraph.write.
• Components: connected_components, weakly_connected_components, strongly_connected_components, largest_component.
• Shortest paths and matrices: single_source_dijkstra_path, multi_source_dijkstra_path, path_to_edges, single_source_dijkstra_path_length, multi_source_dijkstra_path_length, multi_source_dijkstra_nearest_source, dijkstra_path_length_parallel, od_matrix.
• Optional NetworkX helpers: graph2gdf, gdf2graph, read_gml, write_gml, clip_nx_graph, reproject_graph.

Configuration

from iduedu import config

config.set_overpass_url("https://overpass-api.de/api/interpreter")
config.set_timeout(120)
config.set_rate_limit(min_interval=1.0, max_retries=3, backoff_base=0.5)
config.set_enable_tqdm(True)
config.configure_logging(level="INFO")

Overpass cache

Overpass caching is enabled by default and uses .iduedu_cache in the current working directory.

from iduedu import config

config.set_overpass_cache(enabled=False)
config.set_overpass_cache(cache_dir="/tmp/overpass_cache", enabled=True)

Environment variables:

export OVERPASS_CACHE_DIR="/tmp/overpass_cache"
export OVERPASS_CACHE_ENABLED="1"

Historical snapshots

from iduedu import config

config.set_overpass_date(date="2020-01-01")
config.set_overpass_date(year=2020, month=5)
config.set_overpass_date()  # reset to current OSM data

When a historical date is set, detailed subway stop-area queries may be skipped because Overpass does not always support those relation patterns at arbitrary timestamps.

Development

This project uses uv.

uv sync --all-groups

Useful commands:

make test           # fast tests, no network
make test-network   # Overpass/network tests
make test-all       # all tests
make coverage       # terminal coverage for fast tests
make coverage-xml   # CI coverage, includes network tests
make format-check
make lint
make docs

See CONTRIBUTING.md for the full development, testing, Conventional Commits and release workflow.

Releases

Releases are automated from Conventional Commit messages on the official IDUclub/IduEdu main branch using python-semantic-release. Do not bump versions or create tags manually. The single source of truth for the package version is iduedu/_version.py; pyproject.toml reads it dynamically at build time.

Contacts

• NCCR - National Center for Cognitive Research
• IDU - Institute of Design and Urban Studies
• Natalya Chichkova - project manager
• Danila Oleynikov (Donny) - lead software engineer

Acknowledgments

Реализовано при финансовой поддержке Фонда поддержки проектов Национальной технологической инициативы в рамках реализации "дорожной карты" развития высокотехнологичного направления "Искусственный интеллект" на период до 2030 года (Договор № 70-2021-00187)

This research is financially supported by the Foundation for National Technology Initiative's Projects Support as a part of the roadmap implementation for the development of the high-tech field of Artificial Intelligence for the period up to 2030 (agreement 70-2021-00187)

License

IduEdu is distributed under the BSD 3-Clause License. See LICENSE.txt for details.

Publications

Coming soon...