efficacy_table: Create Regulatory-Style Efficacy Summary Table

Description

Takes an rbmi pool object and produces a publication-ready gt table in the style of CDISC/ICH Table 14.2.x. The table displays least squares means by treatment arm, treatment differences, confidence intervals, and p-values, organized by visit row groups.

Usage

efficacy_table(
  pool_obj,
  title = NULL,
  subtitle = NULL,
  digits = 2,
  ci_level = NULL,
  arm_labels = NULL,
  pval_digits = 3,
  pval_threshold = 0.001,
  font_family = NULL,
  font_size = NULL,
  row_padding = NULL,
  ...
)

Value

A gt table object of class gt_tbl.

Arguments

pool_obj: A pooled analysis object of class "pool", typically obtained from rbmi::pool() after calling analyse_mi_data().
title: Optional character string for the table title.
subtitle: Optional character string for the table subtitle.
digits: Integer. Number of decimal places for estimates and standard errors. Default is 2.
ci_level: Numeric. Confidence level for CI column labeling. If NULL (the default), extracted from pool_obj$conf.level. Falls back to 0.95 if neither is available.
arm_labels: Named character vector with elements "ref" and "alt" providing custom labels for the reference and treatment arms. If NULL (the default), uses "Reference" and "Treatment".
pval_digits: Integer. Number of decimal places for p-values. Default is 3.
pval_threshold: Numeric. P-values below this threshold are displayed as "< threshold". Default is 0.001.
font_family: Optional character string specifying the font family for the table. When NULL (default), uses gt's default font. Applied via gt::opt_table_font().
font_size: Optional numeric value specifying the table font size in pixels. When NULL (default), uses gt's default size. Applied via gt::tab_options().
row_padding: Optional numeric value specifying the vertical padding for data rows in pixels. When NULL (default), uses gt's default padding. Smaller values (e.g., 2-3) create compact regulatory-style tables.
...: Additional arguments passed to gt::gt().

Details

This function assumes a single-parameter-per-visit pool object (the standard output from an rbmi ANCOVA or MMRM pipeline). It internally calls tidy_pool_obj() to parse the pool object, then constructs the gt table.

Arm labels: Use the arm_labels parameter to customize arm names in the table. For example, arm_labels = c(ref = "Placebo", alt = "Drug A") will display "LS Mean (Placebo)" and "LS Mean (Drug A)" instead of the defaults.

Customization: The returned gt object can be further customized using standard gt piping, e.g., efficacy_table(pool_obj) |> gt::tab_options(...).

Example output:

Examples

Run this code

# \donttest{
if (requireNamespace("gt", quietly = TRUE)) {
  library(rbmi)
  data("ADMI", package = "rbmiUtils")
  ADMI$TRT <- factor(ADMI$TRT, levels = c("Placebo", "Drug A"))
  ADMI$USUBJID <- factor(ADMI$USUBJID)
  ADMI$AVISIT <- factor(ADMI$AVISIT)

  vars <- set_vars(
    subjid = "USUBJID", visit = "AVISIT", group = "TRT",
    outcome = "CHG", covariates = c("BASE", "STRATA", "REGION")
  )
  method <- method_bayes(
    n_samples = 20,
    control = control_bayes(warmup = 20, thin = 1)
  )

  ana_obj <- analyse_mi_data(ADMI, vars, method, fun = ancova)
  pool_obj <- pool(ana_obj)

  # Basic table
  tbl <- efficacy_table(pool_obj)

  # Publication-styled table
  efficacy_table(
    pool_obj,
    title = "Table 14.2.1: ANCOVA of Change from Baseline",
    subtitle = "Mixed Model for Repeated Measures",
    arm_labels = c(ref = "Placebo", alt = "Drug A"),
    font_size = 12,
    row_padding = 4
  )
}
# }