Propensity-weighted ESS balance diagnostic

For each covariate in X_balance, computes the unweighted and propensity-weighted ODA ESS association with group, the delta ESS (weighted minus unweighted), and a bootstrap confidence interval on the delta.

Usage

propensity_ess_balance(
  propensity_fit,
  group,
  X_balance,
  x_prop = NULL,
  newdata = NULL,
  target_class = NULL,
  adjusted = TRUE,
  n_boot = 500L,
  boot_alpha = 0.05,
  seed = NULL
)

Arguments

propensity_fit

An oda_fit, cta_tree, or cta_ort (LORT) object trained with group as the class variable.

group

Integer (or coercible) binary group/treatment vector of length n.

X_balance

Data frame of baseline covariates. Must have n rows.

x_prop

Numeric vector of length n. Required when propensity_fit is an oda_fit; assigns each observation to an ODA stratum.

newdata

Data frame with n rows. Required when propensity_fit is a cta_tree or cta_ort; used to assign observations to endpoints/strata. Must contain the columns used to fit the propensity model.

target_class

Integer. Passed to cta_propensity_weights / lort_propensity_weights for models with more than two classes.

adjusted

Logical. If TRUE (default), uses adjusted propensity weights (one-hypothetical-misclassification correction for zero-cell strata).

n_boot

Integer. Number of bootstrap resamples. Default 500L.

boot_alpha

Numeric in (0, 1). CI level is 1 - boot_alpha. Default 0.05 gives a 95% CI.

seed

Integer or NULL. Passed to set.seed() before bootstrap resampling for reproducibility.

Value

A data.frame of class c("propensity_ess_balance", "data.frame") with one row per covariate and columns:

variable

Covariate name.

n

Effective sample size from the unweighted ODA fit.

unweighted_ess

Unweighted ODA ESS (%).

weighted_ess

Propensity-weighted ODA ESS / WESS (%).

delta_ess

weighted_ess - unweighted_ess. Negative values indicate attenuation (improved balance).

boot_low

Lower bound of the bootstrap CI on delta_ess.

boot_high

Upper bound of the bootstrap CI on delta_ess.

crosses_null

Logical. TRUE when the CI includes 0.

status

"ok", "inadmissible_unweighted", "inadmissible_weighted", or "inadmissible_both".

Details

If propensity weighting controls confounding, the weighted ODA ESS should move toward 0 (the chance/null boundary). A negative delta_ess means the ODA association was attenuated by weighting (improved balance). crosses_null = TRUE means the bootstrap CI for the delta includes 0.

LORT (cta_ort) propensity models are not supported in this version. Use a single cta_tree via cta_fit() instead.

The bootstrap uses plug-in propensity weights: weights computed on the full data are reused in each resample rather than re-estimating the propensity model. This is appropriate for assessing sampling variability in the balance diagnostic given a fixed propensity model.

oda_balance_table is called with mcarlo = FALSE; MC p-values are not computed during bootstrap iterations.

See also

oda_propensity_weights, cta_propensity_weights, oda_balance_table

Examples

set.seed(1L)
n     <- 80L
group <- c(rep(0L, 40L), rep(1L, 40L))
x_pv  <- c(rnorm(40, 0), rnorm(40, 3))
prop_fit <- oda_fit(x = x_pv, y = group)
X_bal <- data.frame(age   = c(rnorm(40, 45), rnorm(40, 55)),
                    score = rnorm(80))
# \donttest{
peb <- propensity_ess_balance(prop_fit, group, X_bal,
                               x_prop = x_pv, n_boot = 50L, seed = 1L)
print(peb[, c("variable", "unweighted_ess", "weighted_ess",
              "delta_ess", "crosses_null")])
#>   variable unweighted_ess weighted_ess delta_ess crosses_null
#> 1      age          100.0    100.00000   0.00000         TRUE
#> 2    score           17.5     40.94175  23.44175         TRUE
# }