significant documentation updates and new vignettes

.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(dpkg:*)",
+      "Bash(pkg-config:*)",
+      "Bash(apt list:*)",
+      "Bash(Rscript:*)"
+    ]
+  }
+}

DESCRIPTION

@@ -15,14 +15,15 @@ Authors@R: c(
 Description: This packages combines a set of utilities for acquiring and processing 
     climate and climate-adjacent datasets under a consistent API. It takes opinionated 
     stances on how to manipulate raw data in an effort to produce standard workflows 
-    that enable project teams to devote more time to substantive analysis and inference-making.
+    that enable project teams to devote more time to substantive analysis.
 License: MIT + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.3
 Imports: 
     arrow,
     censusapi,
+    sfarrow,
     dplyr,
     esri2sf (>= 0.1.1),
     ellmer,

NAMESPACE

@@ -23,6 +23,7 @@ export(get_sheldus)
 export(get_spatial_extent_census)
 export(get_structures)
 export(get_system_username)
+export(get_wildfire_burn_zones)
 export(inflation_adjust)
 export(interpolate_demographics)
 export(polygons_to_linestring)

R/get_current_fire_perimeters.R

@@ -1,14 +1,30 @@
-# Author: Will Curran-Groome
-
 #' @importFrom magrittr %>%
 
-#' @title Acquire wildfire perimeters
+#' @title Acquire current wildfire perimeters
+#'
+#' @description Retrieves current wildfire perimeter data from the NIFC (National
+#'   Interagency Fire Center) via the Wildland Fire Interagency Geospatial Services
+#'   (WFIGS) API.
+#'
 #' @param geography Included only for API consistency; this must be NULL.
 #' @param file_path Included only for API consistency; this must be NULL.
 #' @param bbox Optionally, an sf::st_bbox() object, or an object that can be converted to such.
 #' @param api Included only for API consistency; this must be TRUE.
 #'
-#' @returns A library(sf) enabled dataframe comprising perimeters of current wildfires.
+#' @details Data are from the NIFC WFIGS service. See
+#'   \url{https://data-nifc.opendata.arcgis.com/datasets/nifc::wfigs-interagency-fire-perimeters/about}.
+#'
+#' @returns An sf dataframe comprising perimeters of current wildfires. Columns include:
+#'   \describe{
+#'     \item{unique_id}{Unique identifier for each observation (generated).}
+#'     \item{incident_name}{Name of the fire incident (title case).}
+#'     \item{incident_size_acres}{Size of the fire in acres.}
+#'     \item{incident_short_description}{Brief description of the incident.}
+#'     \item{percent_contained}{Percent of fire contained (0-100).}
+#'     \item{identified_date}{Date/time the fire was discovered.}
+#'     \item{updated_date}{Date/time the record was last updated.}
+#'     \item{geometry}{Polygon geometry of the fire perimeter.}
+#'   }
 #' @export
 #'
 #' @examples

R/get_emergency_managerment_performance.R

@@ -1,17 +1,30 @@
-#' Get EMPG data
+#' Get Emergency Management Performance Grant (EMPG) data
+#'
+#' @description Retrieves Emergency Management Performance Grant (EMPG) award data
+#'   from FEMA, which supports state and local emergency management agencies.
 #'
 #' @param file_path Path to the downloaded dataset on Box.
-#' @param api Logical indicating whether to use the OpenFEMA API to retrieve the data. Default is TRUE.
+#' @param api Logical indicating whether to use the OpenFEMA API to retrieve the data.
+#'   Default is TRUE.
+#'
+#' @details Data are from FEMA's OpenFEMA API. See
+#'   \url{https://www.fema.gov/openfema-data-page/emergency-management-performance-grants-v2}.
 #'
-#' @return A tibble containing Emergency Management Performance Grant (EMPG) data with the following columns:
-#' \describe{
-#'   \item{state_name}{Character. The name of the state receiving the grant (renamed from original "state" column).}
-#'   \item{year_project_start}{Numeric. The year the project started, with corrections applied for known data entry errors in the source data.}
-#'   \item{state_code}{Character. Two-digit FIPS state code.}
-#'   \item{state_abbreviation}{Character. Two-letter USPS state abbreviation.}
-#'   \item{...}{Additional columns from the OpenFEMA EMPG dataset, cleaned via `janitor::clean_names()`.}
-#' }
-#' Data are filtered to records with `year_project_start > 2012`. A warning is issued noting data completeness concerns for 2024-2025.
+#' @return A data frame containing emergency management performance grant (EMPG) data.
+#'   Columns include:
+#'   \describe{
+#'     \item{id}{Unique identifier for the grant record.}
+#'     \item{state_name}{Full state name.}
+#'     \item{state_code}{Two-digit state FIPS code.}
+#'     \item{state_abbreviation}{Two-letter state abbreviation.}
+#'     \item{year_project_start}{Year the project started.}
+#'     \item{project_start_date}{Date the project started.}
+#'     \item{project_end_date}{Date the project ended.}
+#'     \item{grant_amount}{Total grant amount in dollars.}
+#'     \item{federal_share}{Federal portion of the grant in dollars.}
+#'     \item{non_federal_share}{Non-federal cost share in dollars.}
+#'     \item{program}{EMPG program type.}
+#'   }
 #' @export
 
 get_emergency_management_performance = function(

R/get_fema_disaster_declarations.R

@@ -1,9 +1,28 @@
-# Author: Kameron Lloyd
-
 #' @title Get major disaster declarations by county
+#'
+#' @description Retrieves FEMA Major Disaster Declarations at the county level,
+#'   aggregated by year and month. Tribal declarations are stored separately as
+#'   an attribute.
+#'
 #' @param file_path The path (on Box) to the file containing the raw data.
 #' @param api If TRUE (default), access data from the API. Else, read locally from `file_path`.
-#' @returns A dataframe comprising Major Disaster Declarations by month by year by county. Tribal declarations are stored as an attribute of the primary dataframe called `tribal_declarations`.
+#'
+#' @details Data are from FEMA's OpenFEMA API. See
+#'   \url{https://www.fema.gov/openfema-data-page/disaster-declarations-summaries-v2}.
+#'   Statewide declarations are expanded to all counties in the state.
+#'
+#' @returns A dataframe comprising Major Disaster Declarations by month by year by county.
+#'   Tribal declarations are stored as an attribute (`tribal_declarations`). Columns include:
+#'   \describe{
+#'     \item{unique_id}{Unique identifier for each observation.}
+#'     \item{GEOID}{Five-digit county FIPS code.}
+#'     \item{year_declared}{Year the disaster was declared.}
+#'     \item{month_declared}{Month the disaster was declared (1-12).}
+#'     \item{declaration_title}{Title(s) of the disaster declaration(s).}
+#'     \item{incidents_all}{Total count of disaster declarations in the county-month.}
+#'     \item{incidents_natural_hazard}{Count of natural hazard declarations.}
+#'     \item{incidents_*}{Additional columns for other incident types, each of which reflects the count of the given incident type.}
+#'   }
 #' @export
 #' @examples
 #' \dontrun{

R/get_government_finances.R

@@ -1,21 +1,31 @@
 #' Get government unit-level expenses from the Census of Governments
 #'
+#' @description Retrieves government unit-level finance data from the Census of Governments,
+#'   including expenses by category for state, county, city, township, special district,
+#'   and school district government units.
+#'
 #' @param year A four-digit year. The default is 2022.
 #'
-#' @return A tibble containing government unit-level financial data aggregated by unit, with the following columns:
-#' \describe{
-#'   \item{unit_id}{Character. Unique identifier for the government unit.}
-#'   \item{year_data}{Numeric. The year of the financial data.}
-#'   \item{amount_thousands}{Numeric. Total expenditure amount in thousands of dollars.}
-#'   \item{government_type}{Character. Type of government unit: "State", "County", "City", "Township", "Special District", or "School District/Educational Service Agency".}
-#'   \item{data_quality}{Numeric. Proportion of records that were reported (vs. imputed or from alternative sources), ranging from 0 to 1.}
-#'   \item{unit_name}{Character. Name of the government unit.}
-#'   \item{county_name}{Character. County name where the unit is located.}
-#'   \item{state_code}{Character. Two-digit state FIPS code.}
-#'   \item{population}{Numeric. Population served by the government unit.}
-#'   \item{enrollment}{Numeric. Student enrollment (for school districts; NA for other unit types).}
-#'   \item{amount_per_capita}{Numeric. Expenditure per capita (or per enrolled student for school districts).}
-#' }
+#' @details Data are from the U.S. Census Bureau's Annual Survey of State and Local
+#'   Government Finances and Census of Governments. See
+#'   \url{https://www.census.gov/programs-surveys/gov-finances.html}.
+#'
+#' @return A dataframe containing government unit-level expenses for the specified year.
+#'   Columns include:
+#'   \describe{
+#'     \item{unit_id}{Unique identifier for the government unit.}
+#'     \item{year_data}{Year of the financial data.}
+#'     \item{amount_thousands}{Total expenses in thousands of dollars.}
+#'     \item{government_type}{Type of government (State, County, City, Township, Special District, School District).}
+#'     \item{data_quality}{Proportion of expense items that were reported (vs. imputed).}
+#'     \item{state_code}{Two-digit state FIPS code.}
+#'     \item{county_code}{Three-digit county FIPS code.}
+#'     \item{unit_name}{Name of the government unit.}
+#'     \item{county_name}{Name of the county.}
+#'     \item{population}{Population served by the unit.}
+#'     \item{enrollment}{Student enrollment (for school districts).}
+#'     \item{amount_per_capita}{Expenses per capita or per enrolled student.}
+#'   }
 #' @export
 
 get_government_finances = function(year = 2022) {

R/get_hazard_mitigation_assistance.R

@@ -26,11 +26,39 @@ clean_county = function(county) {
 
 #' Get Hazard Mitigation Assistance (HMA) Project Details
 #'
-#' @param file_path_old_grant_system The file path to raw data for HMA applications from the older grant-reporting system. These data are typically available from: https://www.fema.gov/openfema-data-page/hazard-mitigation-assistance-projects-v4
-#' @param file_path_new_grant_system The file path to raw data for HMA applications from the newer (FEMA GO) grant-reporting system. These data are typically available from: https://www.fema.gov/openfema-data-page/hma-subapplications-v2
-#' @param state_abbreviations NULL by default, in which case data are returned for all 51 states. Provide a vector of two-character USPS state abbreviations to obtain data for a sub-selection of states.
+#' @description Retrieves Hazard Mitigation Assistance project data from both the legacy
+#'   HMA Projects dataset and the newer FEMA GO subapplications dataset, harmonized
+#'   at the project-county level.
 #'
-#' @return A dataframe of project-county HMA application data, aggregated across both old and new grant reporting systems.
+#' @param file_path_old_grant_system The file path to raw data for HMA applications from
+#'   the older grant-reporting system. These data are typically available from:
+#'   \url{https://www.fema.gov/openfema-data-page/hazard-mitigation-assistance-projects-v4}
+#' @param file_path_new_grant_system The file path to raw data for HMA applications from
+#'   the newer (FEMA GO) grant-reporting system. These data are typically available from:
+#'   \url{https://www.fema.gov/openfema-data-page/hma-subapplications-v2}
+#' @param state_abbreviations NULL by default, in which case data are returned for all 51
+#'   states. Provide a vector of two-character USPS state abbreviations to obtain data for
+#'   a sub-selection of states.
+#'
+#' @details Data are from FEMA's OpenFEMA API, combining two data sources: the legacy
+#'   Hazard Mitigation Assistance Projects (v4) and the newer HMA Subapplications (v2).
+#'   Multi-county projects are split across counties based on population proportions.
+#'
+#' @return A dataframe of project-county HMA application data. Only `project_cost_federal_split`
+#'   should be used for county-level aggregations. Columns include:
+#'   \describe{
+#'     \item{data_source}{"hma-projects" (legacy) or "hma-subapplications" (FEMA GO).}
+#'     \item{project_id}{Unique project identifier.}
+#'     \item{disaster_number}{FEMA disaster number (if disaster-related).}
+#'     \item{project_program_area}{HMA program: HMGP, BRIC, FMA, or PDM.}
+#'     \item{project_fiscal_year}{Fiscal year of the project.}
+#'     \item{state_name}{Full state name.}
+#'     \item{county_geoid}{Five-digit county FIPS code.}
+#'     \item{county_population}{County population used for allocation.}
+#'     \item{project_status}{Current project status (e.g., "Closed", "Active").}
+#'     \item{project_cost_federal}{Total federal cost at project level.}
+#'     \item{project_cost_federal_split}{Federal cost allocated to this county.}
+#'   }
 #' @export
 #'
 #' @examples

R/get_ihp_registrations.R

@@ -2,24 +2,41 @@
 
 #' @title Get Individuals and Households Program (IHP) registrations
 #'
-#' @param state_fips A character vector of two-letter state abbreviations. If NULL (default), return data for all 51 states. Otherwise return data for the specified states.
+#' @description Retrieves FEMA Individual and Households Program (IHP) registration data,
+#'   which captures applications for disaster assistance from individuals and households.
+#'
+#' @param state_fips A character vector of two-letter state abbreviations. If NULL (default),
+#'   return data for all 51 states. Otherwise return data for the specified states.
 #' @param file_name The name (not the full path) of the Box file containing the raw data.
 #' @param api If TRUE, query the API. If FALSE (default), read from disk.
 #' @param outpath The path to save the parquet-formatted datafile. Applicable only when `api = FALSE`.
 #'
-#' @return A tibble containing Individual and Households Program (IHP) registration data at the household level, joined to county-level geography. Due to ZIP-to-county crosswalking, records may be duplicated across counties (see warning). The returned object includes:
-#' \describe{
-#'   \item{unique_id}{Character. A UUID uniquely identifying each original IHP registration.}
-#'   \item{allocation_factor_zcta_to_county}{Numeric. The proportion of the ZCTA's population in this county (0-1). Used to apportion registrations when a ZIP spans multiple counties.}
-#'   \item{geoid_county}{Character. Five-digit FIPS county code.}
-#'   \item{zcta_code}{Character. Five-digit ZCTA (ZIP Code Tabulation Area) code.}
-#'   \item{geoid_tract}{Character. 11-digit Census tract GEOID (may have missingness).}
-#'   \item{geoid_block_group}{Character. 12-digit Census block group GEOID (may have missingness).}
-#'   \item{disaster_number}{Character. FEMA disaster number associated with the registration.}
-#'   \item{amount_individual_housing_program, amount_housing_assistance, amount_other_needs_assistance, amount_rental_assistance, amount_repairs, amount_replacement, amount_personal_property}{Numeric. Various IHP assistance amounts in dollars.}
-#'   \item{amount_flood_insurance_premium_paid_by_fema}{Numeric. Flood insurance premium paid by FEMA in dollars.}
-#'   \item{state_name, state_abbreviation, state_code}{Character. State identifiers.}
-#' }
+#' @details Data are from FEMA's OpenFEMA API. See
+#'   \url{https://www.fema.gov/openfema-data-page/individuals-and-households-program-valid-registrations-v2}.
+#'
+#' @returns A dataframe comprising IHP registrations. Note that records are duplicated
+#'   due to a many-to-many join with a ZCTA-to-county crosswalk; use `allocation_factor_zcta_to_county`
+#'   to properly aggregate. Columns include:
+#'   \describe{
+#'     \item{unique_id}{Unique identifier for the original registration.}
+#'     \item{allocation_factor_zcta_to_county}{Weight for attributing registration to county.}
+#'     \item{geoid_county}{Five-digit county FIPS code.}
+#'     \item{zcta_code}{Five-digit ZIP Code Tabulation Area.}
+#'     \item{geoid_tract}{11-digit census tract FIPS code.}
+#'     \item{geoid_block_group}{12-digit census block group FIPS code.}
+#'     \item{disaster_number}{FEMA disaster number.}
+#'     \item{amount_individual_housing_program}{Total IHP assistance amount in dollars.}
+#'     \item{amount_housing_assistance}{Housing assistance amount in dollars.}
+#'     \item{amount_other_needs_assistance}{Other needs assistance amount in dollars.}
+#'     \item{amount_rental_assistance}{Rental assistance amount in dollars.}
+#'     \item{amount_repairs}{Repair assistance amount in dollars.}
+#'     \item{amount_replacement}{Replacement assistance amount in dollars.}
+#'     \item{amount_personal_property}{Personal property assistance amount in dollars.}
+#'     \item{amount_flood_insurance_premium_paid_by_fema}{FEMA-paid flood insurance premium.}
+#'     \item{state_name}{Full state name.}
+#'     \item{state_abbreviation}{Two-letter state abbreviation.}
+#'     \item{state_code}{Two-digit state FIPS code.}
+#'   }
 #' @export
 #'
 #' @examples

R/get_lodes.R

@@ -91,7 +91,6 @@ rename_lodes_variables = function(.df) {
 }
 
 #' Get LEHD Origin-Destination Employment Statistics (LODES) data
-#' Returned data are from LODES Version 8, which is enumerated in 2020-vintage geometries.
 #'
 #' @param lodes_type One of c("rac", "wac", "od"). "rac" = Residence Area
 #'     Characteristics, where jobs are associated with employees' residences.