Build all four maps for one site

Builds, for one site, the four maps that show step by step how the package computes its estimates from American Community Survey (ACS) data, and returns them in one list. The maps come from cacs_plot_site_isochrone() (the site and its drive-time areas), cacs_plot_site_intersection() (the census tracts that overlap one area, shaded by coverage weight), cacs_plot_site_weighted() (one ACS variable over those tracts), and cacs_plot_site_rates() (the five rates). A tract's coverage weight is the share of its area inside the drive-time area.

Usage

cacs_plot_site_pipeline(
  site_id = NULL,
  lat = NULL,
  lon = NULL,
  site_name = NULL,
  iso_sf,
  tract_sf,
  acs_sf,
  run_result,
  sites_df = NULL,
  variable = "B17001_002",
  variable_family = "spatial_total",
  tiles = "OpenStreetMap",
  padding_km = 5,
  drive_time_min = NULL,
  ...
)

Arguments

site_id: A string giving the site_id of the site to map, used to find its point in sites_df and its drive-time areas in iso_sf.
lat, lon: Single numbers giving the latitude and longitude of a point in degrees (WGS 84), used when site_id is NULL. The nearest site in sites_df is found as in cacs_plot_site_rates(), with one message, and used for all four maps.
site_name: A string giving the name of the site, compared with the site_name column of sites_df including case, and used when site_id, lat, and lon are NULL. It must match one row.
iso_sf: An sf object of drive-time areas in EPSG:4326 (longitude and latitude), such as the result of cacs_isochrone(), with the columns site_id and drive_time_min.
tract_sf: An sf object of census tract polygons with a GEOID column, such as the result of cacs_acs_prefetch(). When a tract has several rows, as in that result (one for each variable), the first row is used.
acs_sf: A data frame or sf object of tract estimates in the long form of the result of cacs_acs_prefetch(), with the columns GEOID, variable, estimate, and moe. It is often the same object as tract_sf. The estimates are mapped as they are: unlike cacs_intersect_weight(), the map does not set Census Bureau annotation codes, such as -666666666, to NA, and it draws a tract with two rows for the variable twice instead of giving an error.
run_result: A data frame of rates with the columns site_id, variable, estimate, moe, n_tracts_num, n_tracts_den, and moe_fallback, such as the long form of a cacs_run() result or the result of cacs_derive_rates(). The rows of the chosen site for the five rates are used, and there must be at least one.
sites_df: An sf object of site points in longitude and latitude with a site_id column, or NULL (the default) for cacs_alabama_sites. The bundled file legacy_2025_isochrones.rds uses the same site_id values for other places, so with its areas the default puts the point and the initial view far from them.
variable: A string giving the ACS variable code to map, one of the values in the variable column of acs_sf. The default is "B17001_002", the number of people whose income in the past 12 months was below the poverty level.
variable_family: A string giving the kind of quantity that variable is, as in the estimand_family column of cacs_run() results. It only chooses the ColorBrewer palette: "Greens" for "spatial_total" (a count; the default), "PuOr" for "median_proxy" (a median), "YlOrRd" for "area_weighted_scalar_proxy" (a per-person value), and "RdYlBu" for "derived_rate" (a rate). NA and unrecognized values give "YlGnBu", and "metadata_only" gives an error. The value is not checked against variable.
tiles: A string naming the background map, one of the tile providers in leaflet::providers; the default is "OpenStreetMap", the standard OpenStreetMap map, which needs no API key. The map is built offline, and the tiles are downloaded when it is displayed. The CARTO tiles, such as "CartoDB.Positron", need an API key, which these functions do not send, so they show a notice asking for one.
padding_km: A single positive number. The initial view shows at least this many kilometers on each side of the site; the default is 5.
drive_time_min: A single number giving the drive time, in minutes, of the area in the second and third maps, or NULL (the default) for the longest drive time of the site in iso_sf. The first map draws all the areas of the site, and the fourth their outline.
...: Passed to the four map functions, which do not use them.

Value

A list of class "cacs_site_plot_pipeline" with four leaflet maps, isochrone, intersection, weighted, and rates, from the four functions in that order. See print.cacs_site_plot_pipeline() for what printing the list shows. The attributes site_id, lat, lon, and name record the site used, and variable the variable of the third map.

Details

The site is looked up once, before any map is built, and used for all four. iso_sf, sites_df, tiles, padding_km, and ... are passed to all four functions, tract_sf and drive_time_min to the second and third, acs_sf, variable, and variable_family to the third, and run_result to the fourth.

The function does not contact a routing service or the Census Bureau. Its inputs are results computed beforehand: the drive-time areas by cacs_isochrone(), the tract estimates by cacs_acs_prefetch(), and the rates by cacs_run().

Examples

if (requireNamespace("leaflet", quietly = TRUE)) {
  # Example data bundled with the package for one site in Birmingham,
  # Alabama: a 10-minute drive-time area from the OSRM routing service,
  # 2019-2023 ACS estimates for nearby tracts, and the cacs_run() result.
  fx <- readRDS(system.file("extdata", "visual_walkthrough_fixture.rds",
                            package = "catchmentACS"))
  maps <- cacs_plot_site_pipeline(
    site_id    = "AL_BHM_01",
    iso_sf     = fx$iso_sf,
    tract_sf   = fx$tract_sf,
    acs_sf     = fx$acs_sf,
    run_result = fx$run_result,
    sites_df   = fx$sites_df
  )
  # A summary of the four maps; no map is drawn
  print(maps)
  # The second map
  maps$intersection
}
#> 
#> ── catchmentACS site plot pipeline ─────────────────────────────────────────────
#> Site: AL_BHM_01 (Birmingham_Vulcan)
#> Variable (Stage 3): B17001_002
#> 
#> ── 4 leaflet widgets returned ──
#> 
#> • `x$isochrone` - Stage 1: site point + isochrone polygon
#> • `x$intersection` - Stage 2: tracts colored by area_wt
#> • `x$weighted` - Stage 3: tract choropleth on `B17001_002`
#> • `x$rates` - Stage 4: 5-rate popup summary
#> ℹ Show a map by typing its name, such as `x$isochrone`, in the console.


# Downloads ACS data with a Census API key and builds three areas on the
# public OSRM demo server with the osrm package; the server limits requests.
if (FALSE) { # \dontrun{
library(sf)
sites <- cacs_alabama_sites[1:3, ]
iso <- cacs_isochrone(sites, drive_times = 10)
acs <- cacs_acs_prefetch("AL")
out <- cacs_run(sites, state = "AL", drive_times = 10,
                precomputed_isochrones = iso, acs = acs)
maps_live <- cacs_plot_site_pipeline(site_id = "AL_SITE_01", iso_sf = iso,
                                     tract_sf = acs, acs_sf = acs,
                                     run_result = out)
} # }

Usage

Arguments

Value

Details

See also

Examples