Updating code written for version 0.3

The value of the expression in cacs_capture_conditions()

cacs_capture_conditions() evaluates an expression and returns a table of the messages and warnings of catchmentACS given while it runs. In 0.3 it returned only that table. An assignment inside the expression, as in cacs_capture_conditions(result <- cacs_run(site_07, state = "AL")), does not keep the value, because the expression is evaluated in a new environment.

From 0.4 on, return_value = "both" returns a list with the value of the expression, result, and the table, conditions:

out <- cacs_capture_conditions(
  cacs_run(site_07, state = "AL",
           precomputed_isochrones = iso_07, acs = acs),
  return_value = "both"
)
result <- out$result
table(out$conditions$class)

#> 
#>         catchmentACS_message_progress catchmentACS_message_progress_summary 
#>                                     5                                     3

The captured conditions here are the progress messages of cacs_run(), which are not shown. The default is still return_value = "conditions", and options(catchmentACS.capture_return_value = "both") changes it for the session.

The approach used with 0.3, an assignment with <<- inside the expression, still works. R assigns the value to the first variable of that name that it finds, searching from the environment in which cacs_capture_conditions() is called, and creates the variable in the global environment when there is none (?assignOps). Inside a function, creating the variable first, as with result <- NULL, keeps the value in the function.

Drive-time areas built on the public OSRM server

With the Open Source Routing Machine (OSRM), the default routing service, cacs_isochrone() used res = 70L in 0.3 when res was not given. Since 0.4, it uses res = 30L with osrm_mode = "demo", the default, which sends the requests to the public OSRM demo server, and still res = 70L with osrm_mode = "docker".

The coarser grid sends fewer requests, so the demo server is less likely to respond with HTTP status 429 (too many requests), but it can give different areas, and so different estimates. To keep the grid of a 0.3 script, set res = 70L in the call to cacs_isochrone(), or iso_args = list(res = 70L) in cacs_run():

# Needs the osrm package and an internet connection.
iso_70 <- cacs_isochrone(site_07, drive_times = c(5, 10, 15), res = 70L)

options(catchmentACS.osrm_demo_budget_protect = FALSE) makes res = 70L the default with both values of osrm_mode. cacs_validate_osrm_endpoint(), added in 0.4, checks whether an OSRM server is accepting requests before the areas are built. ?cacs_isochrone describes the grid and the waiting time on the demo server, and vignette("providers", package = "catchmentACS") describes the servers and this check.

The isochrone column of the list-column form

With output = "list_column", cacs_run() returns a row for each site and drive time, with the ACS estimates and the rates in list-columns of tibbles. In 0.3, its column isochrone held NULL. Since 0.4, it holds the drive-time area of the row, as a one-row sf object, when the areas are supplied through precomputed_isochrones, and since 0.5.0 also when cacs_run() builds them:

by_area <- cacs_run(
  site_07, state = "AL", precomputed_isochrones = iso_07, acs = acs,
  output = "list_column", verbose = FALSE
)
class(by_area$isochrone[[1]])

#> [1] "sf"         "tbl_df"     "tbl"        "data.frame"

The same holds for the element list_column of the result with output = "both". Code that kept the areas next to the result, for example to map them, can take them from this column.

The row order of as_tibble()

In 0.3, tibble::as_tibble() returned the rows of a result of cacs_run() in their order. Versions 0.4 to 0.5.1 sorted them by site_id, drive_time_min, and variable, with the rows of the five rates first for each site and drive time. Version 0.6.0 keeps the rows in their order again, and rate_first = TRUE sorts them in the same way as 0.4 to 0.5.1:

head(tibble::as_tibble(result)$variable)

#> [1] "B01003_001" "B11001_001" "B17001_001" "B17001_002" "B19013_001"
#> [6] "B19056_001"

head(tibble::as_tibble(result, rate_first = TRUE)$variable)

#> [1] "labor_force_participation" "poverty_rate"             
#> [3] "snap_rate"                 "ssi_rate"                 
#> [5] "unemp_rate"                "B01003_001"

Code written for 0.3 that selects rows by their position after tibble::as_tibble() gets them in the order of the result, as it did with 0.3. options(catchmentACS.rate_first_default = TRUE) makes tibble::as_tibble() put the rate rows first without rate_first, but only when it is called from code run in the global environment, such as the console, a script, or a document; a message says so the first time in a session.

Functions of other packages that convert a result with tibble::as_tibble() keep the order, even with that option, so dplyr::left_join(), dplyr::semi_join(), dplyr::anti_join(), tidyr::pivot_wider(), and dplyr::summarise() or dplyr::reframe() after dplyr::rowwise() work on a result as on any other table (?as_tibble.cacs_run_result). In 0.4 to 0.5.1, these functions got the sorted rows unless options(catchmentACS.rate_first_default = FALSE) was set. dplyr::semi_join() and dplyr::anti_join() could then return the wrong rows, and summaries after dplyr::rowwise() with grouping variables could have the wrong labels, without a warning; such results should be computed again.

Rates by site in summary(), print(), and Markdown tables

From 0.4 on, summary() of a result also has the elements rates_per_site and rates_per_site_moe, tables of the five rates with a row for each site and drive time (site_id and drive_time_min). In rates_per_site_moe, each cell gives the estimate and its margin of error (MOE), the half-width of its confidence interval at the 90 percent level by default. print() shows the first table for results with at most getOption("catchmentACS.summary_per_site_max") sites, 12 by default, and cacs_summary_as_markdown() formats either table as Markdown:

cacs_summary_as_markdown(summary(result)$rates_per_site_moe)

None of these additions requires a change to 0.3 code.

Values in rates_breakdown before 0.4

In 0.2 and 0.3, the rows of the element rates_breakdown of summary() were shifted by one: the mean, standard deviation, and count of missing values shown for each rate belonged to another rate. Since 0.4, dplyr::group_by() has a method for results of cacs_run(), which have the class cacs_run_result: group_by(cacs_run_result, ...) removes that class before grouping, so tables summarized from a result are ordinary tibbles (?group_by.cacs_run_result). Values from rates_breakdown reported with 0.2 or 0.3 need to be computed again.