run_eba: Extreme-Bounds Analysis (EBA) over Control-Variable...

In bivarhr: Bivariate Hurdle Regression with Bayesian Model Averaging

Extreme-Bounds Analysis (EBA) over Control-Variable Combinations

Description

Runs an Extreme-Bounds Analysis (EBA) over a predefined set of control variable combinations, fitting (or re-fitting) the bivariate hurdle model for each combination and extracting posterior mean coefficients for all regression blocks (mu_I, pi_I, mu_C, pi_C).

Usage

run_eba(
  DT,
  spec = "C",
  control_combos,
  k_bma_table = NULL,
  seed = 123,
  dir_csv = NULL
)

Arguments

DT	A data.table or data.frame with the data passed to fit_one().
spec	Character scalar; model specification (e.g.\ "A", "B", "C", "D") passed to fit_one().
control_combos	A named list whose names are control tags (e.g.\ "None", "X1+X2", "X1+X3+X4") and whose elements are the corresponding character vectors of control-variable names, defining which control sets to explore.
k_bma_table	Optional object (typically a named list or list-like structure) indexed by control-combination tags that indicates for which combinations a BMA selection table already exists. If k_bma_table[[tag]] is NULL or bma_weights_* CSV is missing, the function falls back to a default fit with k = 2 and default horseshoe hyperparameters.
seed	Integer; base random seed for the fits. For different control combinations, the seed is jittered to avoid identical pseudo-random sequences.
dir_csv	Character scalar or NULL; directory where BMA weight CSV files are read from and where the coefficient table ("eba_coefficients.csv") is written. If NULL (default), no BMA files are read (each combination uses the default fit) and no CSV is written.

Details

This function relies on fit_one(), which requires cmdstanr and a working CmdStan installation.

For each control-combination tag tag:

• If a BMA weights file "bma_weights_spec<spec>_ctrl<tag>.csv" exists in dir_csv and k_bma_table[[tag]] is not NULL, the top-weighted row (highest weight) is used to select k and horseshoe hyperparameters (hs_tau0, hs_slab_scale, hs_slab_df) for the fit.

• Otherwise, the model is fit with k = 2 and default horseshoe hyperparameters.

• Posterior means of the regression coefficients with prefixes "b_mu_I", "b_pi_I", "b_mu_C", "b_pi_C" are extracted and mapped back to the corresponding column names of the design matrices.

All coefficient summaries are stacked into a single table and, when dir_csv is supplied, written to "eba_coefficients.csv" in that directory.

Value

A data.frame with the columns:

• name: name of the covariate (design-matrix column).

• mean: posterior mean of the corresponding coefficient.

• block: block identifier ("mu_I", "pi_I", "mu_C", "pi_C").

• combo: control-combination tag used for that fit.

Examples

# This example fits Stan models and therefore runs only in an
# interactive session with 'cmdstanr' and a working CmdStan.
if (interactive() && requireNamespace("cmdstanr", quietly = TRUE)) {
  DT <- data.table::data.table(
    I = rpois(21, lambda = 4),
    C = rpois(21, lambda = 3),
    zI = rnorm(21),
    zC = rnorm(21),
    t_norm = seq(-1, 1, length.out = 21),
    t_poly2 = seq(-1, 1, length.out = 21)^2,
    Regime = factor(sample(c("A", "B"), 21, replace = TRUE)),
    trans_PS = sample(0:1, 21, replace = TRUE),
    trans_SF = sample(0:1, 21, replace = TRUE),
    trans_FC = sample(0:1, 21, replace = TRUE),
    log_exposure50 = rep(0, 21),
    X1 = rnorm(21), X2 = rnorm(21), X3 = rnorm(21)
  )

  combos <- list(
    None       = character(0),
    "X1+X2"    = c("X1", "X2"),
    "X1+X2+X3" = c("X1", "X2", "X3")
  )

  eba_tab <- run_eba(DT, spec = "C", control_combos = combos, seed = 123)
  print(head(eba_tab))
}

bivarhr documentation built on July 7, 2026, 1:06 a.m.