Routing control parameters

Creates a control object for travel-time computation in compute_travel_times(). All parameters have sensible defaults; override only what you need.

Usage

routing_control(
  mode = "AUTO",
  point_method = "pop_weighted",
  min_area_for_pop_weight = 1,
  max_trip_duration = 120L,
  fallback_max_trip_duration = 90L,
  unreachable_threshold = 0.01,
  n_threads = 4L,
  gtfs_zip_path = NULL,
  departure_datetime = NULL,
  pop_raster = NULL,
  osm_buffer_km = 10,
  fill_missing = NULL
)

Arguments

mode

Character. Routing mode, using r5r convention: "AUTO" (default), "WALK", "BICYCLE", "CAR", "TRANSIT", or combinations like c("WALK", "TRANSIT"). Passed directly to r5r::travel_time_matrix().

When mode = "AUTO", routing first tries "WALK" with max_trip_duration. If the fraction of tracts with no reachable station exceeds unreachable_threshold, the entire matrix is re-computed with "CAR" and fallback_max_trip_duration. Travel times in the returned matrix are always from a single mode — never mixed. For municipalities with large rural areas or complex geography (rivers, forests), CAR mode may provide better coverage; AUTO handles this automatically.

point_method

Character. Method for computing representative points of census tracts. One of "pop_weighted" (default, uses WorldPop raster), "point_on_surface", or "centroid". See compute_representative_points().

min_area_for_pop_weight

Numeric. Minimum tract area in km2 for applying the pop_weighted method. Smaller tracts fall back to point_on_surface. Default: 1.

max_trip_duration

Integer. Maximum trip duration in minutes. Pairs beyond this threshold are not routed and receive zero weight. Default: 120 (2 hours walking). In AUTO mode, this is used for the initial WALK attempt.

fallback_max_trip_duration

Integer. Maximum trip duration in minutes for the CAR fallback when mode = "AUTO". Ignored for other modes. Default: 90 (1.5 hours driving).

unreachable_threshold

Numeric between 0 and 1. Fraction of tracts that must be unreachable (zero reachable stations) to trigger the WALK-to-CAR switch in AUTO mode. Ignored for other modes. Default: 0.01 (1%).

n_threads

Integer. Number of parallel threads for the r5r routing engine. Default: 4.

gtfs_zip_path

Character or NULL. Path to a GTFS .zip file for transit routing. Copied into the network directory so r5r can auto-detect it. Default: NULL.

departure_datetime

POSIXct or NULL. Departure time for transit-based routing. Required when mode includes transit. Default: NULL.

pop_raster

A terra::SpatRaster, file path to GeoTIFF, or NULL. Population raster for point_method = "pop_weighted". If NULL, WorldPop data is auto-downloaded. Default: NULL.

osm_buffer_km

Numeric. Buffer in km around the combined bounding box of tracts and points when clipping OSM data. Default: 10.

fill_missing

Numeric, NA, or NULL. Value for unreachable OD pairs. NA (default when NULL) leaves unreachable pairs as NA in the travel time matrix, which maps to exactly zero weight in the weight matrix. These pairs are immune to alpha optimization. Set to a numeric value (e.g., max_trip_duration) to impute a travel time instead.

Value

A list of class "interpElections_routing_control" with one element per parameter.

Examples

# Default settings (AUTO mode: walk first, car fallback if needed)
routing_control()
#> interpElections routing control:
#>   mode: AUTO 
#>   fallback_max_trip_duration: 90 min
#>   unreachable_threshold: 1% 
#>   point_method: pop_weighted 
#>   min_area_for_pop_weight: 1 
#>   max_trip_duration: 120 min
#>   n_threads: 4 
#>   gtfs_zip_path: NULL 
#>   departure_datetime: NULL 
#>   pop_raster: NULL (auto-download) 
#>   osm_buffer_km: 10 
#>   fill_missing: NA 

# Explicit walking mode (no fallback)
routing_control(mode = "WALK")
#> interpElections routing control:
#>   mode: WALK 
#>   point_method: pop_weighted 
#>   min_area_for_pop_weight: 1 
#>   max_trip_duration: 120 min
#>   n_threads: 4 
#>   gtfs_zip_path: NULL 
#>   departure_datetime: NULL 
#>   pop_raster: NULL (auto-download) 
#>   osm_buffer_km: 10 
#>   fill_missing: NA 

# Transit mode with GTFS
routing_control(
  mode = c("WALK", "TRANSIT"),
  gtfs_zip_path = "sptrans.zip",
  departure_datetime = as.POSIXct("2022-10-02 10:00:00")
)
#> interpElections routing control:
#>   mode: WALK;TRANSIT 
#>   point_method: pop_weighted 
#>   min_area_for_pop_weight: 1 
#>   max_trip_duration: 120 min
#>   n_threads: 4 
#>   gtfs_zip_path: sptrans.zip 
#>   departure_datetime: 2022-10-02 10:00:00 
#>   pop_raster: NULL (auto-download) 
#>   osm_buffer_km: 10 
#>   fill_missing: NA 

# AUTO mode with more lenient threshold (10% unreachable to trigger CAR)
routing_control(unreachable_threshold = 0.10)
#> interpElections routing control:
#>   mode: AUTO 
#>   fallback_max_trip_duration: 90 min
#>   unreachable_threshold: 10% 
#>   point_method: pop_weighted 
#>   min_area_for_pop_weight: 1 
#>   max_trip_duration: 120 min
#>   n_threads: 4 
#>   gtfs_zip_path: NULL 
#>   departure_datetime: NULL 
#>   pop_raster: NULL (auto-download) 
#>   osm_buffer_km: 10 
#>   fill_missing: NA 

# Bicycle with centroid-based points
routing_control(mode = "BICYCLE", point_method = "centroid")
#> interpElections routing control:
#>   mode: BICYCLE 
#>   point_method: centroid 
#>   min_area_for_pop_weight: 1 
#>   max_trip_duration: 120 min
#>   n_threads: 4 
#>   gtfs_zip_path: NULL 
#>   departure_datetime: NULL 
#>   pop_raster: NULL (auto-download) 
#>   osm_buffer_km: 10 
#>   fill_missing: NA

Usage

Arguments

Value

See also

Examples