CTA covariate balance evidence-interval summary

Builds one row per analysis scale (multivariate CTA) containing the observed full-tree ESS/WESS, a bootstrap confidence interval, and a chance interval. This is the multivariate analogue of oda_balance_effect_table: a single CTA ENUMERATE run per bootstrap or permutation iteration classifies all covariates jointly.

Usage

cta_balance_effect_summary(
  group,
  X,
  w = NULL,
  compare_weights = FALSE,
  mindenom = 1L,
  nboot = 200L,
  chance_iter = 200L,
  ci = 0.95,
  mc_seed = NULL,
  mc_iter = 5000L,
  ...
)

Arguments

group: Integer (or coercible) binary group indicator.
X: Data frame of baseline covariate columns.
w: Optional numeric case-weight vector.
compare_weights: Logical; when TRUE and w is supplied, produces two rows: "unweighted" and "weighted". Default FALSE.
mindenom: Integer minimum endpoint denominator. Default 1L.
nboot: Integer bootstrap resamples. Default 200L (CTA ENUMERATE is expensive per iteration).
chance_iter: Integer group-label permutations. Default 200L.
ci: Numeric nominal coverage. Default 0.95.
mc_seed: Integer RNG seed set once at function entry. NULL for unseeded.
mc_iter: Integer CTA MC iterations per node for the observed fit. Default 5000L.
...: Additional arguments forwarded to cta_fit for the observed fit (e.g., alpha_split, prune_alpha). mindenom, mc_iter, mc_seed, and loo are controlled internally.

Value

A list of class "cta_balance_effect_summary" with:

rows: Data frame; one row per analysis scale. Columns: analysis, metric, estimate, boot_lo, boot_hi, chance_lo, chance_hi, d_stat, n_endpoints, root_attribute, status, balance_interpretation.
meta: List: n_obs, has_weights, compare_weights, analyses, mindenom, nboot, chance_iter, ci, mc_iter, mc_seed.

Details

Three passes are run:

Observed: full cta_fit() with mc_iter – point estimate and tree metadata.
Bootstrap: nboot row-resamples, loo = "off" – ESS/WESS percentile CI. no_tree results contribute 0.
Chance: chance_iter group-label permutations – null percentile interval. no_tree results contribute 0.

no_tree convention: when CTA finds no admissible tree on a bootstrap or chance iteration, ESS = 0 (no discrimination above chance). The observed no_tree result is also recorded as estimate = 0.

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

X <- data.frame(
  A = c(rep(0L, 20), rep(1L, 20), rep(1L, 20)),
  B = c(rep(0L, 20), rep(0L, 20), rep(1L, 20))
)
group <- c(rep(0L, 40), rep(1L, 20))
ces <- cta_balance_effect_summary(group, X, mindenom = 5L,
                                   mc_iter = 200L, mc_seed = 42L,
                                   nboot = 20L, chance_iter = 20L)
ces$rows[, c("analysis", "estimate", "boot_lo", "boot_hi",
             "chance_lo", "chance_hi", "status")]
#>     analysis estimate boot_lo boot_hi chance_lo chance_hi     status
#> 1 unweighted      100     100     100         0         0 valid_tree