scf (version 1.0.5)

scf_update_by_implicate: Modify Each Implicate Individually in SCF Data

Description

Each household in SCF data is represented by five implicates, which reflect uncertainty from the imputation process. Most transformations — such as computing log income or assigning categorical bins — can be applied uniformly across implicates using scf_update(). However, some operations depend on the internal distribution of variables within each implicate. For those, you need to modify each one separately.

This function extracts each implicate from the replicate-weighted survey design, applies your transformation, and rebuilds the survey design objects accordingly.

Usage

scf_update_by_implicate(object, f)

Value

A modified scf_mi_survey object with updated implicate-level designs.

Arguments

object

A scf_mi_survey object from scf_load().

f

A function that takes a data frame as input and returns a modified data frame. This function will be applied independently to each implicate.

Use this When

• You need implicate-specific quantiles (e.g., flag households in the top 10% of wealth)

• You want to assign percentile ranks (e.g., income percentile by implicate)

• You are computing statistics within groups (e.g., groupwise z-scores)

• You need to derive a variable based on implicate-specific thresholds or bins

Details

Applies a user-defined transformation to each implicate's data frame separately. This is useful when you need to compute values that depend on the distribution within each implicate — such as ranks, percentiles, or groupwise comparisons — which cannot be computed reliably using scf_update().

See Also

scf_update()

Examples

# Do not implement these lines in real analysis:
# Use functions `scf_download()` and `scf_load()`
td <- tempfile("update_by_implicate_")
dir.create(td)
src <- system.file("extdata", "scf2022_mock_raw.rds", package = "scf")
file.copy(src, file.path(td, "scf2022.rds"), overwrite = TRUE)
scf2022 <- scf_load(2022, data_directory = td)

# Example for real analysis: compute implicate-specific z-scores of income
scf2022 <- scf_update_by_implicate(scf2022, function(df) {
  mu <- mean(df$income, na.rm = TRUE)
  sigma <- sd(df$income, na.rm = TRUE)
  df$z_income <- (df$income - mu) / sigma
  df
})

# Verify new variable exists
head(scf2022$mi_design[[1]]$variables$z_income)

# Do not implement these lines in real analysis: Cleanup for package check
unlink(td, recursive = TRUE, force = TRUE)