replicate_weights: Replicate weights methods

View source: R/replicate.weights.R

replicate_weightsR Documentation

Replicate weights methods

Description

A function calculating replicate weights.

Usage

replicate_weights(
  data,
  method = c("JKn", "dCV", "bootstrap", "subbootstrap", "BRR", "split", "extrapolation"),
  cluster = NULL,
  strata = NULL,
  weights = NULL,
  design = NULL,
  k = 10,
  R = 1,
  B = 200,
  train.prob = 0.7,
  method.split = c("dCV", "bootstrap", "subbootstrap"),
  rw.test = FALSE,
  dCV.sw.test = FALSE
)

Arguments

data

A data frame with information on (at least) cluster and strata indicators, and sampling weights. It could be NULL if the sampling design were indicated in the design argument (see design).

method

A string of a name of replicate weights methods. Choose one of these: JKn, dCV, bootstrap, subbootstrap, BRR, split, extrapolation.

cluster

A string of a cluster identifier. It could be NULL if the sampling design were plugged in the design argument.

strata

A string of a strata identifier. It could be NULL if the sampling design were plugged in the design argument.

weights

A string of a sampling weights' identifier. It could be NULL if the sampling design were included in the design argument.

design

An object of class survey.design generated by svydesign. It could be NULL if information about cluster, strata, weights and data were given.

k

An integer. The number of folds to be defined. Default is k=10. Only applies to the dCV method.

R

An integer. The number of times the sample is partitioned. Default is R=1. Only applies to dCV, split or extrapolation methods.

B

An integer. The number of bootstrap re-samples. Default is B=200. Only applies to bootstrap and subbootstrap methods.

train.prob

A numeric between 0 and 1 that sets the proportion of clusters (for the method split) or strata (for the method extrapolation) in training sets. Default is train.prob=0.7. Only applies to split and extrapolation methods.

method.split

A string of one the following replicate weights methods to be implemented under the split method in the method argument: dCV, bootstrap or subbootstrap.

rw.test

A logical value. If TRUE, the function returns in the output object the replicate weights to the corresponding test sets. If FALSE, only the replicate weights of the training sets are returned. Default is rw.test = FALSE.

dCV.sw.test

A logical value. If TRUE, original sampling weights for the units in the test sets are returned instead of the replicate weights. Default is dCV.sw.test = FALSE. Only applies to dCV method.

Details

This function from R-wlasso (https://github.com/aiparragirre/wlasso/, recently registered in CRAN: svyVarSel) is slightly modified for our package development. The following description is also obtained from the original source for convenience.

Some of replicate weights methods, such as JKn, bootstrap, subbootstrap and BRR, are implemented in R-survey, as.svrepdesign, from which the replicate_weights() function generates replicate weights for these options; dCV, split and extrapolation have been expressly defined in this function.

Selecting any of the above-mentioned methods returns a new data frame, in which new columns are added to the original data set; each column by replicate weights always creates different pairs of training sets and optionally the corresponding test sets by setting rw.test=TRUE. The number of new columns and their corresponding names are usually determined by numeric arguments, i.e.,k, or R, etc. and specifically by the selected replicate weights method. The new columns indicating training and test sets follow the similar structure for any selected method: rw_r_x_train_t, where x=1,...,R, and t=1,...,T indicate the x-th partition of the sample,the t-th training set, respectively. Similarly, the new columns for test sets are structured by rw_r_x_test_t or sw_r_x_test_t. For other methods, fold or set for each unit respectively labeled as fold_t or set_t is included in each partition depending on the method in a data set.

For JKn, bootstrap, and subbootstrap, the sw_r_1_test_* test columns (generated when rw.test = TRUE) represent an out-of-bag (OOB) style test set: for each replicate, a unit's original sampling weight is assigned to the test column if and only if that unit's PSU was not drawn into that particular replicate (resample multiplier of exactly 0), and 0 otherwise. For bootstrap/subbootstrap specifically, this means the OOB test fraction per replicate is random and not fixed in advance – in expectation roughly 1/e \approx 37\% of PSUs are held out per replicate for ordinary bootstrap, somewhat more for subbootstrap – rather than a predetermined split proportion as in dCV or split.

Value

The function returns a new data frame with new columns, each of which indicates replicate weights for different subsets.

Examples

data(nhanes2013_sbc)

## JKn ---------------------------------------------------------------------
data_rw <- replicate_weights(data = nhanes2013_sbc,
                             method = "JKn",
                             cluster = "SDMVPSU",
                             strata = "SDMVSTRA",
                             weights = "WTSAF2YR",
                             rw.test = TRUE)

## dCV ---------------------------------------------------------------------
data_rw <- replicate_weights(data = nhanes2013_sbc,
                             method = "dCV",
                             cluster = "SDMVPSU",
                             strata = "SDMVSTRA",
                             weights = "WTSAF2YR",
                             k = 10, R = 20,
                             rw.test = TRUE)

## subbootstrap ------------------------------------------------------------
# rw.test = TRUE now also returns out-of-bag ("sw_r_1_test_*") weights:
# units whose PSU was not drawn into a given replicate (resample multiplier
# == 0) are treated as that replicate's held-out test set.
data_rw <- replicate_weights(data = nhanes2013_sbc,
                             method = "subbootstrap",
                             cluster = "SDMVPSU",
                             strata = "SDMVSTRA",
                             weights = "WTSAF2YR",
                             B = 100,
                             rw.test = TRUE)

## BRR ---------------------------------------------------------------------
data_rw <- replicate_weights(data = nhanes2013_sbc,
                             method = "BRR",
                             cluster = "SDMVPSU",
                             strata = "SDMVSTRA",
                             weights = "WTSAF2YR",
                             rw.test = TRUE)

## split ---------------------------------------------------------------------

data_rw <- replicate_weights(data = nhanes2013_sbc,
                             method = "split",
                             cluster = "SDMVPSU",
                             strata = "SDMVSTRA",
                             weights = "WTSAF2YR",
                             R=20,
                             train.prob = 0.5,
                             method.split = "subbootstrap",
                             rw.test = TRUE)

## extrapolation -------------------------------------------------------------
data_rw <- replicate_weights(data = nhanes2013_sbc,
                            method = "extrapolation",
                            cluster = "SDMVPSU",
                            strata = "SDMVSTRA",
                            weights = "WTSAF2YR",
                            R=20,
                            train.prob = 0.5,
                            rw.test = TRUE)



MLSurvey documentation built on Nov. 18, 2026, 5:11 p.m.