Combine EJAM blockgroup datasets and rename fields for EJSCREEN

Usage

calc_ejscreen_export(
  blockgroupstats = NULL,
  bgej = NULL,
  usastats_acs = NULL,
  statestats_acs = NULL,
  usastats_envirodata = NULL,
  statestats_envirodata = NULL,
  usastats_ej = NULL,
  statestats_ej = NULL,
  pipeline_dir = NULL,
  pipeline_storage = c("auto", "local", "s3"),
  blockgroupstats_stage = "blockgroupstats",
  bgej_stage = "bgej",
  usastats_acs_stage = "usastats_acs",
  statestats_acs_stage = "statestats_acs",
  usastats_envirodata_stage = "usastats_envirodata",
  statestats_envirodata_stage = "statestats_envirodata",
  usastats_ej_stage = "usastats_ej",
  statestats_ej_stage = "statestats_ej",
  blockgroupstats_path = NULL,
  bgej_path = NULL,
  usastats_acs_path = NULL,
  statestats_acs_path = NULL,
  usastats_envirodata_path = NULL,
  statestats_envirodata_path = NULL,
  usastats_ej_path = NULL,
  statestats_ej_path = NULL,
  stage_format = c("csv", "rds", "rda", "arrow"),
  by = "bgfips",
  output_vars = NULL,
  rename_newtype = "ejscreen_indicator",
  mapping_for_names = map_headernames,
  export_percentile_scope = c("national", "state"),
  required_output_names = NULL,
  include_ej_percentiles = TRUE,
  include_state_ej_percentiles = TRUE,
  ej_percentile_vars = c(names_ej, names_ej_supp),
  ej_percentile_output_vars = c(names_ej_pctile, names_ej_supp_pctile),
  ej_state_percentile_vars = c(names_ej_state, names_ej_supp_state),
  ej_state_percentile_output_vars = c(names_ej_state_pctile, names_ej_supp_state_pctile),
  include_ejscreen_map_fields = TRUE,
  map_field_pctile_names = NULL,
  overwrite_ejscreen_map_fields = TRUE,
  feature_server_fields = NULL,
  ejscreen_reference_pctile_signif_digits = c(pctdisability = 12L),
  save_path = NULL,
  save_format = NULL,
  overwrite = TRUE
)

Arguments

blockgroupstats: blockgroupstats-like data.frame, or NULL if reading from a saved pipeline stage.
bgej: bgej-like data.frame, or NULL if reading from a saved pipeline stage.
usastats_acs, usastats_envirodata, statestats_acs, statestats_envirodata: ACS and environmental percentile lookup tables. National exports use the usastats_* tables. EPA-style state-percentile exports use the statestats_* tables and write state-percentile values into the ordinary EPA field names, matching EPA's archived StatePct files.
usastats_ej, statestats_ej: EJ-index percentile lookup tables. These are used to add P_D2_.../P_D5_... fields before creating EJSCREEN map helper fields. EPA-style state-percentile exports use statestats_ej.
pipeline_dir: folder for reading saved pipeline stages.
pipeline_storage: stage storage backend: "auto", "local", or "s3".
blockgroupstats_stage, bgej_stage: stage names to read when objects are not supplied.
usastats_acs_stage, statestats_acs_stage, usastats_envirodata_stage, statestats_envirodata_stage, usastats_ej_stage, statestats_ej_stage: stage names to read for percentile lookup tables when objects are not supplied.
blockgroupstats_path, bgej_path, usastats_acs_path, statestats_acs_path, usastats_envirodata_path, statestats_envirodata_path, usastats_ej_path, statestats_ej_path: explicit paths to saved inputs.
stage_format: input file format when reading pipeline stages.
by: key column used to merge blockgroupstats and bgej.
output_vars: optional EJAM rname columns to keep before renaming. Defaults to all available columns after the merge.
rename_newtype: target naming column in map_headernames. Defaults to "ejscreen_indicator".
mapping_for_names: map_headernames-like crosswalk.
export_percentile_scope: "national" for the ordinary EPA national percentile export, or "state" for the EPA StatePct convention where state raw scores and state percentiles are written into the same generic output field names used by the national export.
required_output_names: optional final EJSCREEN field names that must be present after renaming.
include_ej_percentiles: logical. If TRUE, add missing national EJ-index percentile columns from usastats_ej.
include_state_ej_percentiles: logical. If TRUE, add missing state EJ-index percentile columns from statestats_ej.
ej_percentile_vars, ej_percentile_output_vars: raw national EJ-index variables and corresponding percentile variables to add.
ej_state_percentile_vars, ej_state_percentile_output_vars: raw state EJ-index variables and corresponding percentile variables to add.
include_ejscreen_map_fields: logical. If TRUE, create EJSCREEN app B_... map color-bin columns and T_... popup-text columns from exported P_... percentile columns.
map_field_pctile_names: optional final EJSCREEN percentile field names to use when creating map helper fields. Defaults to all exported P_... fields known to mapping_for_names, plus any other exported fields whose names start with P_.
overwrite_ejscreen_map_fields: logical. If TRUE, recalculate existing B_... and T_... fields from the matching percentile fields.
feature_server_fields: optional final EJSCREEN FeatureServer field names. When supplied, missing schema fields are added when possible and the export is returned in exactly this field order.
ejscreen_reference_pctile_signif_digits: optional named integer vector that gives raw EJAM indicator names and significant digits to use when looking up EJSCREEN export percentiles. The default applies 12 significant digits to pctdisability, which avoids tiny floating-point boundary differences seen when replicating EPA's archived ACS22 P_DISABILITYPCT fields. Set to NULL to use ordinary lookup precision for all fields.
save_path: optional file path to save the export.
save_format: optional save format. Guessed from save_path when NULL. Supported values are "csv", "rds", "rda", and "arrow".
overwrite: logical. If FALSE, refuse to overwrite save_path.

Value

data.frame with EJSCREEN-ready column names.

Details

This helper prepares a tabular export by merging a blockgroupstats-like table with a bgej-like table and renaming available columns through map_headernames. By default it uses ejscreen_indicator, which is the column intended to represent the current EJSCREEN app/export numeric field name. It also creates EJSCREEN app map helper fields from exported percentile fields: B_... map color-bin columns and T_... popup-text columns. The B_... bins use the historical EJSCREEN/ejanalysis cutpoints: 0-9th percentile is bin 1, 10-19 is bin 2, ..., 80-89 is bin 9, 90-94 is bin 10, and 95-100 is bin 11. Missing or out-of-range percentiles are left missing in B_... fields and blank in T_... fields. The T_... fields use the current EJSCREEN service text style, such as "95 %ile".

blockgroupstats keeps pctunemployed as NA where the civilian labor force denominator is zero. For EJSCREEN app/export compatibility, this helper reports those zero-denominator cases as 0 only when the broader unemployment-base denominator is also zero, then builds matching percentile values from those export-compatible values. Rows where unemployment is missing for other reasons remain NA.

blockgroupstats keeps pctnohealthinsurance on the Census-defined B27010 civilian noninstitutionalized population universe. If EJSCREEN requires a legacy-compatible health-insurance field for a specific export target, that compatibility adjustment belongs in this export stage rather than in the EJAM ACS indicator formula.