Package {nonprobsampling}

nonprobsampling: Inference for Nonprobability Samples Using Multiple Reference Surveys

Description

nonprobsampling implements pseudo-weighting methods for finite population inference from nonprobability samples, such as convenience samples, volunteer cohorts, and opt-in panels. Because the participation mechanism in a nonprobability sample is unknown, unadjusted estimates of population means and prevalences may be biased. The package addresses this issue by leveraging auxiliary information from one or more probability reference surveys to estimate participation probabilities and using their inverses as pseudo-weights to obtain bias-corrected estimates of finite population means and prevalences.

Details

The package implements the generalized estimating equation framework of Landsman et al. (2026). Pseudo-weights are obtained by solving estimating equations that equate auxiliary variable totals estimated from the nonprobability sample with the corresponding totals estimated from one or more probability reference surveys. Totals from the nonprobability sample are computed using estimated pseudo-weights, whereas totals from the reference surveys are computed using the known survey sampling weights.

Several one reference methods arise as special cases of this framework under different choices of the weight and estimating functions:

• the raking ratio calibration method of Landsman et al. (2026);

• the adjusted logistic propensity (ALP) method of Wang, Valliant, and Li (2021);

• the Chen–Li–Wu (CLW) method of Chen, Li, and Wu (2020).

A key feature of the package is the multi-reference extension of the calibration method. This extension enables the integration of auxiliary information across multiple surveys when no single reference survey contains all variables relevant to participation (Landsman et al., 2026), with an optional cumulative precalibration step to preserve information on the relationships between overlapping and unique auxiliary variables across reference surveys.

Variance estimation is based on Taylor linearization. The resulting analytic variance estimator accounts for uncertainty from pseudo-weight estimation and for the sampling designs of the reference surveys through integration with the survey package. The package also supports bootstrap-based variance estimation when bootstrap weights are provided with the reference surveys.

Typical workflow

Estimation is carried out in two steps:

1. est_pw() estimates pseudo-weights using the nonprobability sample and one or more reference survey design objects. This step fits the participation model and stores the internal quantities needed for subsequent estimation. It does not require an outcome variable.

2. pwmean() uses the object returned by est_pw() to estimate a pseudo-weighted mean or prevalence for an outcome, either overall or by category. It also returns the standard error and confidence interval.

Numerical settings for solving the estimating equations can be specified with pw_solver_control().

Datasets

The package includes example datasets for demonstrating one reference and multiple reference analyses: sc is a nonprobability sample, sp1 and sp2 are probability reference surveys, and sp1_bootstrap contains replicate weights for sp1. See the package vignette for worked examples.

Author(s)

Maintainer: Jiakun Lin jiak.lin@alumni.utoronto.ca

Authors:

• Victoria Landsman

• Aya A. Mitani

References

Chen, Y., Li, P., and Wu, C. (2020). Doubly robust inference with nonprobability survey samples. Journal of the American Statistical Association, 115(532), 2011–2021. doi:10.1080/01621459.2019.1677241

Landsman, V., Wang, L., Carrillo-Garcia, I., Mitani, A. A., Smith, P. M., Graubard, B. I., Bui, T., and Carnide, N. (2026). Correction for participation bias in nonprobability samples using multiple reference surveys. Statistics in Medicine, 45(3–5). doi:10.1002/sim.70403

Wang, L., Valliant, R., and Li, Y. (2021). Adjusted logistic propensity weighting methods for population inference using nonprobability volunteer-based epidemiologic cohorts. Statistics in Medicine, 40(24), 5237–5250. doi:10.1002/sim.9122

See Also

est_pw, pwmean, pw_solver_control

Build pseudo-weights using the ALP method

Description

Build pseudo-weights using the ALP method

Usage

alp_build(
  vars,
  sc,
  sp,
  sp_des,
  wts.col,
  control,
  verbose = FALSE,
  log_messages = NULL
)

Arguments

Value

A list with components:

Estimate step for the ALP estimator

Description

Computes the domain-specific pseudo-weighted Hájek mean and its Taylor-linearized variance for the adjusted logistic propensity estimator.

Usage

alp_estimate(Y, Z, w, X, D, S_beta)

Arguments

Value

A list with components 'mean' and 'variance'.

Assemble the final output object

Description

Combines the pseudo-weighted estimates and naive (unweighted) estimates into a plain list to be returned by 'pwmean()'.

Usage

assemble_output(build, est, naive, na_info)

Arguments

Value

A list with components 'method', 'estimates', and 'na.action'. The S3 class is assigned by the calling function 'pwmean()'.

Build the estimates summary data frame

Description

Constructs the 'estimates' data frame that is stored in a 'pwmean' object. Each row corresponds to one estimate. The 95 computed using the 0.975 normal quantile (approximately 1.96).

Usage

build_domains_df(labels, mean_unw, se_unw, mean_adj, se_adj)

Arguments

Value

A data frame with one row per domain and columns 'domain', 'unweighted_mean', 'unweighted_se', 'unweighted_lower', 'unweighted_upper', 'adjusted_mean', 'adjusted_se', 'adjusted_lower', and 'adjusted_upper'.

Validate the Jacobian and estimating equation vector

Description

Checks that the Jacobian 'J' and estimating equation vector 'g' are numerically valid and that 'J' is square and full rank before a Newton-Raphson step is taken.

Usage

check_estimating_system(J, g, label = "method", tol_singular = 1e-07)

Arguments

Value

'invisible(TRUE)' if all checks pass; otherwise stops with an informative error message.

Validate inputs and build variable sets for multi-reference calibration

Description

Validate inputs and build variable sets for multi-reference calibration

Usage

check_input_multi(sc, sp_list, vars_list, wts_cols, verbose = FALSE)

Arguments

Value

A list with components:

Validate inputs at the estimation stage

Description

Checks that 'build' is a valid 'pw_fit' object with all required internal fields, that 'y' names a numeric or factor column in the raw convenience sample, and that 'zcol' (if supplied) is a supported domain variable with at least two non-missing levels in both the full sample and the build-stage complete cases.

Usage

check_ipwm_inputs_estimate(build, y, zcol = NULL)

Arguments

Value

'invisible(TRUE)' on success; stops with an informative message on failure.

Check the result returned by nleqslv

Description

Inspects the termination code ('termcd') from 'nleqslv::nleqslv()' and either returns silently on success, issues a warning for partial convergence, or stops with an informative error message on failure.

Usage

check_nleqslv_result(root, label, ftol)

Arguments

Value

'invisible(TRUE)' on success or acceptable convergence; otherwise stops or warns.

Build pseudo-weights using the CLW method

Description

Build pseudo-weights using the CLW method

Usage

clw_build(
  vars,
  sc,
  sp,
  sp_des,
  wts.col,
  control,
  verbose = FALSE,
  log_messages = NULL
)

Arguments

Value

A list with components:

Estimate step for the CLW estimator

Description

Computes the domain-specific pseudo-weighted Hájek mean and its Taylor-linearized variance for the CLW estimator.

Usage

clw_estimate(Y, Z, w, X, D, S_beta)

Arguments

Value

A list with components 'mean' and 'variance'.

Compute design-based covariance matrix D for ALP

Description

Internal helper to compute

D = Var_p\left( \sum_{j \in s_p} d_j p_j x_j \right)

from an existing survey design object created by survey::svydesign() or survey::svrepdesign().

Usage

compute_D_ALP(sp_des, p_sp, Xp)

Arguments

Details

In the ALP method, the probability sample contribution in the estimating equation is p_j d_j x_j, so the design-based covariance matrix is obtained by treating h_j = p_j x_j as the survey total variable.

Value

A 'p x p' covariance matrix 'D'.

Compute design-based covariance matrix D for CLW

Description

Internal helper to compute

D = Var_p\left( \sum_{j \in s_p} d_j \pi_j x_j \right)

from an existing survey design object created by survey::svydesign() or survey::svrepdesign().

Usage

compute_D_CLW(sp_des, pi_sp, Xp)

Arguments

Details

In the CLW method, the probability sample contribution in the estimating equation is \pi_j d_j x_j, where 'pi_j' corresponds to the inverse of the estimated pseudo-weight. Thus the design-based covariance matrix is obtained by treating h_j = \pi_j x_j as the survey total variable.

Value

A 'p x p' covariance matrix 'D'.

Compute design-based covariance matrix D for calibration

Description

Internal helper to compute

D = Var_p\left( \sum_{j \in s_p} d_j x_j \right)

from an existing survey design object created by survey::svydesign() or survey::svrepdesign().

Usage

compute_D_raking(sp_des, Xp)

Arguments

Details

In the raking ratio calibration method, the probability sample contribution in the estimating equation is d_j x_j, so the design-based covariance matrix is obtained by treating h_j = x_j as the survey total variable.

Value

A 'p x p' covariance matrix 'D'.

Dispatch the estimator across domains

Description

Determines the domain mode (overall, binary, or factor) from 'yz_data' and calls 'dispatch_estimator_one_domain()' for each domain, returning a unified result list.

Usage

dispatch_estimator(build, yz_data)

Arguments

Value

A list with components:

- 'type': either '"single"' or '"multi"'. - 'labels': character vector of domain labels. - 'estimates': a list of per-domain results, each with 'mean' and 'variance'.

Run the estimator for a single domain

Description

Selects and calls the specific estimator function based on 'build$method', passing the relevant matrices and vectors for one domain at a time.

Usage

dispatch_estimator_one_domain(build, Y, zvec, w, X)

Arguments

Value

A list with components 'mean' and 'variance'.

Estimate Pseudo-Weights for Nonprobability Samples

Description

est_pw() estimates pseudo-weights for a nonprobability sample using one reference survey or multiple reference surveys. The function specifies the participation model, handles missing values in the participation model variables, solves the estimating equations, and stores the quantities needed for downstream point and variance estimation.

Users should harmonize variable names and coding before calling est_pw(). Variables used in the participation model must have consistent names and compatible definitions across the nonprobability sample and the reference survey data used for estimation.

With one reference survey, the available methods include the raking ratio calibration method described in Landsman et al. (2026), the adjusted logistic propensity weighting (ALP) method proposed by Wang, Valliant, and Li (2021), and the CLW method proposed by Chen, Li, and Wu (2020). With multiple reference surveys, pseudo-weights are estimated using the multi-reference calibration method proposed by Landsman et al. (2026).

The returned object is designed to be passed to pwmean.

Usage

est_pw(
  data,
  sp_order = c("size", "given"),
  precali = TRUE,
  p_formula = NULL,
  method = NULL,
  na.action = stats::na.omit,
  sc_wname = "pseudo_wts",
  control = pw_solver_control(),
  verbose = FALSE
)

Arguments

Details

est_pw() performs pseudo-weight estimation for the nonprobability sample and stores the method-specific internal objects needed later by pwmean. It does not require an outcome variable.

The input data must be provided as a list, where the first element is the nonprobability sample and the remaining elements are reference survey design objects. Reference survey designs can be created with svydesign for standard complex survey designs or svrepdesign for surveys with replicate weights. These objects preserve the sampling structure needed for design-consistent variance estimation.

Variable harmonization. Variables are matched by name, not by meaning. Before applying est_pw(), shared variables must be harmonized across the nonprobability sample and reference survey data. For example, if a categorical variable is named agecat in the nonprobability sample and age_group in the reference survey, the user should rename one of the variables before estimation.

Categorical variables should be encoded as factors with compatible category definitions and identical levels in the same order. Even when categories are substantively equivalent, mismatched factor levels may cause est_pw() to return an error. Continuous variables included in the participation model should also be measured on comparable scales across datasets.

Internally, est_pw() performs the following steps:

1. Input validation
   Validates the structure and required components of the input data.

2. Reference survey detection
   Determines whether the input contains a single reference survey or multiple reference surveys.

3. Method selection
   Selects the pseudo-weighting method based on the specified argument(s).

4. Participation model specification
   Constructs a default participation model formula when p_formula = NULL.

5. Missing data handling
   Applies missing-data handling procedures to variables used in the participation model.

6. Model matrix construction
   Generates model matrices from the participation model variables.

7. Pseudo-weight estimation
   Estimates pseudo-weights using the selected method.

8. Output augmentation
   Appends the estimated pseudo-weights as a new column to the nonprobability sample.

9. Metadata storage
   Stores information related to missing-data handling and other internal objects for later use or diagnostics.

Value

An object of class "pw_fit". This is a list containing user-facing outputs and internal objects required by pwmean.

Important components include:

sc_updated

A data frame containing the nonprobability sample with an added pseudo-weight column named by sc_wname.

pseudo_weights

The estimated pseudo-weight vector. With stats::na.omit, the vector contains only observations retained for pseudo-weight estimation. With stats::na.exclude, excluded observations receive NA and the vector has length nrow(sc).

coefficients

Estimated coefficients for the participation model variables.

solver_diagnostics

A list of solver diagnostics: solver (solver name), termcd (termination code), message (solver message), iter (number of iterations), and fmax (maximum absolute value of the final estimating equations at convergence).

method

The pseudo-weighting method used by the function.

internal

A list of internal objects needed for downstream estimation.

na_summary

An object of class "pw_na_summary" summarizing the number of rows excluded from the nonprobability sample and each reference survey due to missing participation model variables. NULL if no rows were excluded.

call

The matched function call.

One-reference method and multi-reference method

If data contains one reference survey design object, est_pw() fits a one-reference method. If data contains more than one reference survey design objects, est_pw() fits the multi-reference calibration method. In both settings, the auxiliary variables used for pseudo-weight estimation should be harmonized across all data sources before calling est_pw().

Multi-reference precalibration

When precali = TRUE, cumulative precalibration is performed before the main multi-reference calibration step. For overlapping auxiliary variables, this procedure calibrates the survey weights of a reference survey so that its weighted totals of the overlapping variables and its sum of weights match the corresponding totals from the preceding reference survey in the cumulative order. If there are no overlapping auxiliary variables, cumulative precalibration is applied only to the sum of weights.

The order of the reference surveys is controlled by sp_order. If sp_order = "size", reference surveys are ordered by sample size, from largest to smallest. If sp_order = "given", the user-specified order of the reference surveys is used.

Cumulative precalibration is based only on overlapping variables that are specified in p_formula, rather than on all overlapping variables in the reference surveys. This choice avoids excluding observations because of missing values in variables that are not used for pseudo-weight estimation.

Missing data handling

Missing values are handled only for variables used in the participation model. The selected na.action is recorded in the returned object, together with the row indices of the nonprobability sample observations retained for pseudo-weight estimation.

With stats::na.omit, rows with missing participation model variables are removed from sc_updated. With stats::na.exclude, the original rows are retained in sc_updated, but excluded rows receive NA in the pseudo-weight column. This can be useful when users want to preserve row alignment with the original nonprobability sample for later imputation or merging.

Numerical control

Numerical settings are supplied through the control argument, which should be created by pw_solver_control. This object controls solver choice, convergence tolerance, maximum iterations, tracing, and optional solver-specific arguments.

The top-level ftol, xtol, and maxit values in pw_solver_control are the package-level convergence controls used by pseudo-weight estimation stages. When the selected solver is "nleqslv", additional arguments can be passed through nleqslv_control. These are forwarded to nleqslv::nleqslv().

References

Chen, Y., Li, P., and Wu, C. (2020). Doubly robust inference with nonprobability survey samples. Journal of the American Statistical Association, 115(532), 2011–2021. doi:10.1080/01621459.2019.1677241

Wang, L., Valliant, R., and Li, Y. (2021). Adjusted logistic propensity weighting methods for population inference using nonprobability volunteer-based epidemiologic cohorts. Statistics in Medicine, 40(24), 5237–5250. doi:10.1002/sim.9122

Landsman, V., Wang, L., Carrillo-Garcia, I., Mitani, A. A., Smith, P. M., Graubard, B. I., Bui, T., and Carnide, N. (2026). Correction for Participation Bias in Nonprobability Samples Using Multiple Reference Surveys. Statistics in Medicine, 45(3–5). doi:10.1002/sim.70403

See Also

pw_solver_control, pwmean

Examples

data(sc)
data(sp1)
data(sp2)

## One-reference example

ref1_design <- survey::svydesign(
  ids     = ~psu_sp1,
  strata  = ~strata_sp1,
  weights = ~wts_sp1,
  data    = sp1,
  nest    = TRUE
)

fit1 <- est_pw(
  data      = list(sc, ref1_design),
  p_formula = ~ agecat + race + education + comorbidity + BMI + diabetes,
  method    = "calibration",
  control   = pw_solver_control(ftol = 1e-6)
)

print(fit1)

summary(fit1)

## Multi-reference example

ref2_design <- survey::svydesign(
  ids     = ~psu_sp2,
  strata  = ~strata_sp2,
  weights = ~wts_sp2,
  data    = sp2,
  nest    = TRUE
)

fit2 <- est_pw(
  data = list(sc, ref1_design, ref2_design),
  p_formula = list(
    ~ agecat + race + education + psa_level + pros_enlarged + comorbidity,
    ~ agecat + race + BMI + diabetes + comorbidity
  ),
  sp_order = "size",
  precali = TRUE,
  control = pw_solver_control(ftol = 1e-6)
)

print(fit2)

summary(fit2)

Extract analysis data from a survey design object

Description

Remove design variables (cluster IDs, strata, FPC, probabilities, weights) from a survey design object and attaches the sampling weights as a single column, returning a plain data frame ready for modeling.

Usage

extract_analysis_data(des, weight_name = "sp_wts")

Arguments

Details

Cluster and strata variables are identified from the design object's own fields ('des$cluster', 'des$strata') rather than the original call, so the result is correct even when 'des' has been subset after construction. Weights, FPC, and probability variables are still read from 'des$call'. For replicate designs ('svyrep.design'), replicate weight columns are also dropped.

Value

A data frame containing the analysis variables from 'des$variables' (design variables removed) plus one column named 'weight_name' storing the sampling weights.

Finalize and assemble the 'pw_fit' return object

Description

Attaches the reconstructed sample data frame, the pseudo-weight vector, and NA-handling metadata to 'result', then assigns the '"pw_fit"' class so that downstream S3 methods can dispatch on it.

Usage

finalize_pw_fit(result, sc_out, sc0, sc_wname, na_mode, keep_sc, na_action_obj)

Arguments

Value

'result' with 'sc_updated', 'pseudo_weights', and 'internal' fields populated, and class set to '"pw_fit"'.

Build pseudo-weights for the multi-reference calibration method

Description

Build pseudo-weights for the multi-reference calibration method

Usage

ipwm_multi_build(
  sc,
  sp,
  vars,
  weight,
  sp_des,
  sp_order,
  control,
  verbose = FALSE,
  log_messages = NULL
)

Arguments

Value

A list with components:

Dispatch one-reference pseudo-weight estimation

Description

Dispatch one-reference pseudo-weight estimation

Usage

ipwm_one_build(
  sc,
  sp,
  sp_des,
  vars = NULL,
  weight,
  method,
  control,
  verbose = FALSE,
  log_messages = NULL
)

Arguments

Value

A list with components:

Construct block-diagonal D matrix for multi-reference raking

Description

Internal helper to assemble the block-diagonal covariance matrix D for the multi-reference raking estimator. Each reference survey contributes one design-based covariance block computed from 'compute_D_raking()'.

Usage

make_block_D_multi(sp_des_list, Xp_list)

Arguments

Value

A block-diagonal covariance matrix D.

Estimate step for multi-reference raking

Description

Computes the domain-specific pseudo-weighted Hájek mean and its Taylor-linearized variance for the multi-reference raking estimator.

Usage

multi_estimate(Y, Z, w, X, D, S_beta)

Arguments

Value

A list with components 'mean' and 'variance'.

Construct block design matrices for multi-reference calibration

Description

Construct block design matrices for multi-reference calibration

Usage

multi_matrix_construction(vars_XC, sc, sp_list, xcol, wts_cols)

Arguments

Value

A list with components:

Map each reference-sample block to its column indices in Xc

Description

Map each reference-sample block to its column indices in Xc

Usage

multi_raking_block_cols(Xc, Xp_list, label = "Multi_Calibration")

Arguments

Value

A list of integer vectors, one per element of 'Xp_list', giving the column positions in 'Xc' that correspond to the columns of each 'Xp_list[[j]]'.

Compute reference weighted totals for multi-reference calibration

Description

Compute reference weighted totals for multi-reference calibration

Usage

multi_raking_fp(Xp_list, wts_list, label = "Multi_Calibration")

Arguments

Value

A named numeric vector of length equal to the total number of columns across all elements of 'Xp_list', containing the survey-weighted column totals \sum_j w_{ij} X_{ij} stacked in block order.

Compute starting values for multi-reference calibration

Description

Compute starting values for multi-reference calibration

Usage

multi_raking_start(Xc, Xp_list, block_cols, f_p, label = "Multi_Calibration")

Arguments

Value

A numeric vector of length 'ncol(Xc)' containing the starting values for the coefficient vector \beta, with the intercept initialized to match the ratio of reference to sample weighted totals and all other coefficients set to zero.

Extract NA action from a pw_fit object

Description

Returns the na.action component recorded during the build step.

Usage

## S3 method for class 'pw_fit'
na.action(object, ...)

Arguments

Value

The na.action object recorded by est_pw during the build step: an integer vector of the nonprobability-sample rows omitted because of missing participation model variables (of class "omit" or "exclude"), or NULL if no rows were omitted.

Extract NA action from a pwmean object

Description

Returns the na.action component recorded during estimation, mimicking na.action behavior for fitted model objects.

Usage

## S3 method for class 'pwmean'
na.action(object, ...)

Arguments

Value

The na.action object recorded by pwmean: an integer vector of rows omitted because of missing outcome or domain values (of class "omit" or "exclude"), or NULL if no rows were omitted.

Compute naive (unweighted) means from the convenience sample

Description

Filters the convenience sample to complete cases, then computes the unweighted sample mean (and its variance) for each domain using 'naive_mean_one_domain()'. The domain structure is standardized via 'standardize_zcol()'.

Usage

naive_mean(df, domain_var = NULL, y)

Arguments

Value

A list with components:

- 'type': '"single"' for overall or binary domains; '"multi"' for factor/character domains. - 'labels': character vector of domain labels. - 'estimates': for 'type = "single"', a list with 'mean' and 'variance'. For 'type = "multi"', a list of such lists, one per domain level.

Compute the naive mean for one domain

Description

Computes the unweighted sample mean and its variance for observations belonging to a single domain, identified by a 0/1 indicator vector.

Usage

naive_mean_one_domain(yvec, zvec = NULL)

Arguments

Value

A list with components:

- 'mean': unweighted sample mean of 'yvec' within the domain, or NA if the domain is empty. - 'variance': estimated variance of the mean (s^2/n), or NA if fewer than two observations are available.

Auto-build a default participation model formula

Description

Constructs a one-sided participation model formula from the variables shared between the nonprobability sample ('sc') and each reference survey, excluding the sampling weight column. Called by 'est_pw()' when 'p_formula = NULL'.

Usage

p_formula_construction(sc, sp, weight)

Arguments

Details

For each reference survey, the candidate covariates are the column names present in both 'sc' and the reference survey data frame after dropping the sampling weight column named by 'weight'. A one-sided formula of the form '~ var1 + var2 + ...' is built from the remaining shared variables. An error is raised if no shared covariates remain after excluding the weight column.

The function distinguishes the one-reference case from the multi-reference case by the type of 'sp': a plain data frame triggers the one-reference path; a list of data frames triggers the multi-reference path. Note that in R a 'data.frame' is also a 'list', so the 'is.data.frame()' check is performed first.

Value

A list with two elements:

'p_formula'

A one-sided formula (one-reference case) or a named list of one-sided formulas (multi-reference case).

'log_messages'

A character vector of messages describing the auto-generated formula(s), used for downstream printing when 'verbose = TRUE'.

Parse the data list passed to est_pw

Description

Splits the input list into its two parts: the nonprobability sample ('sc') and one or more reference survey designs ('sp_des'). For each design it calls 'extract_analysis_data()' to remove design variables and attach a 'sp_wts' column, giving back a plain data frame ready for modeling. If the list elements have no names, or if any element name is an empty string (partially named list), default names '"sp[[1]]"', '"sp[[2]]"', ... are assigned to all elements.

Usage

parse_ipwm_data(data)

Arguments

Value

A list with four elements:

- 'sc': the nonprobability sample (first element of 'data'). - 'sp_des': named list of the survey design objects. - 'sp_vars': named list of plain data frames, one per reference survey, with design variables removed and a 'sp_wts' column added. - 'n_ref': integer giving the number of reference surveys.

Cumulative precalibration across multiple probability samples

Description

Performs a cumulative precalibration across multiple probability samples by sequentially calibrating each sample's weights to align with the marginal totals of the previous samples. Called internally by est_pw().

Usage

precal_cumulative_order(sp_raw, sp_new, weight, sp_order)

Arguments

Value

A list with components sp_new, total_vector, log_messages, and order_used.

Assemble arguments for nleqslv

Description

Extracts and assembles the solver settings from a control object created by 'pw_solver_control()' into the format expected by 'nleqslv::nleqslv()'.

Usage

prepare_nleqslv_args(control)

Arguments

Value

A list with components 'method', 'global', 'xscalm', and 'control' (containing 'ftol', 'xtol', 'maxit', 'trace', and any user-supplied extras from 'nleqslv_control').

Extract and align sc data from a build object

Description

Reads the raw sc sample, the build-stage complete-case index ('keep_sc'), the covariate matrix 'Xc', and the pseudo-weights from 'build'. Remove NA placeholders inserted by 'na.exclude' so that all returned vectors and matrices have the same length (the number of build-stage complete cases).

Usage

prepare_sc_data(build)

Arguments

Value

A list with components:

- 'sc': data frame of build-stage complete cases. - 'X': covariate matrix 'build$internal$Xc'. - 'w': pseudo-weight vector with NA placeholders removed. - 'idx_keep': integer index of which rows of 'raw_sc' were retained.

Print method for pw_fit objects

Description

Compact one-screen overview of a fitted pseudo-weight object: the call, the pseudo-weighting method, the participation model size, solver convergence, and a summary of the estimated pseudo-weights. For the full coefficient table and detailed solver diagnostics, use summary.pw_fit.

Usage

## S3 method for class 'pw_fit'
print(x, ...)

Arguments

Value

Invisibly returns x.

Print method for pw_na_summary

Description

Prints a formatted table showing the original row count, rows used, and rows excluded due to missing participation model variables, for each dataset ('sc' and each reference survey).

Usage

## S3 method for class 'pw_na_summary'
print(x, ...)

Arguments

Value

Invisibly returns 'x'.

Print method for pwmean objects

Description

Displays the pseudo-weighted mean estimate and its uncertainty. For factor-like domain variables, prints one row per domain level.

Usage

## S3 method for class 'pwmean'
print(x, ...)

Arguments

Value

Invisibly returns x.

Print method for pwmean objects with categorical outcomes

Description

Displays pseudo-weighted prevalence estimates and their uncertainty.

Usage

## S3 method for class 'pwmean_factor'
print(x, ...)

Arguments

Value

Invisibly returns x.

Handle missing values at the build stage (first layer)

Description

Process NA for 'est_pw()' before estimation step. Resolves the 'na.action' argument to a standard mode string, applies NA filtering to 'sc' and 'sp', subsets the survey design object(s) in 'sp_des' to match the filtered 'sp', and produces a summary of exclusions.

Usage

process_na_build(sc, sp, sp_des, p_formula, na.action, n_ref, verbose = FALSE)

Arguments

Value

A list with the following elements:

'na_mode'

Character string: one of '"omit"', '"exclude"', '"fail"', or '"pass"'.

'sc'

The cleaned nonprobability sample data frame.

'sp'

The cleaned reference survey data frame(s).

'sp_des'

The subsetted survey design object(s).

'keep_sc'

Logical vector indicating which rows of the original 'sc' are retained.

'keep_sp'

Logical vector (one-reference) or list of logical vectors (multi-reference) indicating which rows of each 'sp' are retained.

'n_sp_orig'

Original row count(s) of 'sp_des' before subsetting.

'na_action_obj'

An lm-style 'na.action' attribute for 'sc', or 'NULL' if no rows were removed.

'log_messages'

Character vector of per-variable NA detail messages from 'handle_na_for_ipwm()', suitable for appending to the running 'log_messages' in 'est_pw()'.

'na_summary'

A 'pw_na_summary' object with row counts before and after NA removal, or 'NULL' if no rows were excluded.

Handle missing values in the outcome and domain variables

Description

Identifies rows with missing values in 'y' (and 'zcol' if supplied), applies the chosen 'na.action' strategy, and returns the complete-case subsets of the outcome vector, covariate matrix, and pseudo-weight vector. Also standardizes the domain variable via 'standardize_zcol()'.

Usage

process_na_yz(sc_data, y, zcol = NULL, na.action = stats::na.omit)

Arguments

Value

A list with components:

- 'Y': numeric outcome vector (complete cases only). - 'X': covariate matrix (complete cases only). - 'w': pseudo-weight vector (complete cases only). - 'sc': data frame (complete cases only). - 'y_name': the value of 'y'. - 'zcol': the value of 'zcol'. - 'domain': list returned by 'standardize_zcol()'. - 'na_info': list with 'na_action', 'n_omitted', 'n_used', 'omitted_raw', and 'kept_raw'.

Control Solver Settings for Pseudo-Weight Estimation

Description

pw_solver_control() creates a solver control object used by est_pw to manage numerical settings for pseudo-weight estimation.

Usage

pw_solver_control(
  solver = "nleqslv",
  maxit = NULL,
  trace = FALSE,
  method = c("Newton", "Broyden"),
  global = c("dbldog", "cline", "pwldog", "qline", "gline", "hook", "none"),
  xscalm = c("fixed", "auto"),
  ftol = 1e-08,
  xtol = 1e-08,
  nleqslv_control = list()
)

Arguments

Details

The control object stores solver settings used by pseudo-weight estimation step. It is passed to est_pw through the control argument.

Currently, only solver = "nleqslv" is supported. The arguments method, global, xscalm, ftol, xtol, and maxit correspond to options used by nleqslv::nleqslv(). They are collected internally and passed to nleqslv::nleqslv() at the pseudo-weight estimation step.

The argument ftol is the function-value convergence tolerance. It controls convergence based on the size of the estimating function. The argument xtol is the parameter-step convergence tolerance. It controls convergence based on changes in the parameter vector. The argument maxit controls the maximum number of solver iterations.

Additional, less commonly used nleqslv control options can be supplied through nleqslv_control. To avoid ambiguity, do not supply ftol, xtol, maxit, or trace inside nleqslv_control; use the main arguments instead.

Value

A flat list containing all solver control settings for pseudo-weight estimation:

solver

The selected numerical solver.

method

The nleqslv numerical method.

global

The nleqslv global strategy.

xscalm

The nleqslv scaling method.

ftol

The function-value convergence tolerance.

xtol

The parameter-step convergence tolerance.

maxit

The maximum number of solver iterations, stored as an integer. 150 if a global strategy is used; 20 if global = "none". Since the default global strategy is "dbldog", the effective default is 150 unless global = "none" is explicitly specified.

trace

Logical value indicating whether tracing information is requested.

nleqslv_control

A list of additional options passed to nleqslv::nleqslv().

See Also

est_pw

Examples

## Default solver control settings
ctrl <- pw_solver_control()

## Custom nleqslv solver settings
ctrl <- pw_solver_control(
  maxit  = 20,
  trace  = FALSE,
  method = "Newton",
  global = "cline",
  xscalm = "auto",
  ftol   = 1e-8,
  xtol   = 1e-10
)

## Additional nleqslv control options
ctrl <- pw_solver_control(
  method = "Newton",
  global = "dbldog",
  nleqslv_control = list(
    btol = 1e-3
  )
)

Estimate Pseudo-Weighted Means, Prevalences, and Standard Errors

Description

Computes pseudo-weighted means and standard errors using a fitted pseudo-weight object of class "pw_fit" returned by est_pw. The function applies second-layer missing-data handling for the outcome and optional domain variable, and then estimates overall or domain-specific means or prevalences using the pseudo-weighting method stored in object.

Usage

pwmean(object, y, zcol = NULL, na.action = stats::na.omit)

Arguments

Details

Missing data handling (layer 2). After pseudo-weights are constructed by est_pw(), estimation of the mean requires complete cases for the outcome y and, if supplied, the domain variable zcol. The argument na.action controls how these missing values are handled at the outcome-estimation step.

Input object. The object argument should be an object of class "pw_fit" returned by est_pw. It stores the estimated pseudo-weights, participation model information, and design-based quantities required for point and variance estimation.

Categorical outcomes. When y is a categorical variable (defined as a factor in R), pwmean() estimates the prevalence (proportion) of each category. To do so, each category is internally converted into a 0/1 indicator variable, and the pseudo-weighted mean estimator is then computed for each indicator.

Value

An object of class "pwmean" containing unweighted and pseudo-weighted estimates, standard errors, and confidence intervals. For categorical outcomes, the estimate columns contain category prevalences.

method

Character. The pseudo-weighting method used.

estimates

A data frame containing the unweighted and pseudo-weighted estimates.

For numeric outcomes, the first column is domain. If zcol = NULL, domain is "Overall". If zcol is a logical variable or a numeric/integer variable containing only 0 and 1, there is one row with domain labeled "<zcol> = 1". If zcol is a factor or character variable, there is one row per zcol level, with domain labeled "<zcol> = <level>".

For categorical outcomes, the first two columns are category and domain. category identifies the outcome level as "<y> = <level>". If zcol = NULL, domain is "Overall" for each outcome level. If zcol is supplied, the rows are formed by each outcome category within each domain, and domain follows the same labels described above for zcol.

The columns are:

category

Category label for categorical outcomes only.

domain

Domain label.

unweighted_mean, unweighted_se

Unweighted mean of y and its standard error.

unweighted_lower, unweighted_upper

Bounds of the 95% confidence interval for the unweighted mean, based on the normal approximation.

adjusted_mean, adjusted_se

Pseudo-weighted mean of y and its standard error.

adjusted_lower, adjusted_upper

Bounds of the 95% confidence interval for the pseudo-weighted mean, based on the normal approximation.

na.action

Integer vector of row indices omitted at the outcome-estimation step, with class "omit" or "exclude" matching the na.action argument, or NULL if no observations were omitted. The indices refer to the nonprobability sample available to pwmean() after missing-data handling in est_pw().

call

The matched function call.

See Also

est_pw, summary.pwmean, print.pwmean

Examples

data(sc)
data(sp1)

ref1_design <- survey::svydesign(
  ids     = ~psu_sp1,
  strata  = ~strata_sp1,
  weights = ~wts_sp1,
  data    = sp1,
  nest    = TRUE
)

fit <- est_pw(
  data      = list(sc, ref1_design),
  p_formula = ~ agecat + race + education + comorbidity + BMI + diabetes,
  method    = "calibration",
  control   = pw_solver_control(ftol=1e-6)
)

out <- pwmean(fit, y = "psa_level", zcol = "BMI")

print(out)

summary(out)

Build pseudo-weights using the calibration (raking) method

Description

Build pseudo-weights using the calibration (raking) method

Usage

raking_build(
  vars,
  sc,
  sp,
  sp_des,
  wts.col,
  control,
  verbose = FALSE,
  log_messages = NULL
)

Arguments

Value

A list with components:

Estimate step for raking-ratio calibration

Description

Computes the domain-specific pseudo-weighted Hájek mean and its Taylor-linearized variance for the raking-ratio calibration estimator.

Usage

raking_estimate(Y, Z, w, X, D, S_beta)

Arguments

Value

A list with components 'mean' and 'variance'.

Reconstruct the sample data frame with fitted pseudo-weights

Description

Inserts the fitted pseudo-weights 'w_fit' back into the original sample data frame 'sc0', using the NA handling strategy used during estimation. For '"omit"', only the rows that were kept are returned. For '"exclude"', all original rows are returned with NA weights for rows that were dropped. For '"fail"' or '"pass"', all rows are assumed to be present and weights are attached directly.

Usage

reconstruct_sc_output(sc0, w_fit, keep_sc, na_mode, na_action_obj, sc_wname)

Arguments

Value

A data frame derived from 'sc0' with a pseudo-weight column named 'sc_wname'.

Nonprobability Sample (sc)

Description

This dataset represents a synthetic nonprobability sample generated via Poisson sampling from a finite population constructed from the National Health and Nutrition Examination Survey (NHANES) cycles 1999–2010. It is intended to illustrate the pseudo-weighting methods implemented in the nonprobsampling package.

Usage

data(sc)

Format

A data frame with 2404 observations and 8 variables:

psa_level

Outcome variable: serum prostate-specific antigen level (numeric)

BMI

Body mass index category (factor with 4 levels: "Normal", "Overweight", "Obese", "Morbidly Obese")

race

Race category (factor with 4 levels: 1 = White, 2 = Black, 3 = Hispanic, 4 = Other)

agecat

Age category (factor with 4 levels: 1 = 55–59, 2 = 60–64, 3 = 65–69, 4 = 70+)

education

Education level (factor with 5 levels: 1 = Less Than 8 Years, 2 = 8–11 Years, 3 = 12 Years Or Completed High School, 4 = College Graduate, 5 = Postgraduate)

pros_enlarged

Prostate enlargement indicator (factor with 2 levels: 0 = No, 1 = Yes)

comorbidity

General comorbidity indicator (factor with 2 levels: 0 = No, 1 = Yes)

diabetes

Diabetes diagnosis indicator (factor with 2 levels: 0 = No, 1 = Yes)

Details

The dataset has 2,404 complete-case observations, with psa_level serving as the outcome variable. Auxiliary variables shared with the probability reference surveys sp1 and sp2 are used to construct pseudo-weights aimed at correcting for participation bias.

Source

Synthetic data generated by the package authors. The underlying finite population was constructed from the National Health and Nutrition Examination Survey (NHANES), 1999–2010 cycles, conducted by the U.S. National Center for Health Statistics (NCHS).

Examples

data(sc)
str(sc)
summary(sc)

Solve the participation model estimating equations

Description

A unified wrapper that calls 'nleqslv::nleqslv()' to solve the system of estimating equations g(\beta) = 0, then validates the result via 'check_nleqslv_result()'.

Usage

solve_participation_model(beta_start, fn, jac, label, control = NULL, ...)

Arguments

Value

A list with components 'coefficients', 'iterations', 'solver', 'solver_result', 'solver_method', 'fvec', 'termcd', and 'message'.

Sort reference samples by size

Description

Sort reference samples by size

Usage

sort_by_sp_size(sp, vars, weight, design, sp_order, verbose = FALSE)

Arguments

Value

A list with components:

Probability Reference Sample 1 (sp1)

Description

This dataset represents a probability sample derived from the 1999–2010 cycles of the National Health and Nutrition Examination Survey (NHANES). It is used as a probability reference survey to support the pseudo-weighting methods implemented in the nonprobsampling package.

Usage

data(sp1)

Format

A data frame with 3494 observations and 14 variables:

agecat

Age category (factor with 4 levels: 1 = 55–59, 2 = 60–64, 3 = 65–69, 4 = 70+)

marital

Marital status (factor with 4 levels: 1 = Married Or Living As Married, 2 = Widowed, 3 = Divorced or Separated, 4 = Never Married)

race

Race category (factor with 4 levels: 1 = White, 2 = Black, 3 = Hispanic, 4 = Other)

education

Education level (factor with 5 levels: 1 = Less Than 8 Years, 2 = 8–11 Years, 3 = 12 Years Or Completed High School, 4 = College Graduate, 5 = Postgraduate)

employment

Employment status (factor with 2 levels: 0 = Not Working, 1 = Working)

smoking

Smoking status (factor with 3 levels: 1 = Never Smoker, 2 = Former Smoker, 3 = Current Smoker)

comorbidity

General comorbidity indicator (factor with 2 levels: 0 = No, 1 = Yes)

psa_level

Serum prostate-specific antigen level (numeric)

BMI

Body mass index category (factor with 4 levels: "Normal", "Overweight", "Obese", "Morbidly Obese")

diabetes

Diabetes diagnosis indicator (factor with 2 levels: 0 = No, 1 = Yes)

pros_enlarged

Prostate enlargement indicator (factor with 2 levels: 0 = No, 1 = Yes)

strata_sp1

Stratum identifier for complex survey design (numeric)

psu_sp1

Primary sampling unit identifier for complex survey design (numeric)

wts_sp1

10-year interview sampling weights (numeric)

Details

The dataset includes auxiliary variables shared with the nonprobability sample sc, enabling the construction of pseudo-weights to adjust for participation bias. Survey design variables and sampling weights are provided to support design-consistent estimation.

The sp1 dataset contains the outcome variable psa_level, which is also observed in sc, allowing for the evaluation of pseudo-weighted estimators against estimates based on true sampling weights. It may also be incorporated into the participation model, potentially enhancing bias reduction when participation depends on the outcome.

Source

Derived from the National Health and Nutrition Examination Survey (NHANES), 1999–2010 cycles, conducted by the U.S. National Center for Health Statistics (NCHS).

Examples

data(sp1)
str(sp1)
summary(sp1)

Probability Reference Sample 1 with Bootstrap Replicate Weights (sp1_bootstrap)

Description

A replicate-weight version of sp1, including the main survey weight and 500 bootstrap replicate weights. It is provided to illustrate design-based variance estimation with svrepdesign. The original primary sampling unit and stratum identifiers are not included.

Usage

data(sp1_bootstrap)

Format

A data frame with 3494 rows and 512 columns. The first 12 columns are the substantive survey variables from sp1 (agecat, marital, race, education, employment, smoking, comorbidity, psa_level, BMI, diabetes, pros_enlarged, wts_sp1). The remaining 500 columns are bootstrap replicate weights named bw1 through bw500 (numeric).

Details

The bootstrap replicate weights were constructed from the original stratified cluster design of sp1, using the Rao-Wu rescaling bootstrap method. A total of R = 500 replicates were produced with seed = 2026.

The variables psu_sp1 and strata_sp1 are not included in this dataset because they are not needed when using replicate weights for variance estimation. The main survey weight wts_sp1 and the replicate weight columns bw1–bw500 are sufficient for constructing a replicate-weight survey design object via survey::svrepdesign().

Source

Derived from sp1 (National Health and Nutrition Examination Survey, NHANES, 1999–2010 cycles), with bootstrap replicate weights added by the package authors using the Rao-Wu rescaling bootstrap.

Examples

data(sp1_bootstrap)

# Example: create replicate-weight survey design object
des_boot <- survey::svrepdesign(
  data    = sp1_bootstrap,
  weights = ~wts_sp1,
  repweights = "bw[0-9]+",
  type    = "bootstrap",
  combined.weights = FALSE
)

summary(des_boot)

Probability Reference Sample 2 (sp2)

Description

This dataset represents a probability survey derived from the 1997–2008 cycles of the National Health Interview Survey (NHIS). It is intended for use alongside sc and sp1 to illustrate the multi-reference calibration method implemented in the nonprobsampling package.

Usage

data(sp2)

Format

A data frame with 35525 observations and 11 variables:

agecat

Age category (factor with 4 levels: 1 = 55–59, 2 = 60–64, 3 = 65–69, 4 = 70+)

marital

Marital status (factor with 4 levels: 1 = Married Or Living As Married, 2 = Widowed, 3 = Divorced or Separated, 4 = Never Married)

race

Race category (factor with 4 levels: 1 = White, 2 = Black, 3 = Hispanic, 4 = Other)

employment

Employment status (factor with 2 levels: 0 = Not Working, 1 = Working)

diabetes

Diabetes diagnosis indicator (factor with 2 levels: 0 = No, 1 = Yes)

BMI

Body mass index category (factor with 4 levels: "Normal", "Overweight", "Obese", "Morbidly Obese")

smoking

Smoking status (factor with 3 levels: 1 = Never Smoker, 2 = Former Smoker, 3 = Current Smoker)

comorbidity

General comorbidity indicator (factor with 2 levels: 0 = No, 1 = Yes)

wts_sp2

Sampling weights (numeric)

strata_sp2

Stratum identifier for complex survey design (numeric)

psu_sp2

Primary sampling unit identifier for complex survey design (numeric)

Details

The dataset includes auxiliary variables shared with the nonprobability sample sc, enabling the construction of pseudo-weights to adjust for participation bias. Survey design variables and sampling weights are provided to support design-consistent estimation.

Source

Derived from the National Health Interview Survey (NHIS), 1997–2008 cycles, conducted by the U.S. National Center for Health Statistics (NCHS).

Examples

data(sp2)
str(sp2)
summary(sp2)

Standardize a domain variable into a common internal format

Description

Converts 'zcol' in 'data' to a standard form used throughout the estimation pipeline. Logical and binary numeric (0/1) variables become a single integer indicator column; character variables are trimmed and coerced to a factor; factor variables are dropped of unused levels and expanded to one integer indicator column per level. The returned list always has the same structure so downstream code can branch on 'mode' alone.

Usage

standardize_zcol(data, zcol = NULL)

Arguments

Value

A list with components:

- 'mode': one of '"overall"', '"binary"', or '"factor"'. - 'z_name': the value of 'zcol', or NULL when 'zcol' is NULL. - 'labels': character vector of domain labels shown to the user. - 'indicators': data frame of integer 0/1 indicator columns (one column per domain level), or NULL in the overall case.

Summarize a Pseudo-Weight Fit

Description

Summarize a Pseudo-Weight Fit

Usage

## S3 method for class 'pw_fit'
summary(object, ...)

Arguments

Value

Invisibly returns object.

Summary method for pwmean objects

Description

Provides console output for objects of class "pwmean", including unweighted and pseudo-weighted mean estimates, standard errors, confidence intervals, and optional domain-level summaries.

Usage

## S3 method for class 'pwmean'
summary(object, ...)

Arguments

Value

Invisibly returns object.

Summary method for pwmean objects with categorical outcomes

Description

Provides console output for objects of class "pwmean_factor", including unweighted and pseudo-weighted prevalence estimates, standard errors, and confidence intervals.

Usage

## S3 method for class 'pwmean_factor'
summary(object, ...)

Arguments

Value

Invisibly returns object.