Describe how a result was produced

Prints a description of an object made by the package, drawn from the attributes that record how it was produced, and returns the description invisibly as a list. It describes the results of cacs_run() and of the functions that cacs_run() runs: cacs_isochrone(), cacs_acs_prefetch(), cacs_intersect_weight(), cacs_propagate_moe(), and cacs_derive_rates(). Their Value sections describe the attributes.

Usage

cacs_describe(x, ...)

# S3 method for class 'cacs_description'
print(x, ...)

Arguments

x

An object to describe (see Details). For print(), a list returned by cacs_describe().

...

Not used.

Value

cacs_describe() returns, invisibly, a list of class cacs_description with these elements:

object_type

A string naming the kind of object (see Details).

sections

A named list with one character vector of printed lines for each section.

data

A named list of the attributes that the sections are drawn from, such as rate_provenance, the cacs_rate_provenance attribute of x or NULL. For a result of cacs_run(), it also holds cache_state, from cacs_get_cache_state().

attributes_present

A character vector of the names of the package's attributes that x has.

print() prints x in the same way and returns it invisibly.

Details

The output starts with a title and the kind of object, which is also kept in object_type and decides the sections that follow:

"cacs_run_result"

A result of cacs_run(). For a result with output = "both", its element long is described. The sections are "Object", "Run", "Rates", and "Cache". "Run" shows the routing service and profile, the drive times, the numbers of sites, and the running time, as print.cacs_run_result() does, and "Rates" the lines of "Rate Derivation" below. For the list-column form, "Rate rows" is 0, because the rates are inside its derived_rates column. "Cache" shows values of cacs_get_cache_state() for the R session at the time of the call.

"weighted_seam", "propagated_seam", "derived_rates"

The results of cacs_intersect_weight(), cacs_propagate_moe(), and cacs_derive_rates(), told apart by their attributes; another tibble is "tbl_df". After "Object", "Carrier Table" summarizes the cacs_aggregation_carriers attribute, the table of weighted totals and means, with their variances, that cacs_intersect_weight() keeps for the later steps: the number of rows, the numbers of distinct variables and sites, how many rows have a missing total, and the range of weight_sum. cacs_derive_rates() removes that attribute, and for its result the section reads Carrier attribute: absent or already consumed. "MOE Propagation" shows values of cacs_moe_provenance, the record of how the margins of error (MOE) were computed. "Rate Derivation" shows the number of rate rows and values of cacs_rate_provenance, and "Aggregation" values of cacs_aggregation_provenance.

"isochrone_sf", "acs_sf", "sf"

sf objects told apart by their columns: drive-time areas, such as a result of cacs_isochrone(), American Community Survey (ACS) data, such as a result of cacs_acs_prefetch(), and others. "Spatial Provenance" shows values of cacs_isochrone_provenance and cacs_res_param, and "ACS Provenance" values of cacs_acs_provenance.

"unknown"

Any other object, with one section saying that there is nothing to describe.

A data frame that is not a tibble is described as a tibble only if it has one of the package's attributes or one of the columns site_id, drive_time_min, variable, estimand_family, ring_topology, or failure_origin. A value that is not recorded is shown as n/a. Two sections differ: "Rates computed" lists the five rates even for an object without rate rows, and "Carrier Table" says that the attribute is absent or already consumed.

The description does not count the rate rows whose chosen formula for the margin of error could not be used (moe_fallback = TRUE). The lines about rates in "MOE Propagation", such as "C1 to C2 fallbacks", are always 0 (see cacs_propagate_moe()). "Formula downgrades" is the number of rates that formula_dispatch = "proportion_subset" left on the ratio formula. In "Aggregation", "Input sites" is the number of site and drive-time pairs, and "Sites with data" is the number of rows with tracts in the cacs_intersect_weight() result, which has one row for each pair and variable.

The description is printed as R messages, so suppressMessages() hides it.

See also

Other result summaries: as_tibble.cacs_run_result(), cacs_summary_as_markdown(), group_by.cacs_run_result(), print.cacs_run_result(), print.cacs_run_summary(), summary.cacs_run_result()

Examples

# A bundled cacs_run() result for a 10-minute area in Birmingham, Alabama
out <- readRDS(system.file("extdata", "visual_walkthrough_fixture.rds",
                           package = "catchmentACS"))$run_result
desc <- cacs_describe(out)
#> 
#> ── catchmentACS provenance map ─────────────────────────────────────────────────
#> Object type: cacs_run_result
#> 
#> ── Object ──
#> 
#> Type: cacs_run_result
#> Rows: 19
#> Columns: 27
#> Schema version: 1.0
#> 
#> ── Run ──
#> 
#> Provider/profile: osrm / car
#> Drive times: 10,
#> Sites: 1 success / 0 failed / 1 total
#> Wall clock seconds: 0.181549
#> 
#> ── Rates ──
#> 
#> Rate rows: 5
#> Rates computed: poverty_rate, snap_rate, ssi_rate, unemp_rate,
#> labor_force_participation,
#> Formula dispatch: general_ratio_conservative
#> Carrier-missing rate rows: 0
#> Out-of-range audit rows: 0
#> Formula downgrades: 0
#> 
#> ── Cache ──
#> 
#> Enabled: TRUE
#> Namespace mode: production
#> Fingerprint algorithm: sha256
#> Session hits: 0
#> Session misses: 0

# The package's attributes that out has
desc$attributes_present
#>  [1] "cacs_schema_version"         "cacs_run_provenance"        
#>  [3] "cacs_run_result_metadata"    "cacs_run_warnings"          
#>  [5] "cacs_aggregation_provenance" "cacs_moe_provenance"        
#>  [7] "cacs_rate_provenance"        "cacs_rate_audit"            
#>  [9] "cacs_confidence_level"       "skipped_geoids"