pwmean: 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)

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.

Arguments

object: An object of class "pw_fit" returned by est_pw.
y: A character string specifying the name of the outcome variable in the nonprobability sample stored in object. The outcome must be numeric for mean estimation, including binary 0/1 outcomes for prevalence estimation, or a factor for category prevalence estimation.
zcol: Optional character string giving the name of a categorical domain variable in the nonprobability sample stored in the object. If NULL, the overall mean is estimated. If supplied, estimates are computed within domains defined by this variable. The following column types are supported: logical (must contain both TRUE and FALSE); numeric or integer containing only 0 and 1 after removing missing values; character (empty strings are treated as missing values); and factor (unused levels are dropped).
na.action: Function specifying how missing values in y and zcol should be handled. Default is stats::na.omit.

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.

Examples

Run this code

# \donttest{
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)
# }