Adjust survey weights for unit nonresponse

Redistributes the weights of nonrespondents to respondents within weighting classes defined by by. All rows (respondents and nonrespondents) are returned; nonrespondent weights are set to 0 and respondent weights are adjusted upward to conserve the total weight within each cell.

Usage

adjust_nonresponse(
  data,
  response_status,
  weights = NULL,
  by = NULL,
  wt_name = "wts",
  method = c("weighting-class", "propensity-cell", "propensity"),
  control = list(min_cell = 20, max_adjust = 2)
)

Arguments

data

A data.frame, weighted_df, survey_taylor, or survey_nonprob. Must include BOTH respondents and nonrespondents. survey_replicate → error. Any other class → error.

response_status

Bare name (NSE). Binary response indicator column. Must be logical or integer 0/1. 1 / TRUE = respondent.

weights

Bare name (NSE). Weight column. NULL → auto-detected from weighted_df attribute or survey object @variables$weights. For plain data.frame with weights = NULL, uniform starting weights are used.

by

<tidy-select> Weighting class variables. Redistribution is performed within each cell defined by the joint combination of these variables. NULL → global redistribution across all rows.

wt_name

Character scalar. Name of the output weight column in the returned weighted_df. Default "wts". Ignored when data is a survey object (survey_taylor or survey_nonprob).

method

Character scalar. Adjustment method. In Phase 0, only "weighting-class" is supported. "propensity" and "propensity-cell" are API-stable stubs that error until Phase 2.

control

Named list of warning thresholds:

• min_cell: warn when a cell has fewer than this many respondents (default 20, per NAEP methodology).

• max_adjust: warn when the nonresponse adjustment factor for a cell exceeds this value (default 2.0, per survey::sparseCells() convention). Either condition alone triggers the warning.

Value

All rows (respondents and nonrespondents) are returned. Nonrespondent weights are set to 0; respondent weights are adjusted upward to conserve the total weight within each cell.

• data.frame or weighted_df input -> weighted_df

• survey_nonprob input -> survey_nonprob (same class)

• survey_taylor input -> survey_taylor (same class; respondent rows only, because survey_taylor does not support zero weights)

A history entry with operation = "nonresponse_weighting_class" is appended to weighting_history.

Details

The adjustment formula within each cell h is:

$$w_{i,new} = w_i \times \frac{\sum w_h}{\sum w_{h,resp}}$$

where \(\sum w_h\) is the sum of all weights (respondents + nonrespondents) in cell h and \(\sum w_{h,resp}\) is the sum of respondent weights only.

Zero-weight observations are retained for design-based variance estimation. Survey estimation functions (e.g., survey::svymean()) handle zero weights correctly – zero-weight units are excluded from point estimates but included in the design structure for variance estimation. For manual calculations, use w[w > 0] to exclude nonrespondents.

Diagnostic functions (effective_sample_size(), weight_variability(), summarize_weights()) automatically filter to positive weights before computing statistics.

Re-calibrating post-nonresponse data requires filtering to respondents first, because calibrate(), rake(), and poststratify() reject zero weights.

Examples

df <- data.frame(
  age_group = c("18-34", "35-54", "55+", "18-34", "35-54"),
  responded = c(1L, 1L, 1L, 0L, 1L),
  stringsAsFactors = FALSE
)
result <- adjust_nonresponse(df, response_status = responded)
#> Warning: ! Weighting class cell "(global)" is sparse (4 respondent(s), adjustment factor
#>   1.25×).
#> ℹ Small or high-adjustment cells may produce extreme weights.
#> ℹ Consider collapsing weighting classes or adjusting `control$min_cell` /
#>   `control$max_adjust`.