Estimate Pseudo-Weighted Means, Prevalences, and Standard Errors

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

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.

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.

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

# \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)
#> 
#> Pseudo-weighted (calibration) Estimators:
#>   Domain: BMI = Morbidly Obese
#>   Mean:             1.732436
#>   Std. Error:       0.140720
#>   95% CI:         [1.456629, 2.008243]
#> 
#>   Domain: BMI = Normal
#>   Mean:             1.728680
#>   Std. Error:       0.083032
#>   95% CI:         [1.565940, 1.891420]
#> 
#>   Domain: BMI = Obese
#>   Mean:             1.362181
#>   Std. Error:       0.057429
#>   95% CI:         [1.249623, 1.474740]
#> 
#>   Domain: BMI = Overweight
#>   Mean:             1.491525
#>   Std. Error:       0.049834
#>   95% CI:         [1.393851, 1.589199]

summary(out)
#> Call:
#> pwmean(object = fit, y = "psa_level", zcol = "BMI")
#> 
#> Method: One reference calibration 
#> 
#> Unweighted estimators:
#>                domain     mean         se CI_lower CI_upper
#>  BMI = Morbidly Obese 1.673128 0.12901739 1.420259 1.925998
#>          BMI = Normal 1.692864 0.08216978 1.531814 1.853914
#>           BMI = Obese 1.360960 0.05707777 1.249089 1.472830
#>      BMI = Overweight 1.513487 0.05114169 1.413251 1.613723
#> 
#> Pseudo-weighted (calibration) estimators:
#>                domain     mean         se CI_lower CI_upper
#>  BMI = Morbidly Obese 1.732436 0.14072032 1.456629 2.008243
#>          BMI = Normal 1.728680 0.08303227 1.565940 1.891420
#>           BMI = Obese 1.362181 0.05742881 1.249623 1.474740
#>      BMI = Overweight 1.491525 0.04983443 1.393851 1.589199
# }