Assemble fusionACS microdata across surveys

For fusionACS usage only. Provides a safe and efficient way to assemble (merge) fused microdata across surveys to return a single data table with the requested variables. The requested variables can come from any fused (donor) survey and/or the American Community Survey (ACS). The necessary variables are automatically and efficiently read from the appropriate local file and safely merged on household and/or person ID variables, optionally collapsing or expanding records as necessary depending on the respondent argument. Assumes (and checks for) a local /fusionData directory with appropriate file structure and conventions.

Usage

assemble(
  year,
  var,
  respondent = "household",
  M = 1,
  df = NULL,
  cores = 1,
  source = "all",
  silent = FALSE
)

Arguments

year

Integer. One or more years for which to return results (i.e. the ACS recipient year).

var

Character. Name of one or more variables to return. May contain household- and/or person-level variables. See Details.

respondent

Character. Should "household"- or "person"-level microdata be returned?

M

Integer. The first M implicates are returned for fused variables. Set M = Inf to return all implicates. Ignored if var contains only ACS variables (i.e. no implicates)

df

Data frame. Data frame used to identify a subset of rows to return. Default is to return all rows.

cores

Integer. Number of cores used by the fst-package when reading from disk.

source

Character Specifies where to look for var: all available microdata (source = "all"); only ACS microdata (source = "ACS"); or only fused microdata (source = "fused"). Note that no observation weights are returned if source = "fused", since weights are stored in the ACS microdata.

silent

Logical. If FALSE, a warning is issued if any var cannot be located in available local files.

Value

A keyed data table containing the following columns, in addition to the variables named in var:

M

Implicate number. See fuse.

year

Year of the ACS recipient microdata.

hid

ACS household ID using fusionACS convention.

pid

ACS person ID using fusionACS convention, if respondent = "person".

weight

ACS microdata primary sample weight.

Details

The var argument can contain a mix of household- and/or person-level variables. When respondent = "household", the reference person (i.e. head of household) value is returned for any person-level variables. When respondent = "person", the values of any household-level variables are replicated for each person in the household.

Examples

# NOTE: Requires local /fusionData directory containing the necessary ACS and .fsd files
test <- assemble(year = 2018:2019,
                 var = c("dollarel", "hincp", "agep", "state"),
                 respondent = "household",
                 M = 1)