Check drive-time areas and list the problems found

Checks whether an object can be used as drive-time areas (isochrones) by cacs_intersect_weight(), or by cacs_run() through its precomputed_isochrones argument, and returns a table with one row for each problem found. Those two functions stop with an error at the first of these problems. cacs_run() checks at the start only that precomputed_isochrones is an sf object, and makes the other checks after the download step.

Usage

cacs_validate_iso(iso_sf)

Arguments

iso_sf

An sf object of drive-time areas with one row for each site and drive time, or any other object to check.

Value

A tibble with one row for each problem, and no rows when every check passes. Its seven columns are strings:

severity

Always "error".

check

A short name for the check, such as "iso_crs".

col

The column concerned, or NA.

actual, expected

What was found, and what is required.

fix_hint, example

A suggested fix, and a line of R code for it, written for an object named iso_sf.

Details

The object must be an sf object; if it is not, that is the only problem reported. It must have the 16 columns of the result of cacs_isochrone(), with ring_topology equal to "cumulative" in every row, meaning that each area contains the areas of the shorter drive times. An isomin column, if present, must be 0 in every row (see cacs_rings_to_cumulative()). The coordinate reference system must be EPSG:4326, and the geometry type POLYGON or MULTIPOLYGON. provider and provider_requested must be "osrm", "ors", "mapbox", or "r5r", and site_id must hold strings that are neither missing nor empty. drive_time_min must be above 0, drive_time_min and retry_count must be stored as integers, and isochrone_empty and provider_downgrade must be logical.

The areas themselves are not compared, so a 5-minute area larger than the 10-minute area of the same site passes. So does a site and drive time that appears in two rows, which cacs_intersect_weight() turns into a row of NA values. The function gives an error only for an sf object without a usable geometry column, such as one made by selecting rows with [ before the sf package is loaded.

Areas made with another tool, such as the result of cacs_rings_to_cumulative(), can be used once the missing columns hold the values that cacs_isochrone() gives an area built without a problem (see its Value section). NA in isochrone_empty and "" in failure_reason pass the checks here, but cacs_run() treats an area as a routing failure unless its isochrone_empty is FALSE and its failure_reason is NA.

See also

Other validation and conditions: cacs_acs_validate(), cacs_capture_conditions(), cacs_validate_osrm_endpoint(), catchmentACS-conditions

Examples

# The drive-time areas bundled with the package: no problems, no rows
iso <- readRDS(system.file("extdata", "legacy_2025_isochrones.rds",
                           package = "catchmentACS"))
cacs_validate_iso(iso)
#> # A tibble: 0 × 7
#> # ℹ 7 variables: severity <chr>, check <chr>, col <chr>, actual <chr>,
#> #   expected <chr>, fix_hint <chr>, example <chr>

# Drive times stored as decimal numbers instead of integers
iso$drive_time_min <- as.numeric(iso$drive_time_min)
cacs_validate_iso(iso)
#> # A tibble: 1 × 7
#>   severity check               col            actual   expected fix_hint example
#>   <chr>    <chr>               <chr>          <chr>    <chr>    <chr>    <chr>  
#> 1 error    iso_drive_time_type drive_time_min <numeri… integer  Store d… iso_sf…