iduedu.get_drive_graph

iduedu.get_drive_graph(*, osm_id=None, territory=None, simplify=True, add_road_category=True, clip_by_territory=False, keep_largest_subgraph=True, network_type='drive', custom_filter=None, osm_edge_tags=None, keep_edge_geometry=True)[source]

Build a drivable road network (nx.MultiDiGraph) from OpenStreetMap within a given territory.

The function downloads OSM ways via Overpass, segments them into directed edges, optionally merges contiguous segments, duplicates two-way streets in reverse, and computes per-edge length (meters) and travel time (minutes). Node coordinates are unique line endpoints in a local projected CRS. Edge attributes can include selected OSM tags and a derived road category/speed.

Parameters:

  • osm_id (int | None) – OSM relation/area ID of the territory boundary. Provide this or territory.

  • territory (Polygon | MultiPolygon | gpd.GeoDataFrame | None) – Boundary geometry in EPSG:4326 or GeoDataFrame. Used when osm_id is not given.

  • simplify (bool) – If True, merges contiguous collinear segments and transfers attributes back to merged lines using nearest midpoints. If False, keeps raw per-segment edges.

  • add_road_category (bool) – If True, adds a derived category (e.g., local/regional/federal) and a default speed (maxspeed_mpm) inferred from the OSM highway class.

  • clip_by_territory (bool) – If True, clips edges by the exact boundary geometry before graph construction.

  • keep_largest_subgraph (bool) – If True, returns only the largest strongly connected component.

  • network_type (Literal[``”drive”:py:class:`,`”drive_service”:py:class:`,`”custom”``]) – Preset of Overpass filters to select drivable ways. Use “custom” together with custom_filter to pass your own Overpass way filter.

  • custom_filter (str | None) – Custom Overpass filter (e.g., [“highway”~”motorway|trunk|…”]) used when network_type=”custom”.

  • osm_edge_tags (list[str] | None) – Which OSM tags to retain on edges. Overrides defaults from config. The tags oneway, maxspeed, and highway are always added.

  • keep_edge_geometry (bool) – If True, stores shapely geometries on edges (geometry attribute).

Returns:

Directed multigraph of the road network. Each edge carries:

  • geometry (if keep_edge_geometry=True) in local CRS,

  • length_meter (float), time_min (float),

  • type=”drive”,

  • selected OSM tags (incl. highway, maxspeed, oneway, optional category, etc.).

Graph-level attributes: graph[“crs”] (local projected CRS), graph[“type”] (network_type).

Return type:

(nx.MultiDiGraph)

Raises:

ValueError – If network_type is unknown, or network_type=”custom” without custom_filter.