Univariate ODA covariate balance diagnostics

Fits a univariate ODA model for each covariate in X with group as the class variable. Returns one row per covariate summarizing ODA-based balance diagnostics: rule, sensitivity, specificity, Mean PAC, ESS/WESS, and permutation p-value with Sidak and Bonferroni multiplicity corrections.

Usage

oda_balance_table(
  group,
  X,
  w = NULL,
  covariate_types = NULL,
  loo = "off",
  mcarlo = TRUE,
  mc_iter = 1000L,
  alpha = 0.05,
  adjust = c("none", "sidak", "bonferroni"),
  ...
)

Arguments

group: Integer (or coercible) binary group indicator. Must have exactly two distinct non-missing values. Plays the role of the class variable (y) in ODA.
X: Data frame of baseline covariate columns. Plays the role of attributes (x) in ODA. Must have nrow(X) == length(group).
w: Optional numeric case-weight vector (length length(group)). When supplied, ODA fits use case weights and ess_label = "WESS".
covariate_types: Optional named character vector mapping column names to ODA attribute types ("auto", "ordered", "categorical", "binary"). Unmapped columns use "auto".
loo: LOO gate mode passed to each oda_fit call. Default "off". See oda_fit for options.
mcarlo: Logical; run Monte Carlo permutation p-value? Default TRUE. Set FALSE to skip p-value computation.
mc_iter: Integer; maximum MC iterations per covariate. Default 1000L. Higher values (e.g., 25000L) are recommended for final published analyses but increase runtime.
alpha: Numeric significance threshold for the significant flag. Default 0.05.
adjust: Character; which p-value drives the primary significant column: "none" (raw p, default), "sidak", or "bonferroni". All three significance flags are always returned regardless of this choice.
...: Additional arguments forwarded to each oda_fit call (e.g., mc_seed, priors_on, mc_stop).

Value

A list of class "oda_balance_table" with elements:

rows: Data frame; one row per covariate. Key columns: attribute, attr_type, n_total, n_group_0, n_group_1, sensitivity, specificity, mean_pac, ess, wess, ess_display (operative measure), p_mc, p_sidak, p_bonferroni, significant_raw, significant_sidak, significant_bonferroni, significant (driven by adjust), rule_type, rule_summary, loo_status, ess_loo, has_weights, fit_ok, fit_reason.
meta: List of metadata: n_covariates, n_obs, has_weights, ess_label, alpha, adjust, k_valid (number of covariates with valid p_mc used for multiplicity correction), loo_mode, mcarlo, mc_iter.

Details

Balance asks whether group membership (treatment, exposure, or study arm) can be predicted from observed baseline covariates. When no covariate predicts group membership above chance, the groups are considered balanced on those covariates under the declared analytic constraints.

group vs. outcome: group is the binary class variable in every ODA call. The scientific outcome of interest is strictly out of scope; do not pass the outcome as group or as a column of X.

SMD: conventional standardized mean difference is a companion diagnostic, not the oda balance objective. Use smd_balance_table for the conventional companion table.

References

Linden A, Yarnold PR (2016). Using machine learning to assess covariate balance in matching studies. Journal of Evaluation in Clinical Practice, 22(6), 861-867.

Examples

set.seed(1)
n <- 60
group <- c(rep(0L, 30), rep(1L, 30))
X <- data.frame(
  age    = c(rnorm(30, 45, 8), rnorm(30, 55, 8)),   # imbalanced
  score  = rnorm(60, 50, 10)                         # balanced
)
bt <- oda_balance_table(group, X, mcarlo = TRUE, mc_iter = 500L)
bt$rows[, c("attribute", "ess_display", "p_mc", "significant_raw")]
#>   attribute ess_display  p_mc significant_raw
#> 1       age    63.33333 0.000            TRUE
#> 2     score    20.00000 0.606           FALSE