Calculate the ACS-derived blockgroup pipeline stage

Usage

calc_bg_acsdata(
  yr,
  formulas = EJAM::formulas_ejscreen_acs$formula,
  tables = as.vector(EJAM::tables_ejscreen_acs),
  include_tract_data = TRUE,
  tract_tables = c("B18101", "C16001", "B27010"),
  tract_formulas = NULL,
  tract_weight_source = c("decennial2020", "acs"),
  dropMOE = TRUE,
  acs_raw = NULL,
  include_islandareas_data = FALSE,
  islandareas_raw = NULL,
  islandareas_demographics = NULL,
  islandareas_reference = NULL,
  islandareas_tables = islandareas_tables_for_bg_acsdata(),
  use_islandareas_demographics = FALSE,
  acs_raw_stage = NULL,
  pipeline_dir = NULL,
  save_stage = FALSE,
  stage_format = c("csv", "rds", "rda", "arrow"),
  overwrite = TRUE,
  validation_strict = TRUE
)

Arguments

yr: end year of the ACS 5-year survey to use.
formulas: formulas used for blockgroup-resolution ACS tables.
tables: ACS tables to inspect and download when available at blockgroup resolution.
include_tract_data: logical, whether to add tract-resolution ACS indicators apportioned to blockgroups.
tract_tables: ACS tables to obtain at tract resolution and apportion to blockgroups.
tract_formulas: formulas used for tract-resolution ACS indicators. Defaults to calc_blockgroupstats_from_tract_data() defaults.
tract_weight_source: source for tract-to-blockgroup apportionment weights. "decennial2020" matches the legacy EJSCREEN method by using 2020 Decennial Census blockgroup population weights. "acs" uses same-vintage ACS blockgroup population weights.
dropMOE: logical, whether to drop ACS margin-of-error columns.
acs_raw: optional raw ACS pipeline object from download_bg_acs_raw().
include_islandareas_data: logical, whether to append Island Areas rows. Puerto Rico is not included here because it is already part of ACS.
islandareas_raw: optional raw Island Areas Census DHC object from download_bg_islandareas_raw().
islandareas_demographics: optional transformed Island Areas Census DHC demographics table from calc_bg_islandareasdata().
islandareas_reference: optional Island Areas rows from the archived EPA EJScreen ACS2022 reference file. When supplied and use_islandareas_demographics = FALSE, these rows define the Island Areas blockgroup IDs and labels used for placeholder rows.
islandareas_tables: Island Areas Census DHC tables to download if include_islandareas_data is TRUE and islandareas_raw is not supplied.
use_islandareas_demographics: logical. Defaults to FALSE so that the EJSCREEN-compatible pipeline appends Island Areas blockgroup rows without using mixed-source Island Areas Census demographics in bg_acsdata. Set TRUE only for a supplemental mixed-source dataset.
acs_raw_stage: optional stage name to read from pipeline_dir.
pipeline_dir: folder for saving the pipeline stage.
save_stage: logical, whether to save the bg_acsdata stage.
stage_format: file format for saved stages: "csv", "rds", "rda", or "arrow".
overwrite: logical, whether to overwrite an existing saved stage.
validation_strict: logical passed to ejscreen_pipeline_save().

Value

data.table, one row per blockgroup.

Details

This is the first step in the reusable ACS pipeline for annual EJSCREEN/EJAM data updates. It downloads blockgroup-resolution ACS tables via calc_blockgroupstats_acs(), apportions tract-resolution-only ACS tables to blockgroups with calc_blockgroupstats_from_tract_data(), merges those ACS-derived indicators, and can save the validated bg_acsdata stage.

bg_acsdata is intentionally limited to data columns that can be created using only ACS data. "Demographic index" columns are calculated later by calc_ejscreen_blockgroupstats(), after bg_envirodata and extra indicators have been joined, because the supplemental demographic index needs lowlifex which is not from the ACS.

When Island Areas rows are requested, the default EJSCREEN-compatible path appends AS/GU/MP/VI rows from the archived EPA EJScreen ACS2022 reference without using the optional 2020 Island Areas Census DHC demographics. Those DHC values can be saved and reviewed separately, and are used here only when use_islandareas_demographics = TRUE. In the annual/release runner, Island Area placeholder rows are enabled by default so those areas can appear in blockgroup datasets, EJSCREEN exports, and maps. This does not add point-buffer/radius support, because Island Area blocks are not added to the block helper datasets.