Package 'surveycore'

Description

Returns a flat character vector of all design-variable column names (ids, weights, strata, fpc) for any survey design class. NULL entries are dropped; names are unique. Exported for use by extension packages (e.g., surveytidy); not intended for end users.

Usage

.get_design_vars_flat(design)

Arguments

Value

A character vector of column names.

Description

All person records from the 2022 American Community Survey (ACS) 1-Year Public Use Microdata Sample (PUMS) for Wyoming (state FIPS 56). Wyoming is the least-populous U.S. state, making this the smallest state-level PUMS file — ideal for fast tests and examples.

Usage

acs_pums_wy

Format

A data frame with 5,962 rows and 96 variables. Columns pwgtp1 through pwgtp80 are the 80 successive difference replicate weights for variance estimation; the remaining 16 variables are:

• puma: Public Use Microdata Area code. Use as the cluster ID (PSU) for variance estimation.

• st: State FIPS code (all 56 = Wyoming).

• pwgtp: Person weight. Represents the number of people in the Wyoming population that this record represents.

• agep: Age (0–99 years).

• sex: Sex (1 = male, 2 = female).

• rac1p: Recoded detailed race (1 = White alone, 2 = Black or African American alone, 3 = American Indian alone, 6 = Asian alone, 9 = Two or more races).

• hisp: Recoded Hispanic origin (01 = Not Spanish/Hispanic/Latino; 02–24 = specific Hispanic origin).

• schl: Educational attainment (24 categories: 01 = no schooling, 16 = regular high school diploma, 21 = bachelor's degree, 24 = doctorate degree).

• esr: Employment status recode (1 = civilian employed at work, 2 = civilian employed with job but not at work, 3 = unemployed, 4 = Armed Forces at work, 5 = Armed Forces not at work, 6 = Not in labor force).

• pincp: Total person income in the past 12 months (dollars, signed; negative values indicate a net loss). Multiply by adjinc / 1e6 to adjust to constant dollars.

• wagp: Wages or salary income in the past 12 months (dollars). NA if not applicable.

• hicov: Health insurance coverage (1 = with health insurance, 2 = without health insurance).

• dis: Disability recode (1 = with a disability, 2 = without a disability).

• povpip: Income-to-poverty ratio (0–501; 501 means 501% or more).

• wkhp: Usual hours worked per week in the past 12 months. NA if not in the labor force.

• adjinc: Adjustment factor for income and earnings. Divide by 1,000,000 and multiply income variables to convert to 2022 constant dollars.

Details

Survey design: Successive difference replication (SDR). Use as_survey_replicate() with all 80 replicate weights:

svy <- as_survey_replicate(
  acs_pums_wy,
  weights    = pwgtp,
  repweights = pwgtp1:pwgtp80,
  type       = "successive-difference"
)

Income adjustment: Income variables (pincp, wagp) are in survey-year dollars. Multiply by adjinc / 1e6 to convert to 2022 inflation-adjusted dollars before comparing across ACS years.

Metadata: The ACS PUMS source is a plain CSV with no embedded labels. Columns in acs_pums_wy carry no "label", "labels", or "question_preface" attributes. Variable descriptions are documented here in ?acs_pums_wy and in data-raw/README.md. Use set_var_label() and set_val_labels() to attach labels manually before analysis if needed.

Source

U.S. Census Bureau. 2022 ACS 1-Year PUMS. https://www.census.gov/programs-surveys/acs/microdata/access.html

Examples

# Wyoming population represented
sum(acs_pums_wy$pwgtp)

# Age distribution
hist(acs_pums_wy$agep, main = "Age distribution, Wyoming 2022", xlab = "Age")

# Confirm 80 replicate weights are present
sum(grepl("^pwgtp[0-9]", names(acs_pums_wy)))

Description

Appends one or more surveys to an existing collection and returns a new survey_collection. The original collection is unchanged. Surveys may be passed with explicit names or as bare symbols (auto-named, like as_survey_collection()). Duplicate names are repaired by appending ⁠_1⁠, ⁠_2⁠, … Existing names are never modified during repair.

Usage

add_survey(.collection, ...)

Arguments

Details

Calling add_survey(x) with no additional surveys returns x unchanged; no error is raised.

Value

A new survey_collection with the appended surveys.

See Also

as_survey_collection(), remove_survey()

Other collections: as_survey_collection(), remove_survey(), set_collection_id(), set_collection_if_missing_var(), survey_collection()

Examples

d1 <- as_survey(
  gss_2024,
  ids = vpsu,
  weights = wtssps,
  strata = vstrat,
  nest = TRUE
)
d2 <- as_survey(
  gss_2024,
  ids = vpsu,
  weights = wtssps,
  strata = vstrat,
  nest = TRUE
)
coll <- as_survey_collection(a = d1)
coll2 <- add_survey(coll, b = d2)
names(coll2)

Description

A 19-variable extract from the 2024 American National Election Studies (ANES) Time Series Study, a landmark biennial pre- and post-election survey of the American electorate. Fielded via face-to-face interview and web (n = 5,521). This extract uses the FTF + Web combined design variables (v240103a–v240103d), the recommended set for most analyses.

Usage

anes_2024

Format

A data frame with 5,521 rows and 19 variables:

v240103a

Pre-election weight (FTF+Web combined). Use for variables asked before November 5, 2024.

v240103b

Post-election weight (FTF+Web combined). Use for variables asked after November 5, 2024.

v240103c

PSU (FTF+Web combined). Use as the cluster ID for variance estimation.

v240103d

Stratum (FTF+Web combined). Use as the stratification variable.

v240001

2024 Time Series Case ID. Unique respondent identifier.

v240003

Sample type: 1 = Panel, 2 = Fresh Web, 3 = Fresh FTF, 4 = GSS.

v240002c

Pre/Post interview completion: 1 = Pre-election only, 2 = Pre- and post-election.

v243002

State FIPS code.

v243007

Census region: 1 = Northeast, 2 = Midwest, 3 = South, 4 = West.

v241458x

Age on Election Day (summary). Top-coded at 80. -2 = missing.

v241550

Sex: 1 = male, 2 = female.

v241501x

Race/ethnicity (5-category summary): White non-Hispanic, Black non-Hispanic, Hispanic, Asian/NHPI non-Hispanic, Other/Multiracial non-Hispanic.

v241465x

Education (5-category summary): 1 = less than HS, 2 = HS diploma, 3 = some college, 4 = bachelor's degree, 5 = graduate degree.

v241566x

Household income (28 categories from < $5,000 to $250,000+).

v241177

Liberal-conservative self-placement (7-point scale): 1 = extremely liberal, 7 = extremely conservative. 99 = haven't thought about this.

v241222

Party identification strength: 1 = strong, 2 = not very strong.

v241223

Party identification lean (Independents): 1 = closer to Republican, 2 = neither, 3 = closer to Democrat.

v242066

Did respondent vote for President (POST): 1 = yes, 2 = no.

v242067

Presidential vote choice (POST): 1 = Harris, 2 = Trump, 3 = RFK Jr., 4 = West, 5 = Stein, 6 = Other.

Details

Survey design: Stratified cluster — use Taylor series linearization. Two weights are available depending on whether the analysis uses pre- or post-election variables:

# Pre-election analysis (party ID, ideology, candidate preference)
svy_pre <- as_survey(anes_2024,
  ids     = v240103c,
  strata  = v240103d,
  weights = v240103a,
  nest    = TRUE
)

# Post-election analysis (validated vote choice)
svy_post <- as_survey(anes_2024,
  ids     = v240103c,
  strata  = v240103d,
  weights = v240103b,
  nest    = TRUE
)

Missing value codes: The ANES uses negative integer codes for missing data throughout: -9 = Refused, -8 = Don't know, -4 = Technical error, -1 = Inapplicable, and others. These must be recoded to NA before analysis. Check attr(anes_2024$v241177, "labels") for the full set of codes for a given variable.

Metadata: All columns carry variable labels and value labels as R attributes from the original Stata file, automatically extracted into surveycore's metadata system when you call as_survey().

• Variable labels ("label" attribute): A human-readable description of each column. Example: attr(anes_2024$v241550, "label") returns "PRE: What is your sex?" (or similar ANES phrasing).

• Value labels ("labels" attribute): A named numeric vector mapping each code to its meaning, including all missing-value codes. Example: attr(anes_2024$v241550, "labels") returns a vector with entries for Male, Female, and the applicable negative missing codes.

Source

American National Election Studies. 2024 Time Series Study. Available at electionstudies.org (free account required to download raw data; the processed .rda is included in the package). Prepared by ⁠data-raw/prepare-anes-2024.R⁠.

Examples

# Variables in the dataset
names(anes_2024)

# Create pre-election design
svy <- as_survey(
  anes_2024,
  ids = v240103c,
  strata = v240103d,
  weights = v240103a,
  nest = TRUE
)

# Inspect variable label (ANES uses opaque V-codes; labels give context)
attr(anes_2024$v241177, "label")

# Inspect value labels, including missing-value codes
attr(anes_2024$v241177, "labels")

Description

S3 method that dispatches to get_anova(). Pass one or two survey_glm_fit objects; the single-model or pairwise path is chosen automatically.

Usage

## S3 method for class 'survey_glm_fit'
anova(object, ..., method = "LRT", test = "F", null = NULL)

Arguments

Value

A survey_anova tibble; see get_anova() for column details.

Description

Constructs a calibration data object from base sampling weights, g-weights (calibration factors), and a model matrix of calibration covariates. The returned list is suitable for assignment to the ⁠@calibration⁠ slot of a survey_taylor or survey_replicate object.

Usage

as_caldata(base_weights, g_weights, model_matrix)

Arguments

Details

The resulting calibration object is used by the variance estimation routines to apply a Deville-Sarndal (1992) calibration correction to Taylor-series and replicate-weight variance estimates.

GLM limitation: Using a calibrated survey_taylor object with survey_glm() produces correct but conservative standard errors until GREG-GLM variance is implemented in a future release. The calibration correction is not applied in the GLM variance path.

Value

A named list with four elements:

qr

A QR decomposition (class "qr") of sqrt(base_weights) * model_matrix. Used for calibration projection in variance estimation.

w

A numeric vector of length n equal to g_weights * sqrt(base_weights). This intermediate quantity (the square root of the calibrated weights scaled by g) is used directly in the GREG variance projection formula.

stage

Integer scalar 0L. Currently only between-PSU calibration (stage 0) is supported.

index

NULL. Reserved for future within-PSU calibration support.

Inter-package contract

GREG calibration (single auxiliary variable or multiple uncorrelated variables): pass the model matrix from model.matrix(formula, data) directly – one column per calibration variable. The intercept column ((Intercept)) is included by default from model.matrix(); it contributes one degree of freedom to the calibration adjustment.

Raking (multiple calibration margins, Architecture A): combine all margin indicator matrices into a single matrix before calling as_caldata(). Column-bind the matrices and drop one reference column per margin to avoid rank deficiency (e.g., drop the last column of each per-margin block). Pass this single combined matrix. Do not call as_caldata() once per margin; that uses Architecture B (sequential), which requires a separate as_caldata() element per calibration pass and stores them all in the @calibration list.

q_k = 1 assumption: as_caldata() always assumes $q_k = 1$ (uniform calibration weights). If your calibration uses a non-unity $q_k$ (variance-function weights from survey::calibrate( calfun = "linear", variance = ...)) you must absorb those weights into model_matrix before calling as_caldata().

For survey_replicate designs

@calibration on a survey_replicate object is provenance-only: it documents that the replicate weights were derived from a calibrated design, but the variance estimator does not apply any GREG projection. Calibration is already encoded in the replicate weights themselves. Do not expect get_means() SE to differ between a survey_replicate with and without @calibration set.

References

Deville, J.-C., and Sarndal, C.-E. (1992). Calibration estimators in survey sampling. Journal of the American Statistical Association, 87, 376–382.

See Also

as_survey() for Taylor series designs, as_survey_replicate() for replicate-weight designs, as_survey_twophase() for two-phase designs

Other constructors: as_survey(), as_survey_nonprob(), as_survey_replicate(), as_survey_twophase(), survey_glm(), survey_glm_fit(), survey_nonprob(), survey_replicate(), survey_taylor(), survey_twophase()

Examples

# Minimal example: 3-unit design, intercept-only calibration
base_weights <- c(2.5, 3.0, 4.0)
g_weights <- c(1.02, 0.98, 1.01)
model_matrix <- matrix(1, nrow = 3, ncol = 1)

cd <- as_caldata(base_weights, g_weights, model_matrix)
names(cd) # "qr", "w", "stage", "index"

# Assign to a survey_taylor design
df <- data.frame(y = c(1.2, 2.3, 3.4), wt = base_weights)
design <- as_survey(df, weights = wt)
design@calibration <- list(cd)
is.null(design@calibration) # FALSE

Description

Creates a survey design object using Taylor series (linearization) for variance estimation. Supports simple random samples, stratified designs, single- and multi-stage cluster designs, and designs with finite population correction. Uses a tidy-select interface for all design variable arguments.

Usage

as_survey(
  data,
  ids = NULL,
  probs = NULL,
  weights = NULL,
  strata = NULL,
  fpc = NULL,
  nest = FALSE,
  calibration = NULL
)

Arguments

Value

A survey_taylor object.

Tidy-select

All design variable arguments (ids, probs, weights, strata, fpc) support tidy-select syntax: bare column names, c() to combine multiple columns (multi-stage ids = c(psu, ssu), multi-stage fpc), and tidyselect helpers like starts_with(). See the Examples section below for runnable demonstrations.

Simple random sample

When no ids or strata are specified, the result is a survey_taylor object with NULL ids and strata — i.e., a simple random sample (SRS). The Taylor variance machinery produces the same estimates as the classical SRS formula (1 - f) * s^2 / n. If weights and probs are also both omitted, uniform weights are assigned and a warning is issued.

Known limitations

as_survey() does not support probability-proportional-to-size (PPS) variance estimation. Taylor series linearization treats all designs as with-replacement, which overestimates (is conservative for) variance in PPS-without-replacement designs. The Yates-Grundy and Brewer/Overton estimators available in survey::svydesign() via its pps and variance arguments are not supported.

If your design requires PPS-specific variance estimation, create the design with survey::svydesign() and convert it with from_svydesign():

d_survey <- survey::svydesign(
  ids = ~psu, weights = ~wt, strata = ~stratum,
  pps = "brewer", data = mydata
)
d <- from_svydesign(d_survey)

References

Deville, J.-C. and Sarndal, C.-E. (1992) Calibration estimators in survey sampling. Journal of the American Statistical Association 87(418), 376–382.

Deville, J.-C., Sarndal, C.-E. and Sautory, O. (1993) Generalized raking procedures in survey sampling. Journal of the American Statistical Association 88(423), 1013–1020.

Lumley, T. (2004) Analysis of complex survey samples. Journal of Statistical Software 9(1), 1–19.

Lumley, T. (2010) Complex Surveys: A Guide to Analysis Using R. John Wiley and Sons.

Rao, J.N.K., Yung, W. and Hidiroglou, M.A. (2002) Estimating equations for the analysis of survey data using poststratification information. Sankhya 64-A, 22–36.

Sarndal, C-E., Swensson, B. and Wretman, J. (1992) Model Assisted Survey Sampling. Springer.

See Also

as_survey_replicate() for replicate-weight designs, as_survey_twophase() for two-phase designs, set_var_label() to add variable labels

Other constructors: as_caldata(), as_survey_nonprob(), as_survey_replicate(), as_survey_twophase(), survey_glm(), survey_glm_fit(), survey_nonprob(), survey_replicate(), survey_taylor(), survey_twophase()

Examples

# Full NHANES design: stratified cluster with PSU IDs nested within strata
d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)

# Stratified design without PSU cluster IDs
d_strat <- as_survey(nhanes_2017, weights = wtint2yr, strata = sdmvstra)

# Blood pressure analysis: filter to exam participants, use MEC weight
exam <- nhanes_2017[nhanes_2017$ridstatr == 2, ]
d_bp <- as_survey(
  exam,
  ids = sdmvpsu,
  weights = wtmec2yr,
  strata = sdmvstra,
  nest = TRUE
)

# c() to combine multiple columns — sketched on a synthetic two-stage frame
df <- data.frame(
  psu = rep(1:5, each = 4),
  ssu = 1:20,
  wt = runif(20, 0.5, 2)
)
d_ms <- as_survey(df, ids = c(psu, ssu), weights = wt)

# Tidy-select helpers like starts_with() also work
d_h <- as_survey(
  gss_2024,
  ids = vpsu,
  strata = vstrat,
  weights = starts_with("wtssn"),
  nest = TRUE
)

Description

Builds a survey_collection from one or more survey design objects for comparative analysis across waves, cross-sections, or sub-populations. Each element is stored independently — designs are never combined, and variance estimation is never re-specified.

Usage

as_survey_collection(..., group, .id = ".survey", .if_missing_var = "error")

Arguments

Details

Arguments may be passed with explicit names ("wave1" = d1) or as bare symbols (d1, auto-named to "d1"). An unnamed argument that is not a bare symbol (e.g., an inline as_survey(...) call) raises surveycore_error_collection_unnamed_expr — name such arguments explicitly.

Duplicate names are repaired by appending ⁠_1⁠, ⁠_2⁠, … to subsequent occurrences (first occurrence preserved). When any rename occurs, a surveycore_warning_collection_duplicate_name_repaired warning is emitted showing the original -> repaired mapping.

Value

A survey_collection object containing the supplied surveys.

See Also

survey_collection, add_survey(), remove_survey()

Other collections: add_survey(), remove_survey(), set_collection_id(), set_collection_if_missing_var(), survey_collection()

Examples

d1 <- as_survey(
  gss_2024,
  ids = vpsu,
  weights = wtssps,
  strata = vstrat,
  nest = TRUE
)
d2 <- as_survey(
  gss_2024,
  ids = vpsu,
  weights = wtssps,
  strata = vstrat,
  nest = TRUE
)

# Explicit names
coll <- as_survey_collection("2020" = d1, "2024" = d2)
names(coll)

# Bare-symbol auto-naming
coll2 <- as_survey_collection(d1, d2)
names(coll2)

# Uniform grouping across members
coll3 <- as_survey_collection(d1, d2, group = vstrat)
names(survey_data(coll3[[1L]]))

Description

Creates a survey design object for non-probability samples (e.g., online panels, quota samples, volunteer panels). Accepts pre-computed calibration weights (including raking and post-stratification) or inverse probability weighting (IPW) pseudo-weights.

Usage

as_survey_nonprob(
  data,
  weights,
  repweights = NULL,
  type = "bootstrap",
  scale = NULL,
  rscales = NULL,
  mse = TRUE,
  reference_sample = NULL,
  calibration = NULL
)

Arguments

Details

Unlike probability samples, non-probability samples have no design weights derived from known selection probabilities, which means estimates carry additional uncertainty not captured by standard design-based variance formulas. Per Elliott and Valliant (2017), Valliant, Dever, and Kreuter (2018), and Brick (2015), bootstrap or jackknife replicate weights are the recommended approach for variance estimation — they propagate calibration uncertainty into standard errors. Note, however, that replicate variance addresses calibration uncertainty only; it does not resolve uncertainty about the selection mechanism itself, which requires untestable modeling assumptions about the relationship between sample membership and the survey variables of interest. Without replicate weights, standard errors use a model-assisted SRS approximation that systematically underestimates variance for non-probability samples.

When repweights is supplied, the variance estimator uses the replicate formula: V = scale * sum(rscales * (theta_r - theta)^2). For bootstrap replicates (type = "bootstrap"), the default scale = 1/R follows Wu (2022) and Chen et al. (2021). For jackknife replicates (type = "JK1", "JK2", or "JKn"), scale and rscales follow the standard jackknife variance conventions; see type for defaults.

When repweights = NULL, standard errors use an SRS approximation (treating each observation as its own PSU). This understates calibration uncertainty; see vignette("creating-survey-objects") for details.

Value

A survey_nonprob object.

When to use

Use as_survey_nonprob() instead of as_survey() when:

• Your data comes from a non-probability sample (online panel, quota sample, MTurk/Prolific, etc.)

• You have calibration or raking weights but no probability sampling design structure (no PSU IDs, strata, etc.)

• You want to explicitly record the provenance of your calibration weights for reproducibility

If your data comes from a probability sample with known design structure, use as_survey(), as_survey_replicate(), or as_survey_twophase() instead.

Variance estimation

Two modes are available, depending on whether repweights is supplied:

SRS approximation (repweights = NULL, the default)

Standard errors treat the calibrated weights as fixed and assume simple random sampling. This is a model-assisted approximation that understates calibration uncertainty. Use this mode only when replicate weights are unavailable; interpret standard errors with caution (Valliant 2020; Elliott and Valliant 2017).

Bootstrap variance (repweights supplied)

Each replicate weight column must contain calibrated weights re-estimated on one bootstrap draw (i.e., raking or post-stratification was re-applied within each replicate). This propagates calibration uncertainty into the variance estimate and is the recommended approach (Chrostowski et al. 2025; Kolenikov 2014).

See vignette("creating-survey-objects") for guidance on choosing between these modes and on the limitations of SRS-based variance for calibrated non-probability samples.

References

Valliant, R. (2020). Comparing alternatives for estimation from nonprobability samples. Journal of Survey Statistics and Methodology 8(2), 231–263. doi:10.1093/jssam/smz003

Elliott, M.R. and Valliant, R. (2017). Inference for nonprobability samples. Statistical Science 32(2), 249–264.

Chrostowski, M.J., Guzman, C.A. and Malm, L. (2025). Variance estimation for non-probability surveys. Journal of Survey Statistics and Methodology (forthcoming).

Brick, J.M. (2015). Compositional model inference. In Proceedings of the Section on Survey Research Methods, pp. 299–307. American Statistical Association, Alexandria, VA.

Valliant, R., Dever, J.A. and Kreuter, F. (2018). Practical Tools for Designing and Weighting Survey Samples, 2nd ed. Springer, New York.

Kolenikov, S. (2014). Calibrating variance estimation with proxy variables. Survey Methodology 40(1), 21–38.

Wu, C. (2022). Statistical inference with non-probability survey samples. Survey Methodology 48(2), 283–311.

Chen, Y., Li, P. and Wu, C. (2021). Doubly robust inference with non-probability survey samples. Journal of the American Statistical Association 115(532), 2011–2021.

See Also

as_survey() for probability designs with Taylor variance, as_survey_replicate() for replicate-weight designs

Other constructors: as_caldata(), as_survey(), as_survey_replicate(), as_survey_twophase(), survey_glm(), survey_glm_fit(), survey_nonprob(), survey_replicate(), survey_taylor(), survey_twophase()

Examples

# Minimal: pre-computed calibration weights, SRS-based variance
df <- data.frame(
  y = rnorm(200),
  age = sample(c("18-34", "35-54", "55+"), 200, replace = TRUE),
  cal_wt = runif(200, 0.5, 2.5)
)
d <- as_survey_nonprob(df, weights = cal_wt)

# Bootstrap variance: replicate weights with calibration re-applied in each
set.seed(1)
R <- 50
rep_cols <- setNames(
  as.data.frame(
    matrix(runif(200 * R, 0.5, 2.5), nrow = 200)
  ),
  paste0("rep_", seq_len(R))
)
df_rep <- cbind(df, rep_cols)
d_boot <- as_survey_nonprob(
  df_rep,
  weights = cal_wt,
  repweights = starts_with("rep_"),
  type = "bootstrap"
)

# Jackknife variance (JK1): delete-one replicate weights
d_jk <- as_survey_nonprob(
  df_rep,
  weights = cal_wt,
  repweights = starts_with("rep_"),
  type = "JK1"
)

Description

Creates a survey design object using replicate weights for variance estimation. Supports all common replicate methods: jackknife (JK1, JK2, JKn), balanced repeated replication (BRR, Fay), bootstrap, ACS, successive-difference, and user-defined types. Uses a tidy-select interface for weight and replicate-weight columns.

Usage

as_survey_replicate(
  data,
  weights,
  repweights,
  type = c("JK1", "JK2", "JKn", "BRR", "Fay", "bootstrap", "ACS",
    "successive-difference", "other"),
  scale = NULL,
  rscales = NULL,
  fpc = NULL,
  fpctype = c("fraction", "correction"),
  mse = TRUE,
  calibration = NULL
)

Arguments

Value

A survey_replicate object.

Tidy-select

Both weights and repweights support tidy-select syntax:

# Bare name for weights
as_survey_replicate(
  df, weights = wt, repweights = starts_with("repwt"), type = "BRR"
)
# c() for explicit replicate columns
as_survey_replicate(
  df, weights = wt, repweights = c(rep1, rep2, rep3), type = "JK1"
)

Replicate weight matrix

The replicate weight matrix is not stored in the object. Only the column names are stored in ⁠@variables$repweights⁠. Variance estimation computes the matrix on demand: as.matrix(design@data[, design@variables$repweights]).

Memory usage

Each call to an estimation function (e.g., get_means(), get_totals()) materialises the full replicate weight matrix from the data frame. For large designs (e.g., ACS PUMS with 500k+ rows × 80 replicates), this is roughly nrow * n_replicates * 8 bytes per call (~363 MB for ACS Wyoming × 80). If you are estimating many variables, this is repeated for each call. This behaviour matches the survey package reference implementation.

References

Canty, A.J. and Davison, A.C. (1999) Resampling-based variance estimation for labour force surveys. The Statistician 48(3), 379–391.

Deville, J.-C. and Sarndal, C.-E. (1992) Calibration estimators in survey sampling. Journal of the American Statistical Association 87(418), 376–382.

Deville, J.-C., Sarndal, C.-E. and Sautory, O. (1993) Generalized raking procedures in survey sampling. Journal of the American Statistical Association 88(423), 1013–1020.

Judkins, D.R. (1990) Fay's method for variance estimation. Journal of the American Statistical Association 85(410), 895–904.

Rao, J.N.K., Wu, C.F.J. and Yue, K. (1992) Some recent work on resampling methods for complex surveys. Survey Methodology 18(2), 209–217.

Shao, J. and Tu, D. (1995) The Jackknife and Bootstrap. Springer.

See Also

as_survey() for Taylor series designs, as_survey_twophase() for two-phase designs, set_var_label() to add variable labels

Other constructors: as_caldata(), as_survey(), as_survey_nonprob(), as_survey_twophase(), survey_glm(), survey_glm_fit(), survey_nonprob(), survey_replicate(), survey_taylor(), survey_twophase()

Examples

# ACS PUMS Wyoming: 80 successive-difference replicate weights
d_acs <- as_survey_replicate(
  acs_pums_wy,
  weights = pwgtp,
  repweights = pwgtp1:pwgtp80,
  type = "successive-difference"
)

# Explicit replicate columns using c()
d_sub <- as_survey_replicate(
  acs_pums_wy,
  weights = pwgtp,
  repweights = c(pwgtp1, pwgtp2, pwgtp3, pwgtp4),
  type = "JK1"
)

Description

Creates a two-phase (double) sampling design from an existing survey_taylor Phase 1 object. Phase 1 covers all rows; Phase 2 is a strict subset indicated by a logical column. Uses a tidy-select interface for all Phase 2 design variable arguments.

Usage

as_survey_twophase(
  phase1,
  ids2 = NULL,
  strata2 = NULL,
  probs2 = NULL,
  fpc2 = NULL,
  subset,
  method = c("full", "approx", "simple")
)

Arguments

Details

Variance methods

• "full" — Full two-phase variance formula. Accounts for variability in both phases. Requires Phase 2 design information (probs2, ids2, strata2) when Phase 2 is not a simple random subsample. If none of these are provided, an error is raised.

• "approx" — Approximation that ignores Phase 1 sampling variability. Faster but less accurate than "full" when the Phase 1 sampling fraction is non-negligible.

• "simple" — Treats Phase 2 as a single-phase design, ignoring Phase 1. Only valid when Phase 1 is a census (no sampling). Issues a warning when Phase 1 has PSU cluster variables, because this understates variance for clustered designs.

Value

A survey_twophase object.

References

Sarndal, C-E., Swensson, B. and Wretman, J. (1992) Model Assisted Survey Sampling. Springer.

Breslow, N.E. and Chatterjee, N. (1999) Design and analysis of two-phase studies with binary outcome applied to Wilms tumour prognosis. Applied Statistics 48, 457–468.

Breslow, N., Lumley, T., Ballantyne, C.M., Chambless, L.E. and Kulick, M. (2009) Improved Horvitz-Thompson estimation of model parameters from two-phase stratified samples: applications in epidemiology. Statistics in Biosciences. doi:10.1007/s12561-009-9001-6

See Also

as_survey() for Taylor series designs, as_survey_replicate() for replicate-weight designs

Other constructors: as_caldata(), as_survey(), as_survey_nonprob(), as_survey_replicate(), survey_glm(), survey_glm_fit(), survey_nonprob(), survey_replicate(), survey_taylor(), survey_twophase()

Examples

# Minimal two-phase design: Phase 1 = full cohort, Phase 2 = random subset
df <- data.frame(
  id = 1:20,
  wt = rep(2, 20),
  in_phase2 = c(rep(TRUE, 10), rep(FALSE, 10)),
  y = rnorm(20)
)
phase1 <- as_survey(df, ids = id, weights = wt)
d2 <- as_survey_twophase(phase1, subset = in_phase2)

# With Phase 2 stratification and inclusion probabilities
df2 <- data.frame(
  id = 1:30,
  wt = rep(3, 30),
  in_phase2 = c(rep(TRUE, 15), rep(FALSE, 15)),
  arm = rep(c("A", "B", "C"), 10),
  subsamprate = rep(c(0.5, 0.7, 0.3), 10),
  y = rnorm(30)
)
phase1b <- as_survey(df2, ids = id, weights = wt)
d2b <- as_survey_twophase(
  phase1b,
  strata2 = arm,
  probs2 = subsamprate,
  subset = in_phase2,
  method = "full"
)

Description

Converts a survey_taylor, survey_replicate, or survey_twophase object to the corresponding survey package object: svydesign, svrepdesign, or twophase. Useful for accessing survey package estimation functions or for round-trip testing.

Usage

as_svydesign(x)

Arguments

Details

Metadata (variable labels, value labels) is NOT carried over — the survey package has no metadata system.

Value

A survey::svydesign, survey::svrepdesign, or survey::twophase object.

See Also

from_svydesign() to convert back from a survey design

Other conversion: as_tbl_svy(), from_svydesign(), from_tbl_svy()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
if (requireNamespace("survey", quietly = TRUE)) {
  sv <- as_svydesign(d)
  survey::svymean(~ridageyr, sv, na.rm = TRUE)
}

Description

Converts a surveycore design object to an srvyr tbl_svy by first converting to a survey design via as_svydesign() and then wrapping with srvyr::as_survey(). Requires both survey and srvyr.

Usage

as_tbl_svy(x)

Arguments

Details

Metadata (variable labels, value labels) is NOT carried over.

Value

A srvyr::tbl_svy object.

See Also

from_tbl_svy() to convert back from a tbl_svy object

Other conversion: as_svydesign(), from_svydesign(), from_tbl_svy()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
if (
  requireNamespace("survey", quietly = TRUE) &&
    requireNamespace("srvyr", quietly = TRUE)
) {
  ts <- as_tbl_svy(d)
}

Description

A simple random sample from the 2000 California Academic Performance Index (API) study. 200 schools were randomly sampled. This is the same underlying data as apisrs in the survey package, reformatted to surveycore conventions.

Usage

ca_api_2000

Format

A data frame with 200 rows and 38 variables:

pw

Sampling weight (inverse probability of selection).

fpc

FPC (number of schools in the California API system).

cds

County/district/school code (character, 14-digit).

snum

School number (integer).

dnum

District number (integer).

name

Short school name (character).

sname

Full school name (character).

dname

District name (character).

cname

County name (character).

cnum

County number (integer).

api00

API score 2000 (integer).

api99

API score 1999 (integer).

target

API growth target (integer).

growth

API score change, api00 - api99 (integer).

pcttest

Percent of students tested (integer).

sch_wide

Met school-wide growth target (integer, 0 = No, 1 = Yes).

comp_imp

Met comparable improvement target (integer, 0 = No, 1 = Yes).

both

Met both targets (integer, 0 = No, 1 = Yes).

awards

Eligible for awards program (integer, 0 = No, 1 = Yes).

stype

School type (integer): 1 = Elementary, 2 = High, 3 = Middle.

yr_rnd

Year-round school (integer, 0 = No, 1 = Yes).

meals

Percent of students receiving free meals (integer).

ell

Number of English language learners (integer).

mobility

Percent of students in first year at school (integer).

enroll

Total number of students (integer).

api_stu

Number of students included in API 2000 (integer).

acs_k3

Average class size, grades K–3 (integer; NA for high and middle schools).

acs_46

Average class size, grades 4–6 (integer; NA for high schools and some others).

acs_core

Average class size, core academic courses (integer; NA for most elementary schools).

not_hsg

Percent of parents who did not complete high school (integer).

hsg

Percent of parents who are high school graduates (integer).

some_col

Percent of parents with some college (integer).

col_grad

Percent of parents who are college graduates (integer).

grad_sch

Percent of parents with graduate school education (integer).

avg_ed

Average parent education level (numeric).

pct_resp

Percent of parents who responded to the survey (integer).

full

Percent of teachers fully credentialed (integer).

emer

Percent of teachers on emergency credentials (integer).

Details

Survey design: Simple random sample. Use as_survey() with weights = pw and fpc = fpc:

svy <- as_survey(
  ca_api_2000,
  weights = pw,
  fpc = fpc
)

Missing values: Several columns have NA for schools where the value is inapplicable: acs_k3 (grades K–3) is NA for high schools and middle schools, where those grade spans do not exist; acs_46 (grades 4–6) is NA for all high schools and some elementary and middle schools; acs_core is NA for most elementary schools.

Metadata: All 38 columns carry "label" attributes (human-readable variable descriptions). The six categorical columns (stype, sch_wide, comp_imp, both, awards, yr_rnd) additionally carry "labels" attributes mapping integer codes to category names, compatible with surveycore's metadata system.

Relationship to apisrs: This dataset contains the same observations as survey::apisrs, with three differences: (1) the all-NA flag column is dropped; (2) factor columns are stored as plain integers with labels attributes; (3) column names are in snake_case.

Source

Lumley T (2004). Analysis of complex survey samples. Journal of Statistical Software, 9(1):1–19. Data distributed with the survey R package.

California Department of Education, Academic Performance Index 2000.

Examples

head(ca_api_2000[, c("pw", "fpc", "api00", "enroll")])

# Create an SRS design
svy <- as_survey(ca_api_2000, weights = pw, fpc = fpc)
svy

# Inspect variable label
attr(ca_api_2000$api00, "label")

# Inspect value labels for school type
attr(ca_api_2000$stype, "labels")

Description

Groups variables by their shared question_preface metadata and classifies each group as one of "single", "sata", or "battery". This is the single source of truth used by downstream export functions to decide how to render each question.

Usage

classify_question_type(x, ..., variable = NULL)

Arguments

Details

The classification rules, applied per requested variable:

1. If the variable has no question_preface, or is the only requested variable sharing its preface, type = "single".

2. If a question_preface is shared by 2+ requested variables and at least one is flagged via set_sata(), all variables in that group get type = "sata".

3. Otherwise (shared preface, no SATA flag), all variables in the group get type = "battery".

Group numbers are assigned sequentially by first appearance in the input.

Value

A tibble with columns:

• variable (character) — variable name

• question_preface (character) — the preface, or NA if none

• type (character) — one of "single", "sata", or "battery"

• group (integer) — group id; variables with the same non-NA preface share a group

See Also

set_sata(), extract_sata(), set_question_preface()

Other metadata: extract_higher_is(), extract_metadata(), extract_missing_codes(), extract_question_preface(), extract_reverse_coded(), extract_sata(), extract_universe(), extract_val_labels(), extract_var_label(), extract_var_note(), infer_question_prefaces(), set_higher_is(), set_missing_codes(), set_question_preface(), set_reverse_coded(), set_sata(), set_universe(), set_val_labels(), set_var_label(), set_var_note(), survey_metadata(), survey_weighting_history()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
d <- set_question_preface(
  d,
  riagendr = "Demographics",
  ridageyr = "Demographics"
)
d <- set_sata(d, riagendr, ridageyr)
classify_question_type(d, riagendr, ridageyr, bpxsy1)

Description

Converts a survey_glm_fit object into a survey_glm_tidy result tibble with one row per model coefficient (plus optional reference rows for factor predictors), design-based standard errors, confidence intervals, and structured metadata.

Usage

clean(
  model,
  conf_level = 0.95,
  include_reference = TRUE,
  n = FALSE,
  statistic = TRUE,
  exponentiate = FALSE,
  interaction_sep = " * ",
  ...
)

Arguments

Value

A survey_glm_tidy object: a tibble with S3 class c("survey_glm_tidy", "survey_result", "tbl_df", "tbl", "data.frame"). Metadata is accessed via meta().

See Also

survey_glm() to fit the model, meta() to access metadata.

Other analysis: get_anova(), get_corr(), get_covariance(), get_diffs(), get_effective_n(), get_freqs(), get_means(), get_pairwise(), get_quantiles(), get_ratios(), get_t_test(), get_totals(), get_variance(), meta()

Examples

d <- as_survey(
  gss_2024,
  ids = vpsu,
  weights = wtssps,
  strata = vstrat,
  nest = TRUE
)
fit <- survey_glm(d, age ~ sex)
clean(fit)
clean(fit, conf_level = 0.99, exponentiate = FALSE)

Description

Returns the direction-of-improvement ("better" or "worse") for one or more variables in a survey design object or data frame. Variables with no direction set return NA_character_.

Usage

extract_higher_is(x, ..., variable = NULL)

Arguments

Value

A named character vector. Unset variables return NA_character_. Returns character(0) (named, zero-length) when all specified variables are missing from x.

See Also

set_higher_is() to set direction attributes

Other metadata: classify_question_type(), extract_metadata(), extract_missing_codes(), extract_question_preface(), extract_reverse_coded(), extract_sata(), extract_universe(), extract_val_labels(), extract_var_label(), extract_var_note(), infer_question_prefaces(), set_higher_is(), set_missing_codes(), set_question_preface(), set_reverse_coded(), set_sata(), set_universe(), set_val_labels(), set_var_label(), set_var_note(), survey_metadata(), survey_weighting_history()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
d <- set_higher_is(d, bpxsy1 = "worse")
extract_higher_is(d, bpxsy1)
extract_higher_is(d)

Description

Returns a summary of all metadata fields for one or more variables in a survey design object or data frame. Useful for auditing metadata state or building codebooks.

Usage

extract_metadata(x, ..., fill = NULL)

Arguments

Value

A named list. Each entry is a named list with keys: variable_label, value_labels, question_preface, note, universe, missing_codes, transformations.

See Also

Other metadata: classify_question_type(), extract_higher_is(), extract_missing_codes(), extract_question_preface(), extract_reverse_coded(), extract_sata(), extract_universe(), extract_val_labels(), extract_var_label(), extract_var_note(), infer_question_prefaces(), set_higher_is(), set_missing_codes(), set_question_preface(), set_reverse_coded(), set_sata(), set_universe(), set_val_labels(), set_var_label(), set_var_note(), survey_metadata(), survey_weighting_history()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
d <- set_universe(d, ridageyr = "All participants 0+")
extract_metadata(d, ridageyr)
extract_metadata(d, fill = "include")

Description

Returns missing value sentinel codes for one or more variables in a survey design object or data frame.

Usage

extract_missing_codes(x, ..., format = "list", fill = NULL)

Arguments

Value

• "list" (default): named list of atomic vectors. Empty: list().

• "data_frame": long-format tibble with columns variable, description (NA if codes vector is unnamed), code (coerced to character). Empty: zero-row tibble.

See Also

set_missing_codes() to set missing value codes

Other metadata: classify_question_type(), extract_higher_is(), extract_metadata(), extract_question_preface(), extract_reverse_coded(), extract_sata(), extract_universe(), extract_val_labels(), extract_var_label(), extract_var_note(), infer_question_prefaces(), set_higher_is(), set_missing_codes(), set_question_preface(), set_reverse_coded(), set_sata(), set_universe(), set_val_labels(), set_var_label(), set_var_note(), survey_metadata(), survey_weighting_history()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
d <- set_missing_codes(d, ridageyr = c("Not applicable" = 999L))
extract_missing_codes(d, ridageyr)
extract_missing_codes(d, ridageyr, format = "data_frame")

Description

Returns question preface text for one or more variables in a survey design object or data frame.

Usage

extract_question_preface(x, ..., format = "named_vector", fill = NULL)

Arguments

Value

• "named_vector" (default): named character vector. Empty: character(0).

• "list": named list of character scalars. Empty: list().

• "data_frame": tibble with columns variable and preface. Empty: zero-row tibble.

See Also

set_question_preface() to set a question preface

Other metadata: classify_question_type(), extract_higher_is(), extract_metadata(), extract_missing_codes(), extract_reverse_coded(), extract_sata(), extract_universe(), extract_val_labels(), extract_var_label(), extract_var_note(), infer_question_prefaces(), set_higher_is(), set_missing_codes(), set_question_preface(), set_reverse_coded(), set_sata(), set_universe(), set_val_labels(), set_var_label(), set_var_note(), survey_metadata(), survey_weighting_history()

Examples

d <- as_survey(
  gss_2024,
  ids = vpsu,
  weights = wtssps,
  strata = vstrat,
  nest = TRUE
)
d <- set_question_preface(d, happy = "Taken all together...")
extract_question_preface(d, happy)

Description

Returns the reverse-coded status for one or more variables in a survey design object or data frame.

Usage

extract_reverse_coded(x, ..., variable = NULL)

Arguments

Value

A named logical vector. Variables not marked as reverse-coded return FALSE. When all specified variables are missing, returns logical(0).

See Also

set_reverse_coded() to set reverse-coded flags

Other metadata: classify_question_type(), extract_higher_is(), extract_metadata(), extract_missing_codes(), extract_question_preface(), extract_sata(), extract_universe(), extract_val_labels(), extract_var_label(), extract_var_note(), infer_question_prefaces(), set_higher_is(), set_missing_codes(), set_question_preface(), set_reverse_coded(), set_sata(), set_universe(), set_val_labels(), set_var_label(), set_var_note(), survey_metadata(), survey_weighting_history()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
d <- set_reverse_coded(d, bpxsy1)
extract_reverse_coded(d, bpxsy1)
extract_reverse_coded(d)

Description

Returns the SATA status for one or more variables in a survey design object or a data frame.

Usage

extract_sata(x, ..., format = "named_vector", fill = FALSE)

Arguments

Value

• "named_vector" (default): named logical vector. Empty: logical(0).

• "list": named list of logical scalars. Empty: list().

• "data_frame": tibble with columns variable (character) and sata (logical). Empty: zero-row tibble.

See Also

set_sata() to set SATA flags

Other metadata: classify_question_type(), extract_higher_is(), extract_metadata(), extract_missing_codes(), extract_question_preface(), extract_reverse_coded(), extract_universe(), extract_val_labels(), extract_var_label(), extract_var_note(), infer_question_prefaces(), set_higher_is(), set_missing_codes(), set_question_preface(), set_reverse_coded(), set_sata(), set_universe(), set_val_labels(), set_var_label(), set_var_note(), survey_metadata(), survey_weighting_history()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
d <- set_sata(d, riagendr)
extract_sata(d, riagendr)
extract_sata(d, fill = NULL)

Description

Returns universe (eligibility) descriptions for one or more variables in a survey design object or data frame.

Usage

extract_universe(x, ..., format = "named_vector", fill = NULL)

Arguments

Value

• "named_vector" (default): named character vector. Empty: character(0).

• "list": named list of character scalars. Empty: list().

• "data_frame": tibble with columns variable and universe. Empty: zero-row tibble.

See Also

set_universe() to set a universe description

Other metadata: classify_question_type(), extract_higher_is(), extract_metadata(), extract_missing_codes(), extract_question_preface(), extract_reverse_coded(), extract_sata(), extract_val_labels(), extract_var_label(), extract_var_note(), infer_question_prefaces(), set_higher_is(), set_missing_codes(), set_question_preface(), set_reverse_coded(), set_sata(), set_universe(), set_val_labels(), set_var_label(), set_var_note(), survey_metadata(), survey_weighting_history()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
d <- set_universe(d, ridageyr = "All participants 0+")
extract_universe(d)
extract_universe(d, ridageyr, format = "data_frame")

Description

Returns value labels for one or more variables in a survey design object or data frame.

Usage

extract_val_labels(x, ..., format = "list", fill = NULL)

Arguments

Value

• "list" (default): named list of named vectors. Empty: list().

• "data_frame": long-format tibble with columns variable, label, value (codes coerced to character). Empty: zero-row tibble.

See Also

set_val_labels() to set value labels

Other metadata: classify_question_type(), extract_higher_is(), extract_metadata(), extract_missing_codes(), extract_question_preface(), extract_reverse_coded(), extract_sata(), extract_universe(), extract_var_label(), extract_var_note(), infer_question_prefaces(), set_higher_is(), set_missing_codes(), set_question_preface(), set_reverse_coded(), set_sata(), set_universe(), set_val_labels(), set_var_label(), set_var_note(), survey_metadata(), survey_weighting_history()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
extract_val_labels(d, riagendr)
extract_val_labels(d, riagendr, format = "data_frame")

Description

Returns variable labels for one or more variables in a survey design object or data frame.

Usage

extract_var_label(x, ..., format = "named_vector", fill = NULL)

Arguments

Value

• "named_vector" (default): named character vector. Empty: character(0).

• "list": named list of character scalars. Empty: list().

• "data_frame": tibble with columns variable and label. Empty: zero-row tibble.

See Also

set_var_label() to set a variable label

Other metadata: classify_question_type(), extract_higher_is(), extract_metadata(), extract_missing_codes(), extract_question_preface(), extract_reverse_coded(), extract_sata(), extract_universe(), extract_val_labels(), extract_var_note(), infer_question_prefaces(), set_higher_is(), set_missing_codes(), set_question_preface(), set_reverse_coded(), set_sata(), set_universe(), set_val_labels(), set_var_label(), set_var_note(), survey_metadata(), survey_weighting_history()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
extract_var_label(d)
extract_var_label(d, riagendr, ridageyr)
extract_var_label(d, format = "data_frame")
extract_var_label(d, fill = NA_character_)

Description

Returns analyst notes for one or more variables in a survey design object or data frame.

Usage

extract_var_note(x, ..., format = "named_vector", fill = NULL)

Arguments

Value

• "named_vector" (default): named character vector. Empty: character(0).

• "list": named list of character scalars. Empty: list().

• "data_frame": tibble with columns variable and note. Empty: zero-row tibble.

See Also

set_var_note() to set a note

Other metadata: classify_question_type(), extract_higher_is(), extract_metadata(), extract_missing_codes(), extract_question_preface(), extract_reverse_coded(), extract_sata(), extract_universe(), extract_val_labels(), extract_var_label(), infer_question_prefaces(), set_higher_is(), set_missing_codes(), set_question_preface(), set_reverse_coded(), set_sata(), set_universe(), set_val_labels(), set_var_label(), set_var_note(), survey_metadata(), survey_weighting_history()

Examples

d <- as_survey(
  gss_2024,
  ids = vpsu,
  weights = wtssps,
  strata = vstrat,
  nest = TRUE
)
d <- set_var_note(d, age = "Top-coded at 89")
extract_var_note(d, age)

Description

Converts a survey package design object (svydesign, svrepdesign, or twophase) to the corresponding surveycore S7 object. The data, design variables, and replicate weights are preserved; metadata (variable labels, value labels) is not — the survey package has no metadata system.

Usage

from_svydesign(x)

Arguments

Details

Weight column names are recovered from the design call when available. When the call does not contain a formula (e.g., weights were passed as a vector), the weight column is identified by matching the stored weight values against columns in the data. If no match is found, a ..surveycore_wt.. column is added.

Value

A survey_taylor, survey_replicate, or survey_twophase object.

See Also

as_svydesign() to convert in the other direction

Other conversion: as_svydesign(), as_tbl_svy(), from_tbl_svy()

Examples

if (requireNamespace("survey", quietly = TRUE)) {
  sv <- survey::svydesign(
    ids = ~sdmvpsu,
    weights = ~wtint2yr,
    strata = ~sdmvstra,
    data = nhanes_2017,
    nest = TRUE
  )
  d <- from_svydesign(sv)
  survey_data(d)
}

Description

Converts an srvyr tbl_svy to a surveycore design object by delegating to from_svydesign(). A tbl_svy IS a survey.design, so the conversion is structurally identical. Requires both survey and srvyr.

Usage

from_tbl_svy(x)

Arguments

Value

A survey_taylor, survey_replicate, or survey_twophase object.

See Also

as_tbl_svy() to convert in the other direction

Other conversion: as_svydesign(), as_tbl_svy(), from_svydesign()

Examples

if (
  requireNamespace("survey", quietly = TRUE) &&
    requireNamespace("srvyr", quietly = TRUE)
) {
  ts <- srvyr::as_survey(
    survey::svydesign(
      ids = ~sdmvpsu,
      weights = ~wtint2yr,
      strata = ~sdmvstra,
      data = nhanes_2017,
      nest = TRUE
    )
  )
  d <- from_tbl_svy(ts)
}

Description

Rao-Scott design-based ANOVA and design-based Wald tests for survey_glm() fits. Accepts three input shapes on object:

Usage

get_anova(
  object,
  formula = NULL,
  response = NULL,
  predictors = NULL,
  ...,
  method = c("LRT", "Wald"),
  test = c("F", "Chisq"),
  null = NULL,
  tolerance = sqrt(.Machine$double.eps),
  decimals = NULL,
  label_vars = TRUE,
  name_style = "surveycore"
)

Arguments

Details

• A single survey_glm_fit — sequential mode, one row per term.

• A list of survey_glm_fit objects — chained pairwise comparison, producing length(object) - 1 rows.

• A survey design (any survey_base subclass) — fits the model internally via survey_glm() using formula (or response + predictors), then runs sequential anova on the fit.

Supports the four method x test combinations shared with survey::anova.svyglm(): Rao-Scott working-LRT with F or Chisq reference, and design-based Wald with F or Chisq reference.

Value

A survey_anova tibble with columns term, statistic, df, ddf, deff, p_value, stars and a .meta attribute. When name_style = "broom", p_value is renamed to p.value and ddf is renamed to df.residual.

See Also

Other analysis: clean(), get_corr(), get_covariance(), get_diffs(), get_effective_n(), get_freqs(), get_means(), get_pairwise(), get_quantiles(), get_ratios(), get_t_test(), get_totals(), get_variance(), meta()

Examples

gss_cc <- gss_2024[stats::complete.cases(gss_2024[, c("age", "sex", "educ")]), ]
gss_design <- as_survey(
  gss_cc,
  ids = vpsu,
  weights = wtssps,
  strata = vstrat,
  nest = TRUE
)

# Single fit
fit <- survey_glm(gss_design, age ~ sex + educ)
get_anova(fit)

# Design + formula (fits internally)
get_anova(gss_design, age ~ sex + educ)

# List of fits (chained pairwise comparison)
fit_s <- survey_glm(gss_design, age ~ sex)
fit_b <- survey_glm(gss_design, age ~ sex + educ)
get_anova(list(fit_s, fit_b))

Description

Compute pairwise correlations between two or more variables in a survey design, with design-based standard errors and confidence intervals. Returns results in long or wide format. The estimator is selected by method: "pearson" (default) for two numeric variables, "polychoric" for two ordinal variables under a bivariate-normal latent model (Olsson 1979), or "polyserial" for one ordinal + one continuous variable (Cox 1974). The survey-weighted polychoric and polyserial estimators (point estimates and design-based variance) are implemented from scratch following Mannan (2025); they are not derived from the survey package, which does not provide these estimators.

Usage

get_corr(
  design,
  x,
  group = NULL,
  format = c("long", "wide"),
  redundant = FALSE,
  diagonal = FALSE,
  variance = "ci",
  conf_level = 0.95,
  n_weighted = FALSE,
  decimals = NULL,
  min_cell_n = 30L,
  na.rm = TRUE,
  label_values = TRUE,
  label_vars = TRUE,
  name_style = "surveycore",
  method = "pearson",
  ...,
  .id = NULL,
  .if_missing_var = NULL
)

Arguments

Details

Polychoric / polyserial semantics. For method != "pearson", each pair is fit by a two-step MLE: weighted marginal thresholds (and, for polyserial, a weighted standardization of the continuous side) are estimated first, then rho is maximised over the weighted log-likelihood via stats::optimize() on ⁠(-1 + 1e-6, 1 - 1e-6)⁠. Confidence intervals are constructed on the Fisher-z scale (atanh(rho)) and back-transformed via tanh with truncation to ⁠[-1, 1]⁠. The Wald statistic zeta.hat / SE(zeta.hat) is referred to a standard normal distribution, so df = NA_integer_ — distinct from the Pearson case where df = n - 2 and the t-distribution is used. Column label attributes are method-neutral (e.g. "statistic", not "t-statistic" / "z-statistic"); check meta(result)$method to interpret the values.

Bivariate-normal assumption. The polychoric / polyserial MLEs assume the underlying latent variables are jointly bivariate-normal. This is an unverified assumption; no runtime diagnostic is performed.

Taylor-path cost. On a survey_taylor design, the variance path for method != "pearson" is O(n) re-optimisations per variable pair (a perturbation-based influence function). For large n and many pairs, passing a survey_replicate design (one re-fit per replicate, not per respondent) is substantially faster.

Replicate-type caveat. Mannan (2025) verifies the replicate-weight variance formula for jackknife and bootstrap replicates. BRR and Fay replicates are admitted mechanically via the design's stored scale / rscales coefficients, but the paper does not validate their behaviour for this non-linear pseudo-likelihood estimator.

Value

A survey_corr tibble (also inheriting survey_result).

When group is active, group variable columns are prepended before all other columns in both long and wide formats.

Long format columns:

• ⁠[group_cols...]⁠ — group variable columns (when active), first.

• var1, var2 — variable names (or labels when label_vars = TRUE).

• r — correlation coefficient. For method = "pearson", the weighted product-moment correlation; for "polychoric" / "polyserial", the MLE of rho under a bivariate-normal latent model.

• Variance columns (se, var, cv, ci_low, ci_high, moe, deff) — only those requested via variance.

• p_value — two-tailed p-value.

• statistic — test statistic. A t-statistic for method = "pearson"; a Wald z-statistic for latent methods.

• df — degrees of freedom. n - 2 for method = "pearson"; NA_integer_ for "polychoric" and "polyserial" (asymptotic normal distribution is used).

• n — pairwise unweighted count.

• n_weighted — pairwise sum of weights (only when requested).

Wide format columns:

• ⁠[group_cols...]⁠ — group variable columns (when active), first.

• variable — row variable names (or labels).

• One column per focal variable, containing r values.

Use meta(result) to access design type, variable labels, and method ("pearson", "polychoric", or "polyserial"). For method != "pearson", meta(result)$bivariate_normal_cdf is "pbivnorm" (the bivariate-normal CDF used internally). When the replicate variance path observed one or more non-converged replicates, meta(result)$n_failed_replicates_total carries the scalar total.

References

Cox, N. R. (1974). Estimation of the correlation between a continuous and a discrete variable. Biometrics, 30(1), 171-178.

Mannan, H. (2025). SAS programs for estimation of weighted polychoric and weighted polyserial correlations in a complex survey. SSRN. doi:10.2139/ssrn.6580480

Olsson, U. (1979). Maximum likelihood estimation of the polychoric correlation coefficient. Psychometrika, 44(4), 443-460.

See Also

Other analysis: clean(), get_anova(), get_covariance(), get_diffs(), get_effective_n(), get_freqs(), get_means(), get_pairwise(), get_quantiles(), get_ratios(), get_t_test(), get_totals(), get_variance(), meta()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
get_corr(d, x = c(ridageyr, bpxsy1))

# Wide correlation matrix
get_corr(d, x = c(ridageyr, bpxsy1), format = "wide")

# AAPOR-compliant
get_corr(
  d,
  x = c(ridageyr, bpxsy1),
  variance = c("ci", "moe"),
  n_weighted = TRUE
)

# Polychoric correlation between two ordinal variables
df <- data.frame(
  id = 1:200,
  wt = runif(200, 0.5, 2),
  o1 = factor(sample(1:4, 200, replace = TRUE), ordered = TRUE),
  o2 = factor(sample(1:4, 200, replace = TRUE), ordered = TRUE)
)
d_ord <- as_survey(df, weights = wt)
get_corr(d_ord, x = c(o1, o2), method = "polychoric")

Description

Compute the design-based estimate of the finite-population Pearson covariance for every (unordered, by default) pair of numeric variables selected from x, with optional grouping, uncertainty quantification, and metadata-driven labelling. Matches the off-diagonal entries of survey::svyvar() (Kish n/(n-1) correction) on Taylor, replicate, twophase, and nonprob designs at numerical parity.

Usage

get_covariance(
  design,
  x,
  group = NULL,
  redundant = FALSE,
  diagonal = FALSE,
  variance = "ci",
  conf_level = 0.95,
  n_weighted = FALSE,
  decimals = NULL,
  min_cell_n = 30L,
  na.rm = TRUE,
  label_values = TRUE,
  label_vars = TRUE,
  name_style = "surveycore",
  ...,
  .id = NULL,
  .if_missing_var = NULL
)

Arguments

Details

Confidence intervals use the normal-Wald approximation on the SE of the covariance estimate: ci_low = covariance - z * se, ci_high = covariance + z * se, where z = qnorm((1 + conf_level) / 2). The bounds are not clamped. Covariance is unbounded — ci_low and ci_high may have opposite signs and may cross zero. Users who want clamped intervals can post-process. This behaviour matches survey::svyvar().

NA handling is pairwise-complete per pair: each ordered pair drops rows where either variable is NA. There is no na_handling argument; pairwise is the only policy. This matches survey::svyvar() off-diagonal pair-at-a-time semantics, not svyvar()'s default listwise deletion across a multi-variable formula. Numerical parity therefore only holds when oracle calls are made pair-at-a-time (survey::svyvar(~x + y, design) per pair).

Under diagonal = TRUE, the self-pair ⁠(x, x)⁠ returns the design-based Kish-corrected variance of x on the active domain — not 1 as in get_corr(). The covariance matrix diagonal is the variance vector, not the identity. The diagonal-parity gate guarantees that get_covariance(d, c(x, x), diagonal = TRUE)$covariance and ⁠$se⁠ equal get_variance(d, x)$variance and ⁠$se⁠ numerically (point at 1e-10, SE at 1e-8) when the active domains match.

Design effect (deff) uses the Goodnight / Mood-Graybill SRS reference SE_SRS(cov) = sqrt((Var(x) * Var(y) + cov^2) / (n - 1)). When both the design SE and SRS SE are zero (constant-variable pairs), deff is set to exactly 0 (0 / 0 guard).

Value

A survey_covariance tibble (also inheriting survey_result). Columns, in order:

• ⁠[group_cols...]⁠ — group variable columns (when active), first.

• var1, var2 — factor columns identifying the pair (levels in x-supply order).

• covariance — design-based Pearson covariance estimate (Kish-corrected). NaN for degenerate cells; 0 for pairs where at least one variable is constant on the active domain.

• Uncertainty columns (se, var, cv, ci_low, ci_high, moe, deff) — only those requested via variance.

• n — pairwise unweighted count.

• n_weighted — pair's sum of weights (only when requested).

References

Mood, A. M., Graybill, F. A., & Boes, D. C. (1974). Introduction to the Theory of Statistics (3rd ed.). McGraw-Hill.

Lumley, T. (2010). Complex Surveys: A Guide to Analysis Using R. Wiley.

Cochran, W. G. (1977). Sampling Techniques (3rd ed.). Wiley.

Demnati, A., & Rao, J. N. K. (2004). Linearization variance estimators for survey data. Survey Methodology, 30, 17–26.

See Also

Other analysis: clean(), get_anova(), get_corr(), get_diffs(), get_effective_n(), get_freqs(), get_means(), get_pairwise(), get_quantiles(), get_ratios(), get_t_test(), get_totals(), get_variance(), meta()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
get_covariance(d, x = c(ridageyr, bpxsy1))

# Include the diagonal (self-pairs return Var(x), not 1)
get_covariance(d, x = c(ridageyr, bpxsy1), diagonal = TRUE)

# With grouping
get_covariance(d, x = c(ridageyr, bpxsy1), group = riagendr)

Description

Estimates treatment effects (differences from a reference group) via survey-weighted regression. Supports bivariate and multivariate models, Gaussian and non-Gaussian families, and optional subgroup analysis.

Usage

get_diffs(
  design,
  x,
  treats,
  group = NULL,
  covariates = NULL,
  ref_level = NULL,
  pval_adj = NULL,
  show_means = TRUE,
  show_pct_change = FALSE,
  scale = c("ame", "link"),
  variance = "ci",
  conf_level = 0.95,
  alpha = 0.05,
  show_favorability = FALSE,
  min_cell_n = 30L,
  n_weighted = FALSE,
  decimals = NULL,
  na.rm = TRUE,
  label_values = TRUE,
  name_style = "surveycore",
  ...,
  .id = NULL,
  .if_missing_var = NULL
)

Arguments

Details

Estimation Paths

get_diffs() uses two estimation paths:

• Clean path (bivariate Gaussian with no covariates and no group, OR any family with scale = "link"): extracts coefficients directly from clean(). The intercept is the reference group mean; treatment coefficients are differences from reference. When scale = "link" and the family is non-Gaussian, mean and pct_change are suppressed.

• Marginaleffects path (covariates, non-Gaussian with scale = "ame", or group): uses avg_slopes() for estimates and avg_predictions() for means.

Link-Scale Suppression

When scale = "link" and the family is non-Gaussian, the mean and pct_change columns are suppressed (omitted entirely). Link-scale means are not substantively meaningful.

P-Value Adjustment

When group is active, p-value adjustment is applied independently within each group. For global adjustment across all comparisons, apply stats::p.adjust() to the result manually. Confidence intervals reflect the specified conf_level and are not affected by p-value adjustment.

Degrees of Freedom

All p-values and confidence intervals use the t-distribution with design-based residual degrees of freedom, regardless of estimation path.

Non-Gaussian Models

By default, non-Gaussian models report average marginal effects on the response scale. Set scale = "link" for coefficients on the link scale (e.g., log-odds for logistic regression).

Value

A survey_diffs tibble (also inheriting survey_result). Columns (in order): group columns (when active), treatment variable, estimate, pct_change (optional), mean (optional), n, n_weighted (optional), se (optional), ci_low (optional), ci_high (optional), p_value, stars, favorable (optional), backlash (optional). Use meta() to access design type, family, reference level, and other metadata.

See Also

Other analysis: clean(), get_anova(), get_corr(), get_covariance(), get_effective_n(), get_freqs(), get_means(), get_pairwise(), get_quantiles(), get_ratios(), get_t_test(), get_totals(), get_variance(), meta()

Examples

# Create survey design with treatment groups
set.seed(42)
df <- data.frame(
  id = 1:200,
  wt = runif(200, 0.5, 2),
  dv = rnorm(200, 50, 10),
  arm = factor(sample(c("Control", "A", "B"), 200, TRUE))
)
d <- as_survey(df, weights = wt)

# Basic treatment effect
get_diffs(d, dv, arm)

# With percentage change and p-value adjustment
get_diffs(d, dv, arm, show_pct_change = TRUE, pval_adj = "BH")

Description

Computes the effective sample size of a survey design using either the Kish (1965) weight-only approximation (method = "kish") or the full design-effect-based formula for a specified variable (method = "deff").

Usage

get_effective_n(
  design,
  x = NULL,
  group = NULL,
  method = c("kish", "deff"),
  na.rm = TRUE,
  decimals = NULL,
  min_cell_n = 30L,
  ...,
  .id = NULL,
  .if_missing_var = NULL
)

Arguments

Details

The Kish method (method = "kish") computes effective N from survey weights alone: n_eff = sum(w)^2 / sum(w^2). It captures only weight variation. For clustered designs with equal weights, deff_kish = 1.0 even when the true design effect is substantially greater due to clustering. Use method = "deff" to capture the full design effect for a specific analysis variable.

The DEFF method (method = "deff") computes effective N as n_eff = n / DEFF, where DEFF = Var_design / Var_SRS for variable x. It captures clustering, stratification, and weight variation jointly.

Value

A survey_effective_n tibble (also inheriting survey_result). Columns, in order:

• ⁠[.id]⁠ — survey identifier column (when design is a collection).

• ⁠[group_cols...]⁠ — group variable columns (when grouping is active).

• n — integer. Unweighted count of observations.

• n_eff — numeric. Effective sample size.

• deff_kish — numeric. Weight-based design effect (n / n_eff). Present when method = "kish" only.

• deff — numeric. Full design effect (Var_design / Var_SRS). Present when method = "deff" only.

Use meta(result)$method to retrieve the formula used. For DEFF, meta(result)$x is a named list with variable metadata.

See Also

Other analysis: clean(), get_anova(), get_corr(), get_covariance(), get_diffs(), get_freqs(), get_means(), get_pairwise(), get_quantiles(), get_ratios(), get_t_test(), get_totals(), get_variance(), meta()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)

# Kish effective N (weight-only approximation)
get_effective_n(d)

# Full DEFF effective N for a specific variable
get_effective_n(d, ridageyr, method = "deff")

Description

Compute weighted proportions (percentages) for one or more categorical variables in a survey design, with optional grouping, uncertainty quantification, and metadata-driven labelling.

Usage

get_freqs(
  design,
  x,
  ...,
  group = NULL,
  names_to = "name",
  values_to = "value",
  variance = NULL,
  conf_level = 0.95,
  n_weighted = FALSE,
  decimals = NULL,
  min_cell_n = 30L,
  na.rm = TRUE,
  label_values = TRUE,
  label_vars = TRUE,
  name_style = "surveycore",
  .id = NULL,
  .if_missing_var = NULL
)

Arguments

Details

Single-variable mode (when x resolves to exactly one variable): The focal variable name becomes the first column. Rows follow the factor level order (if the variable is a factor) or ascending sort order otherwise.

Multi-variable mode (when x resolves to two or more variables): Results are stacked in long format. The names_to column contains the variable label (when label_vars = TRUE) or the raw variable name as fallback. The values_to column contains the response values.

Domain estimation: Proportions use the ratio linearization approach, equivalent to survey::svymean() on a binary indicator within the active domain. The full design structure is used for variance estimation — rows are not physically removed for domain/group subsets.

na.rm = FALSE: NA is appended as the last level. All proportions (including non-NA levels) have their denominator inflated to include NA rows, so the pct column sums to 1.

Value

A survey_freqs tibble (also inheriting survey_result). Columns:

• ⁠[group_cols...]⁠ — group variable columns (when active), first.

• ⁠[variable_name]⁠ (single) or ⁠[names_to]⁠ + ⁠[values_to]⁠ (multi).

• pct — weighted proportion (0–1).

• Variance columns (se, var, cv, ci_low, ci_high, moe, deff) — only those requested via variance.

• n — unweighted cell count (sample basis of each estimate).

• n_weighted — estimated population count (only when requested).

Use meta(result) to access design type, variable labels, value labels, and other metadata.

See Also

Other analysis: clean(), get_anova(), get_corr(), get_covariance(), get_diffs(), get_effective_n(), get_means(), get_pairwise(), get_quantiles(), get_ratios(), get_t_test(), get_totals(), get_variance(), meta()

Examples

# NHANES exam weights are 0 for non-examined participants; filter first
nhanes_sub <- nhanes_2017[nhanes_2017$wtmec2yr > 0, ]
d <- as_survey(
  nhanes_sub,
  ids = sdmvpsu,
  weights = wtmec2yr,
  strata = sdmvstra,
  nest = TRUE
)

# Single variable
get_freqs(d, riagendr)

# With confidence intervals
get_freqs(d, riagendr, variance = "ci")

# Grouped
get_freqs(d, riagendr, group = sdmvstra)

# Multi-variable (stacked)
get_freqs(d, c(riagendr, ridreth3), names_to = "item", values_to = "value")

Description

Compute the weighted mean of a single numeric variable in a survey design, with optional grouping, uncertainty quantification, and metadata-driven labelling.

Usage

get_means(
  design,
  x,
  group = NULL,
  variance = "ci",
  conf_level = 0.95,
  n_weighted = FALSE,
  decimals = NULL,
  min_cell_n = 30L,
  na.rm = TRUE,
  label_values = TRUE,
  label_vars = TRUE,
  name_style = "surveycore",
  ...,
  .id = NULL,
  .if_missing_var = NULL
)

Arguments

Value

A survey_means tibble (also inheriting survey_result). Columns:

• ⁠[group_cols...]⁠ — group variable columns (when active), first.

• mean — weighted mean estimate.

• Variance columns (se, var, cv, ci_low, ci_high, moe, deff) — only those requested via variance.

• df — degrees of freedom used for CI calculation. Present only for survey_taylor designs with an active ⁠@calibration⁠ object (GREG-corrected SE). For all other designs the normal approximation (Inf) is used and df is not included.

• n — unweighted count of non-NA observations used in the estimate.

• n_weighted — sum of weights (only when requested).

The variable name is stored in meta(result)$x, not as a column. Use meta(result) to access design type, variable labels, and other metadata.

See Also

Other analysis: clean(), get_anova(), get_corr(), get_covariance(), get_diffs(), get_effective_n(), get_freqs(), get_pairwise(), get_quantiles(), get_ratios(), get_t_test(), get_totals(), get_variance(), meta()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
get_means(d, ridageyr)

# With grouped estimate
get_means(d, ridageyr, group = riagendr)

# AAPOR-compliant
get_means(d, ridageyr, variance = c("ci", "moe"), n_weighted = TRUE)

Description

Runs all k(k-1)/2 pairwise two-sample t-tests for a grouping variable with k levels and applies multiple-comparison p-value adjustment. Delegates pair-level computations to get_t_test().

Usage

get_pairwise(
  design,
  x,
  by,
  group = NULL,
  pval_adj = "holm",
  conf_level = 0.95,
  variance = "ci",
  na.rm = TRUE,
  min_cell_n = 30L,
  decimals = NULL,
  label_values = TRUE,
  label_vars = TRUE,
  name_style = "surveycore",
  ...,
  .id = NULL,
  .if_missing_var = NULL
)

Arguments

Value

A survey_pairwise tibble (also inheriting survey_result). Columns: group columns (when active), level_a, level_b, estimate, mean_a, mean_b, n_a, n_b, se (optional), ci_low (optional), ci_high (optional), t_stat, df, p_value (adjusted), stars. Use meta() to access the adjustment method and other metadata.

See Also

Other analysis: clean(), get_anova(), get_corr(), get_covariance(), get_diffs(), get_effective_n(), get_freqs(), get_means(), get_quantiles(), get_ratios(), get_t_test(), get_totals(), get_variance(), meta()

Examples

gss_sub <- gss_2024[gss_2024$sex %in% c(1L, 2L) & !is.na(gss_2024$age), ]
gss_sub$sex <- factor(
  gss_sub$sex,
  levels = c(1, 2),
  labels = c("Male", "Female")
)
gss_design <- as_survey(
  gss_sub,
  ids = vpsu,
  weights = wtssps,
  strata = vstrat,
  nest = TRUE
)
get_pairwise(gss_design, age, by = sex)

Description

Compute survey-weighted quantiles (including the median) for a single numeric variable using the Woodruff (1952) confidence interval method. Supports optional grouping, domain estimation, and all five survey design classes.

Usage

get_quantiles(
  design,
  x,
  probs = c(0.25, 0.5, 0.75),
  group = NULL,
  variance = "ci",
  conf_level = 0.95,
  n_weighted = FALSE,
  decimals = NULL,
  min_cell_n = 30L,
  na.rm = TRUE,
  label_values = TRUE,
  label_vars = TRUE,
  name_style = "surveycore",
  ...,
  .id = NULL,
  .if_missing_var = NULL
)

Arguments

Value

A survey_quantiles tibble (also inheriting survey_result).

• ⁠[group_cols...]⁠ — group variable columns (when active), first.

• quantile — probability label: "p25", "p50", etc.

• estimate — weighted quantile estimate.

• Variance columns (se, var, cv, ci_low, ci_high, moe, deff) — only those requested via variance. CIs are Woodruff intervals and are generally asymmetric around estimate. deff is always NA for quantile estimates: computing it requires a kernel density estimate at the quantile point (the Woodruff SRS approximation used by survey::svyquantile(deff = TRUE)), which is not implemented.

• n — unweighted count of observations in the active domain used in the estimate. When na.rm = TRUE, counts only non-NA observations; when na.rm = FALSE, counts all active-domain rows (including NAs, though the estimate will be NA_real_).

• n_weighted — sum of weights (only when requested).

One row per (group combination × quantile probability). The variable name and probs vector are stored in meta(result).

References

Woodruff, R. S. (1952). Confidence intervals for medians and other position measures. Journal of the American Statistical Association, 47(260), 635–646.

See Also

Other analysis: clean(), get_anova(), get_corr(), get_covariance(), get_diffs(), get_effective_n(), get_freqs(), get_means(), get_pairwise(), get_ratios(), get_t_test(), get_totals(), get_variance(), meta()

Examples

d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)

# IQR + median (default)
get_quantiles(d, ridageyr)

# Median only with SE
get_quantiles(d, ridageyr, probs = 0.5, variance = c("ci", "se"))

# Grouped quartiles
get_quantiles(d, ridageyr, group = riagendr)

Description

Estimate the ratio of two survey-weighted totals (numerator / denominator) for a survey design object. Uses the delta method (linearization) for variance estimation for Taylor, SRS, calibrated, and two-phase designs, and direct per-replicate computation for replicate-weight designs. Both approaches are equivalent to survey::svyratio() for their respective design types. Supports optional grouping, domain estimation, and all five survey design classes.

Usage

get_ratios(
  design,
  numerator,
  denominator,
  group = NULL,
  variance = "ci",
  conf_level = 0.95,
  n_weighted = FALSE,
  decimals = NULL,
  min_cell_n = 30L,
  na.rm = TRUE,
  label_values = TRUE,
  label_vars = TRUE,
  name_style = "surveycore",
  ...,
  .id = NULL,
  .if_missing_var = NULL
)

Arguments