tabmulti: Compare Multivariable Model-Building Strategies
In R4VN: Health Data Analysis and Publication-Ready Reporting

tabmulti

R Documentation

Compare Multivariable Model-Building Strategies

Description

Builds and compares variable-selection strategies for a binary outcome. Each strategy selects complete variables or terms, after which the selected model is refitted using ordinary logistic regression or modified Poisson regression so that conventional OR, RR, or PR estimates, 95% confidence intervals, and p-values can be reported.

Usage

tabmulti(data = NULL, vars = NULL, by = NULL,
         methods = c("full", "forward", "backward", "purposeful"),
         digit = 1, p_digit = 3, effect_digit = 2, global = FALSE,
         pvalue = TRUE, rvrow = NULL, bold_p = TRUE, p_bold = 0.05,
         or = FALSE, rr = FALSE, pr = FALSE, event = NULL,
         criterion = c("AIC", "BIC"), force = NULL, entry = 0.20,
         stay = 0.05, confounding = 0.10, lasso_lambda = "lambda.1se",
         bma_pip = 0.50, max_subset_vars = 15L, max_subset_models = 100000L,
         template = c("journal", "clean", "minimal"), append = NULL,
         file = NULL, raw = FALSE, name = FALSE, title = NULL, show = TRUE)

Arguments

`data`	Optional data frame. When omitted or `NULL`, the active data frame set by `usedf()` or `opendata(..., active = TRUE)` is used.
`vars`	A variable specification created by `vars()`.
`by`	Binary outcome supplied without quotation marks.
`methods`	Model strategies: `"full"`, `"forward"`, `"backward"`, `"purposeful"`, `"lasso"`, `"bma"`, or `"best"`.
`digit`	Retained for API consistency with `tab()`.
`p_digit`	Number of decimal places for p-values.
`effect_digit`	Number of decimal places for effect estimates and confidence limits.
`global`	Logical. Display global likelihood-ratio p-values.
`pvalue`	Logical. Display coefficient p-value columns.
`rvrow`	Categorical variables whose displayed level order should be reversed. This does not change model reference categories.
`bold_p`	Logical. Bold p-values smaller than `p_bold`.
`p_bold`	Threshold used when `bold_p = TRUE`.
`or`	Logical. Report odds ratios from logistic regression.
`rr`	Logical. Report risk ratios from modified Poisson regression.
`pr`	Logical. Report prevalence ratios from modified Poisson regression. Exactly one of `or`, `rr`, and `pr` must be `TRUE`.
`event`	Event level. The last observed outcome level is used when omitted.
`criterion`	Selection criterion, `"AIC"` or `"BIC"`.
`force`	Variables forced into every selected model. Accepts `vars(...)`, `c(...)`, a character vector, `TRUE`, or `"ALL"`.
`entry`	Univariate entry threshold for purposeful selection.
`stay`	Multivariable retention threshold for purposeful selection.
`confounding`	Relative coefficient-change threshold for identifying a confounder during purposeful selection.
`lasso_lambda`	Either `"lambda.min"` or `"lambda.1se"`.
`bma_pip`	Posterior inclusion-probability threshold used by the BIC-weighted BMA strategy.
`max_subset_vars`	Maximum number of candidate variables for exhaustive subset methods.
`max_subset_models`	Maximum number of subset models to evaluate.
`template`	HTML style: `"journal"`, `"clean"`, or `"minimal"`.
`append`	Optional previous `r4vn_tabmulti` object or existing HTML path.
`file`	Optional output HTML path.
`raw`	Logical. Retain unformatted coefficients and selection details.
`name`	Logical. Display original variable names beside labels.
`title`	Optional table title.
`show`	Logical. Open the HTML table in the Viewer or browser.

Details

Available strategies are:

full: include every candidate variable;
forward: forward stepwise selection using AIC or BIC;
backward: backward stepwise selection from the full model;
purposeful: univariate screening followed by significance and confounding assessment;
lasso: selection with glmnet::cv.glmnet(), followed by ordinary-model refitting; requires the suggested package glmnet;
bma: BIC-weighted subset averaging and inclusion-probability thresholding;
best: select the subset with the smallest AIC or BIC.

All strategies use the same complete-case sample. Diagnostic rows include sample size, events, number of variables and parameters, AIC, BIC, pseudo-R-squared measures, goodness-of-fit tests, AUC where applicable, and the coefficient-level VIF range. Exhaustive methods grow exponentially with the number of candidate variables.

Value

Invisibly returns an object of class r4vn_tabmulti. Important components include data, selected, models, diagnostics, file, html, and table_html.

Examples

set.seed(2026)
n <- 180
dat <- data.frame(
  age = round(rnorm(n, 45, 12)),
  sex = factor(sample(c("Female", "Male"), n, TRUE)),
  bmi = round(rnorm(n, 23, 3), 1),
  smoking = factor(sample(c("No", "Yes"), n, TRUE,
                          prob = c(0.70, 0.30))),
  education = factor(sample(c("Primary", "Secondary", "College"),
                            n, TRUE))
)
lp <- -3.1 + 0.045 * dat$age + 0.11 * (dat$bmi - 23) +
      0.45 * (dat$sex == "Male") + 0.70 * (dat$smoking == "Yes")
dat$hypertension <- factor(
  rbinom(n, 1, plogis(lp)),
  levels = c(0, 1), labels = c("No", "Yes")
)

models <- tabmulti(
  dat,
  vars = vars(c.age, b2.sex, c.bmi, b2.smoking, b2.education),
  by = hypertension,
  methods = c("full", "backward"),
  or = TRUE,
  event = "Yes",
  criterion = "AIC",
  global = TRUE,
  show = FALSE
)
models$selected
models$diagnostics


# LASSO requires the suggested package glmnet.
if (requireNamespace("glmnet", quietly = TRUE)) {
models_lasso <- tabmulti(
  dat,
  vars = vars(c.age, b2.sex, c.bmi, b2.smoking, b2.education),
  by = hypertension,
  methods = c("full", "lasso"),
  or = TRUE,
  event = "Yes",
  show = FALSE
)
}


# Extended usage examples

set.seed(2026)
n <- 400
d <- data.frame(
  sex = factor(sample(c("Female", "Male"), n, TRUE)),
  age = rnorm(n, 45, 12),
  bmi = rnorm(n, 23, 3),
  smoking = factor(sample(c("No", "Yes"), n, TRUE)),
  education = factor(sample(c("Primary", "Secondary", "College"), n, TRUE))
)
lp <- -3.2 + 0.045 * d$age + 0.10 * (d$bmi - 23) +
      0.45 * (d$sex == "Male") + 0.70 * (d$smoking == "Yes")
d$outcome <- factor(rbinom(n, 1, plogis(lp)),
                    levels = 0:1, labels = c("No", "Yes"))

# Full multivariable logistic model
m1 <- tabmulti(
  d,
  vars = vars(b2.sex, c.age, c.bmi, b2.smoking, b2.education),
  by = outcome,
  methods = "full",
  or = TRUE,
  event = "Yes",
  show = FALSE
)

# Compare several model-building strategies in one table
m2 <- tabmulti(
  d,
  vars = vars(b2.sex, c.age, c.bmi, b2.smoking, b2.education),
  by = outcome,
  methods = c("full", "forward", "backward", "purposeful"),
  or = TRUE,
  event = "Yes",
  criterion = "AIC",
  global = TRUE,
  show = FALSE
)
m2$selected
m2$diagnostics

# Force variables into every selected model and tune purposeful selection
tabmulti(
  d,
  vars = vars(b2.sex, c.age, c.bmi, b2.smoking, b2.education),
  by = outcome,
  methods = "purposeful",
  force = vars(age, sex),
  entry = 0.20, stay = 0.05, confounding = 0.10,
  or = TRUE, event = "Yes", show = FALSE
)

# Modified Poisson models for RR or PR
tabmulti(d, vars = vars(b2.sex, c.age, c.bmi, b2.smoking),
         by = outcome, methods = "full", rr = TRUE,
         event = "Yes", show = FALSE)
tabmulti(d, vars = vars(b2.sex, c.age, c.bmi, b2.smoking),
         by = outcome, methods = "full", pr = TRUE,
         event = "Yes", show = FALSE)

# Display and output controls
tabmulti(d, vars = vars(b2.sex, c.age, c.bmi, b2.smoking),
         by = outcome, methods = c("full", "backward"),
         or = TRUE, event = "Yes", rvrow = vars(smoking),
         pvalue = TRUE, bold_p = TRUE, p_bold = 0.05,
         template = "clean", raw = TRUE, name = TRUE,
         title = "Model-building comparison", show = FALSE)

# Active-data syntax
usedf(d)
tabmulti(vars = vars(b2.sex, c.age, c.bmi, b2.smoking),
         by = outcome, methods = "full", or = TRUE,
         event = "Yes", show = FALSE)

# LASSO requires glmnet; BMA/best are exhaustive and suit fewer candidates
if (requireNamespace("glmnet", quietly = TRUE)) {
tabmulti(d, vars = vars(b2.sex, c.age, c.bmi, b2.smoking),
         by = outcome, methods = c("full", "lasso"), or = TRUE,
         event = "Yes", lasso_lambda = "lambda.1se", show = FALSE)
}
tabmulti(d, vars = vars(b2.sex, c.age, c.bmi, b2.smoking),
         by = outcome, methods = c("best", "bma"), or = TRUE,
         event = "Yes", criterion = "BIC", bma_pip = 0.50,
         max_subset_vars = 10, show = FALSE)

R4VN documentation built on Sept. 30, 2026, 5:13 p.m.