Capture the package's messages and warnings in a table

Evaluates an expression and returns a tibble listing the standardized catchmentACS messages and warnings given while it runs, that is, those with the class catchmentACS_condition (see catchmentACS-conditions). The captured messages and warnings are not shown.

Usage

cacs_capture_conditions(expr, classes = NULL, return_value = NULL)

Arguments

expr: An expression to evaluate, such as a call to cacs_run().
classes: A character vector of the classes to capture, or NULL (the default) for all messages and warnings of the package. Each element can be a full class name, such as "catchmentACS_message_progress_summary", or "message" or "warning" for all messages or all warnings of the package. It can also be the part of a class name after catchmentACS_message_, catchmentACS_warning_, or catchmentACS_error_, such as "water_tract_filter" or "progress". A name that matches no class captures nothing, without an error.
return_value: A string giving what to return: "conditions" for the table of captured conditions, or "both" for a list with the value of expr as well. NULL (the default) uses the option catchmentACS.capture_return_value, which is "conditions" unless it has been changed.

Value

With return_value = "conditions", a tibble with one row for each captured condition, in the order in which they were given, and these columns:

class: The most specific class of the condition, such as "catchmentACS_message_progress_summary".
message: The text of the condition, as returned by conditionMessage().
phase: The step that gave the condition: "acs" for cacs_acs_prefetch(), "isochrone" for cacs_isochrone(), "intersect" for cacs_intersect_weight(), "moe" for cacs_propagate_moe(), "rates" for cacs_derive_rates(), "run" for cacs_run() itself, and "cache" for cacs_set_cache() and cacs_clear_cache(). Messages and warnings about saved results have the value of their step (some of those about ACS data saved in test mode have "acs_test"; see namespace_mode in cacs_get_cache_state()). A progress line or summary line has the label of its step, such as "Intersect+weight" (see the "Progress messages" section of cacs_run()). The warning of cacs_validate_osrm_endpoint() has "isochrone", and the message and warning of the maps about the nearest site have the name of the function, such as "cacs_plot_site_rates". The warnings of cacs_intersect_weight() about repaired geometries and the message of as_tibble.cacs_run_result() have NA. The values are not the names of the elements of the cacs_run_warnings attribute of a cacs_run() result.
timestamp: The time at which the condition was given, as a date-time in UTC.
call: The call in which the condition was given, as text, or NA when there is none. For a condition given while cacs_run() runs a step, the text can include the data passed to the step and be very long.

With return_value = "both", a list with two elements: result, the value of expr, and conditions, the tibble above.

Details

The conditions are captured with withCallingHandlers(), so expr runs to the end. Messages and warnings that are not captured, because they come from other packages or do not match classes, are shown as usual. Errors are not captured: an error in expr stops cacs_capture_conditions(), and the conditions captured before it are not returned.

Keeping the value of the expression

With return_value = "conditions", the value of expr is not returned. An assignment made with <- inside expr does not keep it either, because expr is evaluated in a new environment: cacs_capture_conditions(acs <- cacs_acs_prefetch("AL")) leaves acs as it was. With return_value = "both", the value is kept as the result element of the list. An assignment made with <<- inside expr also keeps it, in the first variable of that name found by searching from the environment in which cacs_capture_conditions() is called (see assignOps).

Examples

# Turn the cache off while this example runs (see ?cacs_set_cache).
old <- options(catchmentACS.cache_enabled = FALSE)

# Example data bundled with the package: the drive-time areas are circles
# with a radius of 1 km per minute, and the ACS data are made up.
library(sf)
iso <- readRDS(system.file("extdata", "legacy_2025_isochrones.rds",
                           package = "catchmentACS"))
acs <- readRDS(system.file("extdata", "sample_alabama_subset.rds",
                           package = "catchmentACS"))
iso_07 <- iso[iso$site_id == "AL_SITE_07" & iso$drive_time_min == 10, ]
site_07 <- data.frame(site_id = "AL_SITE_07", lon = -85.365, lat = 31.655)

# The messages of a run, captured instead of shown; out$result is the
# result of cacs_run()
out <- cacs_capture_conditions(
  cacs_run(site_07, state = "AL", drive_times = 10,
           precomputed_isochrones = iso_07, acs = acs),
  return_value = "both"
)
out$conditions[, c("class", "message")]
#> # A tibble: 8 × 2
#>   class                                 message                                 
#>   <chr>                                 <chr>                                   
#> 1 catchmentACS_message_progress         "\u001b[1m\u001b[22m\u001b[36mℹ\u001b[3…
#> 2 catchmentACS_message_progress         "\u001b[1m\u001b[22m\u001b[36mℹ\u001b[3…
#> 3 catchmentACS_message_progress         "\u001b[1m\u001b[22m\u001b[36mℹ\u001b[3…
#> 4 catchmentACS_message_progress         "\u001b[1m\u001b[22mIntersecting 1 site…
#> 5 catchmentACS_message_progress_summary "\u001b[1m\u001b[22mIntersect+weight co…
#> 6 catchmentACS_message_progress_summary "\u001b[1m\u001b[22mMOE propagation com…
#> 7 catchmentACS_message_progress_summary "\u001b[1m\u001b[22mRate derivation com…
#> 8 catchmentACS_message_progress         "\u001b[1m\u001b[22m\u001b[36mℹ\u001b[3…

# Only the warnings: the range check on rates, turned on here, warns
# about two rates of the made-up data
old_audit <- options(catchmentACS.audit_rates = TRUE)
warned <- cacs_capture_conditions(
  cacs_run(site_07, state = "AL", drive_times = 10,
           precomputed_isochrones = iso_07, acs = acs, verbose = FALSE),
  classes = "warning"
)
warned[, c("class", "message")]
#> # A tibble: 2 × 2
#>   class                                  message                                
#>   <chr>                                  <chr>                                  
#> 1 catchmentACS_warning_rate_out_of_range "\u001b[1m\u001b[22mRate audit found o…
#> 2 catchmentACS_warning_rate_out_of_range "\u001b[1m\u001b[22mRate audit found o…
options(old_audit)

options(old)

# The download from the Census Bureau needs a Census API key.
if (FALSE) { # \dontrun{
out <- cacs_capture_conditions(
  cacs_acs_prefetch(state = "AL", year = 2023),
  classes = "water_tract_filter",
  return_value = "both"
)
al <- out$result
out$conditions$message
} # }