surveyset: Define a Complex Survey Design for R4VN

In R4VN: Health Data Analysis and Publication-Ready Reporting

Define a Complex Survey Design for R4VN

Description

Creates a reusable complex-survey design for tabsurvey() and future survey-aware R4VN analyses. Designs may include sampling weights, strata, one or more clustering stages, finite-population corrections, or replicate weights. More than one named survey design can be stored in the same R session, which is useful when one data set provides different weights for interviews, examinations, laboratory subsamples, household analyses, and other analytic components.

Usage

surveyset(
  data = NULL,
  name = "survey",
  weight = NULL,
  strata = NULL,
  cluster = NULL,
  fpc = NULL,
  repweights = NULL,
  rep_type = NULL,
  weightscale = c("relative", "population"),
  nest = TRUE,
  pps = FALSE,
  variance = NULL,
  combined.weights = TRUE,
  rho = NULL,
  mse = getOption("survey.replicates.mse"),
  lonely = c("adjust", "fail", "average", "certainty", "remove"),
  active = TRUE
)

Arguments

data	Optional data frame. If omitted, the active R4VN data frame is used.
name	Name used to store the survey design. The default is "survey". Use different names when the same data set requires different survey weights.
weight	Sampling/design/final survey weight. Supply one unquoted variable name or a one-element character vector. If omitted, equal weights are used.
strata	Optional stratum variable(s). Multiple stages may be supplied with vars(...) or c(...).
cluster	Optional cluster/PSU variable(s). For multistage sampling, supply variables in sampling-stage order, for example cluster = vars(psu, ssu).
fpc	Optional finite-population correction variable(s), in the same stage order as the cluster variables when applicable.
repweights	Optional replicate-weight variables, supplied with vars(...), a character vector, a wildcard selector, or a column range such as rep1:rep80.
rep_type	Replicate design type passed to survey, such as "BRR", "Fay", "JK1", "JKn", or "bootstrap". Required when repweights is supplied.
weightscale	Meaning of the supplied weights. "relative" (default) means the weights are suitable for weighted estimates and design-based inference but their sum must not automatically be called a population total. "population" means the weights are expansion weights whose scale supports estimated population totals.
nest	Logical. Treat cluster identifiers as nested within strata. The default is TRUE, which is safe when PSU identifiers are reused in different strata.
pps	Optional PPS specification passed to survey::svydesign(). The default is FALSE. Advanced users may pass a supported survey PPS object or method.
variance	Optional PPS variance estimator passed to survey::svydesign().
combined.weights	Logical argument used for replicate-weight designs.
rho	Optional Fay coefficient for appropriate replicate designs.
mse	Logical argument used for replicate-weight variance estimation.
lonely	Handling of strata containing a single PSU. Supported values are "adjust" (default), "fail", "average", "certainty", and "remove".
active	Logical. The named design is always stored under name. If TRUE (default), it also becomes the active R4VN survey design used when tabsurvey() is called without design=.

Details

Weight meaning is explicit. R4VN deliberately does not assume that sum(weight) is a population size. Many public-use surveys provide normalized or relative weights. Set weightscale = "population" only when documentation for the survey confirms that the weight has an expansion/population interpretation.

Multiple named designs. A single survey file may contain different weights for different analytic subsamples. Define each one separately, for example "interview" and "fasting", and select it in tabsurvey(design = "fasting").

Survey weight versus other weights. The weight argument is intended for sampling/design/final survey weights. Propensity-score IPTW, frequency weights, analytic weights, and arbitrary regression weights are different concepts and should not be silently treated as survey sampling weights.

After changing the data. A survey design stores the data and design information that existed when surveyset() was called. If rows or variables are changed afterward, recreate the survey design so the design and analytic data remain aligned.

Value

An object of class r4vn_survey. The design is stored internally under name; when active = TRUE it also becomes the active survey design.

See Also

tabsurvey, vars, usedf

Other R4VN survey: tabsurvey()

Examples

set.seed(2026)
n <- 600
d <- data.frame(
  psu = sample(1:60, n, TRUE),
  strata = sample(1:8, n, TRUE),
  wt = runif(n, 0.5, 2.5),
  age = rnorm(n, 45, 14),
  sex = factor(sample(c("Female", "Male"), n, TRUE)),
  hypertension = factor(sample(c("No", "Yes"), n, TRUE,
                               prob = c(.72, .28)))
)

usedf(d)
surveyset(weight = wt, strata = strata, cluster = psu)

# A second named design for a hypothetical laboratory subsample
d$labwt <- d$wt * runif(n, .8, 1.2)
surveyset(d, name = "lab", weight = labwt,
          strata = strata, cluster = psu, active = FALSE)

# Inspect the active design
summary(surveyset(d, weight = wt, strata = strata, cluster = psu))

R4VN documentation built on Sept. 30, 2026, 5:13 p.m.