osm-chordify

Download, filter, and export OSM road networks using population-density-based boundaries. Intersect the resulting geometries with polygon grids (TAZ, census tracts, ISRM cells, etc.) and map them to BEAM/MATSim simulation network.

No AI Training Use: The contents of this repository may not be used to train, fine-tune, evaluate, benchmark, or improve machine learning or artificial intelligence models without prior written permission. See NOAI.

Installation

Requires Python 3.10+.

From PyPI:

pip install osm-chordify

From GitHub:

pip install git+https://github.com/LBNL-UCB-STI/osm-chordify.git

For development:

git clone https://github.com/LBNL-UCB-STI/osm-chordify.git
cd osm-chordify
pip install -e ".[dev]"

U.S. Census API key

build_osm_by_pop_density uses the U.S. Census Bureau API to fetch population data for density-based filtering. Set your API key as an environment variable:

export CENSUS_API_KEY="your_key_here"

To make it persistent, add the line above to your ~/.bashrc, ~/.zshrc, or .env file.

Get a free key at https://api.census.gov/data/key_signup.html.

You can also pass the key directly to the example scripts with --census-api-key.

API

from osm_chordify import (
    build_area_mask_from_counties,
    build_osm_by_pop_density,
    create_osm_highway_filter,
    intersect_polygons_with_zones,
    intersect_road_network_with_county_zones,
    intersect_road_network_with_zones,
    spatial_left_join_with_zones,
    intersect_zones_with_zones,
    map_osm_with_beam_network,
)

Core functions:

• build_area_mask_from_counties: build a fused county-based land mask or whole-area mask from FIPS codes
• build_osm_by_pop_density: build a multi-layer OSM network from county / tract / CBG boundaries and density filters
• intersect_polygons_with_zones: cascade an already-intersected polygon layer into a new zone layer
• intersect_road_network_with_county_zones: intersect a network with county polygons fetched by state/county FIPS codes
• intersect_road_network_with_zones: intersect network edges with zone polygons
• spatial_left_join_with_zones: spatially left-join any geometry layer with zone attributes while keeping unmatched rows
• intersect_zones_with_zones: intersect one polygon zone layer with another
• map_osm_with_beam_network: join BEAM network attributes onto OSM geometries

Intersection outputs always include:

• proportion
• link_length_m

These columns always describe the latest intersection step. In chained intersections, earlier polygon columns are carried forward unchanged, and only the current step adds new unlabeled or <label>_... metrics plus the new zone attributes.

For dense grids, intersect_road_network_with_zones(...) can optionally prefilter zones to the overall road-network bounding box before exact intersection:

• prefilter_zones_to_network_bbox=False disables the prefilter
• prefilter_zones_to_network_bbox=True keeps only zones intersecting the network bounding box

This reduces the zone set before exact intersection and shows a dedicated Filtering zones progress bar. Zones kept by the bounding-box prefilter that still contain no intersecting link pieces are preserved instead of being dropped; the fixed numeric intersection columns remain null for those rows.

For rectangular or polygon link workflows, use intersect_polygons_with_zones(...). It computes overlap proportions from polygon area, derives <label>_link_length_m (or link_length_m without a label) from the source polygon length column, and prefilters zones to the input-layer bounding box by default.

For cascading polygon workflows, use:

• intersect_polygons_with_zones(...)
  • preserves all existing columns from the input polygon layer
  • adds new zone attributes with a label prefix such as inmap_* or aermod_*
  • computes current-step metrics:
    • <label>_proportion
    • <label>_link_length_m
• spatial_left_join_with_zones(...)
  • keeps all input rows
  • appends zone attributes where matched, using a label prefix such as county_*
  • leaves zone columns null where no zone intersects

Mask generation semantics:

• include_water=False
  • land mask
  • uses shoreline-clipped cartographic county boundaries
  • fuses counties without taking a convex hull
  • optional buffer_m is applied to that non-convex land geometry
• include_water=True
  • whole-area mask
  • uses full TIGER/Line county boundaries
  • takes the convex hull of the fused counties
  • optional buffer_m is applied to that convex whole-area geometry

Networks can be exported as GraphML, PKL, GPKG, OSM XML, OSM PBF, and GeoJSON.

You can also run the main workflows via CLI:

python -m osm_chordify.main --help

Examples

See the examples/ directory for complete, runnable scripts:

For commands, output layout, validation behavior, and project structure, see docs/USAGE.md.