Library · Noun reference

roads

Mapped road features with provider-native geometry, identifiers, and classes.

Quick facts

Fact	Value
Semantic type	Vector features
Units	Geometry in WGS84 degrees; project explicitly before measuring distance
Source flavors	overture, osm
Access	Explicit bounded acquisition; optional offline snapshot replay

Usage

from cubedynamics.data.roads import roads

roads(*, source, bbox, release=None, snapshot_dir=None, offline=False)

The signature above is generated from the installed loader. Call acquisition before composing the analysis pipe.

Arguments

Argument	Meaning	Default
source	overture or osm; preserves each provider's classes.	required
bbox	WGS84 west, south, east, north; <=0.02° per side.	required
release	Explicit release required for Overture; not accepted for rolling OSM.	None
snapshot_dir	Optional new directory to retain exact responses; use a new directory for a live refresh.	None
offline	Replay verified snapshots only; never download missing content.	False

Available sources

Source	Coverage	Resolution	Time
overture	Release-covered areas; bounded small-area queries	Native vector segments	Explicit release, e.g. 2026-08-19.0
osm	Small query areas through Overpass	Native OSM way geometry	Rolling snapshot at retrieval; timestamp retained

Differences among source flavors

Overture uses a pinned release; OSM is a rolling mapped snapshot. Native identifiers, classes, and segmentation differ and are not silently harmonized. Overture incorporates OSM, so agreement is not independent ground truth. Both remain vector features; neither implies traffic, legal access, or routing connectivity.

Returned data

A WGS84 geopandas.GeoDataFrame. Columns include geometry, source, source_feature_id, source_classification, name, and the complete provider record in native JSON. Attributes retain query bounds, source mode, interpretation contract and acquisition provenance. Features remain un-clipped until you explicitly clip them.

Order / grammar behavior

Use GeoPandas operations inside ordinary pipe callables or project-owned verbs. The lesson defines within_area and length_by_class; these are not new built-in verbs. Raster/time-series verbs and the cube viewer are not interchangeable with a vector workflow.

Minimal reproducible example

Live acquisition below requires network access and the source's optional dependencies. The complete offline lesson uses checksum-verified real inputs and shows a plot at every step.

from cubedynamics.data.roads import roads
import matplotlib.pyplot as plt

frame = roads(source="overture", release="2026-08-19.0",
              bbox=(-105.285, 40.008, -105.270, 40.020))
frame.plot()
plt.show()

See the data

These are mapped features, not evidence of traffic or road condition. Overture incorporates OSM; apparent agreement is not independent validation.

Code and interpretation · Figure and input hashes

Quality and provenance

Implemented and documented here as a scientific noun. Operational certification remains bounded: no production serving revision has been assigned. Retained real-data samples, numerical/schema checks, and replay tests are distinct from broad scientific suitability or live-service guarantees.

overture: 5,000 features; 3 partitions; 4 row groups per partition; 400 requests / 40 MB bodies / 300 s. Install cubedynamics[roads] for PyArrow. Native classes/segmentation retained; not routing or completeness certification.
osm: 5,000 features; 6 requests / 4 MB bodies / 90 s. Ways require a node inside the bbox: long crossing ways may be absent. Public Overpass is not a sustained application backend. No automatic road-class crosswalk.

Validation evidence and release gates. No automatic source switching or synthetic substitution.