Combine drive-time bands into cumulative drive-time areas

Some routing tools return drive-time bands, also called rings: for each site, the area reachable in 0 to 5 minutes, the area reachable in 5 to 10 minutes, and so on. The package uses cumulative areas instead, in which the 10-minute area covers everything reachable within 10 minutes and so contains the 5-minute area. This function makes them by joining each band with the bands of the shorter drive times (their geometric union).

Usage

cacs_rings_to_cumulative(iso_sf, drive_times = NULL)

Arguments

iso_sf

An sf object of polygons in EPSG:4326 (longitude and latitude), with one row for each site and band and a site_id column of strings. The columns isomin and isomax give the drive times, in whole minutes, at which each band starts and ends: isomin must be 0 or more and isomax above isomin. A ring_topology column, if present, must hold only "annulus" (bands) or "cumulative"; it does not change the result.

drive_times

A numeric vector of drive times in minutes, each one of the isomax values, or NULL (the default) for all of them. Every site must have a band that ends at each of these drive times.

Value

An sf object with one row for each site and drive time, sorted by site_id and then by drive time. The geometry, in a column named geometry, is the union of the bands up to that drive time. The other columns are copied from the band that ends at that drive time, except four: isomin is set to 0, isomax and drive_time_min to the drive time, and ring_topology to "cumulative". cacs_intersect_weight() and cacs_run() also need the other columns of a cacs_isochrone() result; cacs_validate_iso() lists any that are missing.

Details

For each site and drive time, the bands that end at or before that drive time are joined. If all of them start at 0, the rows are taken to be cumulative areas already; otherwise they must run from 0 to that drive time without a gap in minutes, or the function gives an error. The geometries are not compared, so bands that overlap or leave gaps between them are joined as they are.

See also

cacs_isochrone(), which returns cumulative areas, and cacs_validate_iso(), which checks drive-time areas from other sources.

Examples

# Two bands for one site: 0 to 5 minutes and 5 to 10 minutes
poly <- function(xmin, xmax, ymin, ymax) {
  sf::st_polygon(list(rbind(
    c(xmin, ymin),
    c(xmax, ymin),
    c(xmax, ymax),
    c(xmin, ymax),
    c(xmin, ymin)
  )))
}

bands <- sf::st_sf(
  site_id = c("A", "A"),
  isomin = c(0L, 5L),
  isomax = c(5L, 10L),
  geometry = sf::st_sfc(
    poly(0, 1, 0, 1),
    poly(1, 2, 0, 1),
    crs = 4326
  )
)

# The 10-minute area is the union of the two bands
cumulative <- cacs_rings_to_cumulative(bands, drive_times = c(5, 10))
sf::st_drop_geometry(cumulative)[
  , c("site_id", "isomin", "isomax", "drive_time_min", "ring_topology")
]
#>   site_id isomin isomax drive_time_min ring_topology
#> 1       A      0      5              5    cumulative
#> 2       A      0     10             10    cumulative
unique(cumulative$ring_topology)
#> [1] "cumulative"