Create Harmonized Microdata Datasets

Parses a specified `.R` "harmony file" generated by the Survey Harmonization Tool (harmony) to transform raw survey microdata into structured, aligned datasets containing specified harmonized variables. This function serves as a core internal workhorse for fusionInput during the input preparation phase.

Usage

harmonize(
  harmony.file,
  respondent,
  output = "both",
  ncores = getOption("fusionData.cores")
)

Arguments

harmony.file: Character. Filename of a `.R` harmony object located within the `harmony/harmonies/` repository path (e.g., `"RECS_2015__ACS_2015.R"`).
respondent: Character. Desired unit of observation for output microdata; must be either `"household"` or `"person"`.
output: Character. Indicates which microdata dataset(s) to process and return: `"both"` (default), `"donor"`, or `"recipient"`.
ncores: Integer. Number of CPU cores allocated for parallel execution. Defaults to `getOption("fusionData.cores")`.

Value

If `output = "both"`, a named list of two data frames corresponding to donor and recipient microdata. If `output = "donor"` or `"recipient"`, a single data frame. Returned data frames include structural metadata attached as custom R attributes:

`survey`: Name of source survey.
`identifier`: Column names defining unique keys (e.g., `hid`, `pid`).
`employed.vars`: Raw processed variables used to construct the harmonized output.
`geo.vars`: Geographic variable names retained for ACS recipient microdata.
`harmonized.vars`: Full list of harmonized variable names generated.

Details

`harmonize()` executes the variable transformation and aggregation definitions recorded in a harmony file against processed donor and ACS microdata (`survey-processed/*.fst`).

Key internal processing steps include:

* **Microdata Loading:** Dynamically pulls matching household (`H`) and person (`P`) `.fst` files based on the harmony file specifications. * **Variable Transformation & Recoding:** Evaluates custom inline expressions (`adj`), applies categorical grouping (`groups` / `levels`), or assigns numeric break intervals (`breaks`). * **Cross-Level Aggregation & Rescaling:** Automatically converts person-level variables to household-level (via methods such as reference person assignment, mean, min, max) or replicates household attributes across person-level observations as required by the `respondent` level. * **Geographic Attribute Retention:** Automatically extracts state and PUMA geographic identifiers for recipient ACS observations across vintages.

Note

This function is an unexported internal helper within `fusionData`. It is invoked automatically by fusionInput() and typically does not need to be called directly by users.

Examples

if (FALSE) { # \dontrun{
# Harmonize household-level microdata for CEI and ACS
hdata <- harmonize(
  harmony.file = "CEI_2015-2019__ACS_2015.R",
  respondent = "household",
  output = "both"
)
} # }