Update Design Variables on an Existing Survey Object

Updates one or more design variables (weights, cluster IDs, strata, FPC, or replicate weights) on an existing survey design object. Use this after modifying the underlying data — for example, after recalibrating weights or adding a stratification variable. Emits an informational message listing changed variables.

Usage

update_design(
  x,
  ids = NULL,
  weights = NULL,
  strata = NULL,
  fpc = NULL,
  repweights = NULL,
  validate = TRUE
)

Arguments

x

A survey_taylor or survey_replicate object. survey_twophase is not supported; create a new design with as_survey_twophase().

ids

<tidy-select> New cluster (PSU) ID column(s). NULL (default) means no change. Only used for survey_taylor objects.

weights

<tidy-select> New weight column (a single column, values strictly > 0). NULL (default) means no change.

strata

<tidy-select> New stratification column (a single column). NULL (default) means no change. Only used for survey_taylor objects.

fpc

<tidy-select> New finite population correction column (a single column). NULL (default) means no change. Only used for survey_taylor objects.

repweights

<tidy-select> New replicate weight columns (one or more). NULL (default) means no change. Only used for survey_replicate objects.

validate

Logical. If FALSE, temporarily marks the object to suppress validation during the variable update. In practice this has no observable effect on the returned object; validate is accepted for interface compatibility. Default TRUE.

Value

The modified survey object, invisibly. As a side effect, a cli_inform() message is printed listing each changed design variable (old name → new name).

See also

as_survey() to create a survey_taylor object, as_survey_replicate() to create a survey_replicate object, as_survey_twophase() to create a survey_twophase object

Examples

# NHANES has two weight columns for different analysis types;
# start with the MEC examination weight for exam participants
exam <- nhanes_2017[nhanes_2017$ridstatr == 2, ]
d <- as_survey(
  exam,
  ids = sdmvpsu,
  weights = wtmec2yr,
  strata = sdmvstra,
  nest = TRUE
)

# Switch to interview weight for interview-based variables
d_updated <- update_design(d, weights = wtint2yr)
#> ℹ Survey design updated. This may affect statistical validity.
#> ℹ Updated: weights