Nothing
# =============================================================================
# MRCT Simulation Functions for ForestSearch Package
# =============================================================================
#
# Multi-Regional Clinical Trial (MRCT) simulation framework for evaluating
# subgroup identification methods using ForestSearch. Supports scenarios with
# heterogeneous treatment effects across regions.
#
# Key functions:
# - mrct_region_sims(): Main simulation function
# - create_dgm_for_mrct(): DGM creation wrapper for MRCT scenarios
# - summaryout_mrct(): Summary table generation
# - SGplot_estimates(): Visualization of HR estimates
#
# =============================================================================
# =============================================================================
# Main Simulation Function: mrct_region_sims
# =============================================================================
#' MRCT Regional Subgroup Simulation
#'
#' Simulates multi-regional clinical trials and evaluates ForestSearch subgroup
#' identification. Splits data by region into training and testing populations,
#' identifies subgroups using ForestSearch on training data, and evaluates
#' performance on the testing region.
#'
#' @param dgm Data generating mechanism object from \code{\link{generate_aft_dgm_flex}}
#' @param n_sims Integer. Number of simulations to run
#' @param n_sample Integer. Sample size per simulation. If NULL (default), uses
#' the entire super-population from dgm
#' @param region_var Character. Name of the region indicator variable used to split
#' data into training (region_var == 0) and testing (region_var == 1) populations.
#' Default: "z_regA"
#' @param sg_focus Character. Subgroup selection criterion passed to
#' \code{\link{forestsearch}}: "minSG", "hr", or "maxSG". Default: "minSG"
#' @param maxk Integer. Maximum number of factors in subgroup combinations (1 or 2).
#' Default: 1
#' @param hr.threshold Numeric. `c1`, the screening threshold on a candidate
#' subgroup's own hazard ratio, passed to \code{\link{forestsearch}}.
#' Default: 0.90
#' @param hr.consistency Numeric. `c2`, \strong{an effect threshold} -- the
#' minimum hazard ratio required in each half of a split. Not a proportion
#' and not the consistency rate.
#' Default: 0.80
#' @param pconsistency.threshold Numeric. `p*`, \strong{a proportion} in
#' \code{[0, 1]} -- the fraction of splits that must clear
#' \code{hr.consistency} (`c2`). Not an effect threshold.
#' Default: 0.90
#' @param confounders.name Character vector. Confounder variable names for ForestSearch.
#' If NULL, automatically extracted from dgm: the columns of
#' \code{dgm$df_super} whose names start with \code{z_}, \code{ecog} or
#' \code{strat}, except that, for a mechanism built with a spline
#' (\code{dgm$model_params$spline_info}), the three internal columns of the
#' spline variable \code{<var>} are left out by their exact names
#' \code{<var>_treat}, \code{<var>_k} and \code{<var>_k_treat} (for
#' \code{\link{create_dgm_for_mrct}}: \code{z_bm_treat}, \code{z_bm_k},
#' \code{z_bm_k_treat}). A covariate such as \code{z_prior_treat} and the
#' region indicator stay in the set.
#' @param conf_force Character vector. Forced cuts to consider in ForestSearch.
#' Default: NULL, which resolves to
#' c("z_age <= 65", "z_bm <= 0", "z_bm <= 1", "z_bm <= 2", "z_bm <= 5")
#' @param fs_args Named list. Additional arguments passed directly to
#' \code{\link{forestsearch}} inside each simulation replicate. Use this to
#' control parameters not exposed by \code{mrct_region_sims} (e.g.,
#' \code{use_grf}, \code{use_lasso}, \code{cut_type}, \code{d0.min},
#' \code{d1.min}, \code{n.min}, \code{max_subgroups_search},
#' \code{use_twostage}, \code{twostage_args}).
#' Parameters already in the \code{mrct_region_sims} signature
#' (\code{hr.threshold}, \code{hr.consistency}, \code{pconsistency.threshold},
#' \code{sg_focus}, \code{maxk}, \code{confounders.name}, \code{conf_force})
#' take precedence over values in \code{fs_args}.
#' Default: list() (uses forestsearch defaults)
#' @param sim_args Named list. Additional arguments passed to
#' \code{\link{simulate_from_dgm}} inside each replicate (e.g.,
#' \code{rand_ratio}, \code{draw_treatment}, \code{max_entry}, or
#' \code{entry_delay = list(var = "z_region", delay = a)} for a region
#' enrolling \code{a} time units later, redrawn every replicate).
#' If \code{dgm$df_super} has a column \code{entrytime}, it is passed as
#' \code{entry_var = "entrytime"} (one fixed entry time per
#' super-population row) and takes precedence over \code{entry_delay}.
#' Parameters already in the \code{mrct_region_sims} signature
#' (\code{analysis_time}, \code{cens_adjust}) take precedence.
#' Default: list(rand_ratio = 1, draw_treatment = TRUE)
#' @param analysis_time Numeric. Time of analysis for administrative censoring.
#' Default: 60
#' @param cens_adjust Numeric. Adjustment factor for censoring rate on log scale.
#' Default: 0
#' @param parallel_args List. Parallel processing configuration with components:
#' \itemize{
#' \item plan: "multisession", "multicore", "callr", or "sequential"
#' \item workers: Number of workers (NULL for auto-detect)
#' \item show_message: Logical for progress messages
#' }
#' @param details Logical. Print detailed progress information. Default: FALSE
#' @param verbose_n_sims Integer. When \code{details = TRUE}, print full
#' ForestSearch diagnostics (including internal output) for only the first
#' \code{verbose_n_sims} simulation replicates. Set to 0 to suppress per-sim
#' output, or \code{Inf} to print all. Default: 2
#' @param seed Integer. Base random seed for reproducibility. Default: NULL
#' @param record Character. \code{"point"} (default) returns the point
#' estimates only, exactly as before this argument existed. \code{"full"}
#' adds, from the same simulated trials (nothing is redrawn), the
#' per-replicate record described under \emph{Full record} below.
#'
#' @return A data.table with simulation results containing:
#' \describe{
#' \item{sim}{Simulation index}
#' \item{n_itt}{ITT sample size}
#' \item{hr_itt}{ITT hazard ratio (stratified if strat variable present)}
#' \item{hr_ittX}{ITT hazard ratio stratified by region}
#' \item{n_train}{Training (non-region A) sample size}
#' \item{hr_train}{Training population hazard ratio}
#' \item{n_test}{Testing (region A) sample size}
#' \item{hr_test}{Testing population hazard ratio}
#' \item{any_found}{Indicator: 1 if subgroup identified, 0 otherwise}
#' \item{sg_found}{Character description of identified subgroup}
#' \item{n_sg}{Subgroup sample size}
#' \item{hr_sg}{Subgroup hazard ratio in testing population}
#' \item{POhr_sg}{Potential outcome hazard ratio in subgroup (testing)}
#' \item{prev_sg}{Subgroup prevalence (proportion of testing population)}
#' \item{n_sg_train}{Subgroup sample size in training population}
#' \item{hr_sg_train}{Subgroup hazard ratio in training population}
#' \item{POhr_sg_train}{Potential outcome hazard ratio in subgroup (training)}
#' \item{hr_sg_null}{Subgroup HR when found, NA otherwise}
#' }
#' With \code{record = "full"}, the same table followed by the columns
#' \code{TP_nonregion}, \code{FP_nonregion}, \code{FN_nonregion},
#' \code{TN_nonregion}, \code{TP_region}, \code{FP_region},
#' \code{FN_region}, \code{TN_region}, then the multiplier-resampling
#' columns \code{mr_ci_method}, \code{mr_debiased_H}, \code{mr_ij_lower_H},
#' \code{mr_ij_upper_H}, \code{mr_field_lower_1s_H}, \code{mr_debiased_Hc},
#' \code{mr_ij_lower_Hc}, \code{mr_ij_upper_Hc},
#' \code{mr_field_upper_1s_Hc}, \code{mr_field_upper_1s_s_Hc},
#' \code{mr_bonf_lower_H}, \code{mr_bonf_upper_Hc}, \code{mr_p_hat_H},
#' \code{mr_selection_rate}, and the attribute \code{"estimators"} (see
#' \emph{Full record}).
#'
#' @details
#' ## Simulation Process
#'
#' For each simulation:
#' 1. Sample from super-population using \code{\link{simulate_from_dgm}}
#' 2. Split by region_var into training and testing populations
#' 3. Estimate HRs in ITT, training, and testing populations
#' 4. Run \code{\link{forestsearch}} on training population
#' 5. Apply identified subgroup to testing population
#' 6. Calculate subgroup-specific estimates
#'
#' ## Region Variable
#'
#' The region_var parameter is used ONLY for splitting data into training/testing
#' populations. It does not imply any prognostic effect. To include prognostic
#' confounder effects, specify them when creating the DGM using
#' \code{\link{create_dgm_for_mrct}} or \code{\link{generate_aft_dgm_flex}}.
#'
#' ## Full record
#'
#' With \code{record = "full"} the returned table is the \code{"point"}
#' table with twenty-two columns added (eight counts, then fourteen
#' multiplier-resampling columns) and a second table attached as an
#' attribute, \code{est <- attr(res, "estimators")}; \code{res$hr_itt},
#' \code{nrow(res)} and every \code{"point"} column are unchanged. (A
#' data.table subset such as \code{res[order(sim)]} drops the attribute:
#' take it first.)
#'
#' \code{estimators} has one row per trial and patient set:
#' \code{itt_all} (all patients), \code{itt_nonregion}
#' (\code{region_var == 0}), \code{itt_region} (\code{region_var == 1}),
#' \code{region_Ghat} (the region outside the declared harm subgroup
#' \eqn{\hat H}; the whole region in an undeclared trial),
#' \code{region_Gstar} (the region with \code{flag_harm == 0}) and
#' \code{Hstar_nonregion} (the non-region patients with
#' \code{flag_harm == 1}). Columns: \code{sim}, \code{estimator},
#' \code{n}, \code{n_exp}, \code{events_exp}, \code{events_ctl}; the
#' unadjusted two-sample Cox fit \code{Surv(y_sim, event_sim) ~ treat_sim}
#' on the set, \code{hr}, \code{lo}, \code{hi} (Wald 95\%) and
#' \code{se_loghr} (a fit with an arm without events is kept; a fit that
#' errors, e.g. on an empty set, gives \code{NA}); the targets on the same
#' patients, \code{ahr} = \code{exp(mean(loghr_po))} and \code{cde} =
#' \code{mean(exp(theta_1)) / mean(exp(theta_0))} (\code{NA} when the
#' simulated trial lacks those columns); and \code{declared} (0/1, the
#' trial's \code{any_found}). \code{itt_all} is unadjusted, so it equals
#' \code{hr_itt} only when the trial has no \code{strat} column.
#'
#' The added columns of the per-trial table are the 2 x 2 counts of
#' \eqn{\hat H} membership against \code{flag_harm == 1} over the
#' non-region patients and over the region patients. \eqn{\hat H} is
#' evaluated from the selected definition with \code{\link{get_dfpred}}
#' (the route of \code{df.test}); it is empty in an undeclared trial, whose
#' counts are kept.
#'
#' When the simulated trial has no \code{flag_harm} column, the
#' \code{region_Gstar} and \code{Hstar_nonregion} rows are omitted and the
#' counts are \code{NA}, with a message.
#'
#' After the counts come fourteen columns read from the trial's
#' \code{forestsearch()} result \code{fs$mr_inference} (multiplier
#' resampling, \code{fs_args = list(mr_inference = TRUE, ...)}; see
#' \code{\link{fs_mr_inference}}), on the effect (HR) scale:
#' \describe{
#' \item{\code{mr_ci_method}}{\code{ci_method}.}
#' \item{\code{mr_debiased_H}, \code{mr_ij_lower_H},
#' \code{mr_ij_upper_H}}{\code{debiased$est}, \code{$lower},
#' \code{$upper}: the de-biased estimate on \eqn{\hat H} and its
#' interval (IJ SE under \code{"ij"} and \code{"field"}, robust SE under
#' \code{"wald"}).}
#' \item{\code{mr_field_lower_1s_H}}{\code{field$lower_1s}.}
#' \item{\code{mr_debiased_Hc}, \code{mr_ij_lower_Hc},
#' \code{mr_ij_upper_Hc}}{\code{complement$debiased$est},
#' \code{$lower}, \code{$upper}.}
#' \item{\code{mr_field_upper_1s_Hc},
#' \code{mr_field_upper_1s_s_Hc}}{\code{field$complement$upper_1s} and
#' its studentized companion \code{field$complement$upper_1s_s}.}
#' \item{\code{mr_bonf_lower_H}, \code{mr_bonf_upper_Hc}}{
#' \code{field$joint$bonf_lower_H}, \code{field$joint$bonf_upper_Hc}.}
#' \item{\code{mr_p_hat_H}}{\code{reselection$p_hat[selected_index]}.}
#' \item{\code{mr_selection_rate}}{\code{selection_rate}.}
#' }
#' Each is \code{NA} when its element is absent: every one in a trial
#' without \code{mr_inference} or without a declared subgroup (nothing to
#' de-bias), or with the short MR return; the
#' complement columns without \code{include_complement = TRUE}; the field
#' columns unless \code{ci_method = "field"}; the complement field and
#' Bonferroni columns without \code{field_complement = TRUE};
#' \code{mr_p_hat_H} without \code{return_reselection = TRUE}. Under
#' \code{record = "point"} none of these columns is added.
#'
#' @examples
#' \dontrun{
#' # Create DGM for alternative hypothesis
#' dgm_alt <- create_dgm_for_mrct(
#' df_case = df_case,
#' model_type = "alt",
#' log_hrs = log(c(3, 1.25, 0.50)),
#' verbose = TRUE
#' )
#'
#' # Run simulations
#' results <- mrct_region_sims(
#' dgm = dgm_alt,
#' n_sims = 100,
#' region_var = "z_regA",
#' sg_focus = "minSG",
#' parallel_args = list(plan = "multisession", workers = 4),
#' details = TRUE
#' )
#'
#' # Summarize results
#' cat("Subgroup identification rate:", mean(results$any_found) * 100, "%\n")
#' }
#'
#' @seealso
#' \code{\link{forestsearch}} for subgroup identification algorithm
#' \code{\link{generate_aft_dgm_flex}} for DGM creation
#' \code{\link{simulate_from_dgm}} for data simulation
#' \code{\link{create_dgm_for_mrct}} for MRCT-specific DGM wrapper
#' \code{\link{summaryout_mrct}} for summarizing simulation results
#'
#' @importFrom survival coxph Surv
#' @importFrom data.table data.table as.data.table fifelse copy
#' @importFrom foreach foreach
#' @importFrom doFuture %dofuture%
#' @importFrom future plan sequential multisession multicore nbrOfWorkers
#' @importFrom progressr progressor handlers with_progress
#' @export
mrct_region_sims <- function(
dgm,
n_sims,
n_sample = NULL,
region_var = "z_regA",
sg_focus = "minSG",
maxk = 1,
hr.threshold = 0.90,
hr.consistency = 0.80,
pconsistency.threshold = 0.90,
confounders.name = NULL,
conf_force = NULL,
fs_args = list(),
sim_args = list(rand_ratio = 1, draw_treatment = TRUE),
analysis_time = 60,
cens_adjust = 0,
parallel_args = list(plan = "multisession", workers = NULL, show_message = TRUE),
details = FALSE,
verbose_n_sims = 2L,
seed = NULL,
record = c("point", "full")
) {
.fs_preserve_rng()
# ===========================================================================
# SECTION 1: INPUT VALIDATION
# ===========================================================================
if (!inherits(dgm, c("aft_dgm_flex", "aft_dgm"))) {
stop("dgm must be an object created by generate_aft_dgm_flex()")
}
if (!is.numeric(n_sims) || n_sims < 1) {
stop("n_sims must be a positive integer")
}
if (!region_var %in% names(dgm$df_super)) {
stop("region_var '", region_var, "' not found in dgm$df_super")
}
record <- match.arg(record)
t_start <- proc.time()[3]
# ===========================================================================
# SECTION 2: SET DEFAULTS
# ===========================================================================
# Default sample size from dgm
if (is.null(n_sample)) {
n_sample <- nrow(dgm$df_super)
}
# Default confounders from dgm
if (is.null(confounders.name)) {
all_vars <- names(dgm$df_super)
exclude_vars <- c("id", "treat", "tte", "event", "y_sim", "treat_sim",
"event_sim", "t_true", "c_time", "lin_pred_0", "lin_pred_1",
"loghr_po", "entrytime", "flag_harm")
# A mechanism built with a spline carries three internal columns of the
# spline variable: <var>_treat, <var>_k and <var>_k_treat. They are not
# baseline covariates. Exclude exactly these names (never a suffix match,
# which would also drop a covariate such as z_prior_treat).
spline_info <- dgm$model_params$spline_info
spline_helpers <- if (!is.null(spline_info)) {
paste0(spline_info$var, c("_treat", "_k", "_k_treat"))
} else {
character(0)
}
confounders.name <- setdiff(
all_vars[grepl("^z_|^ecog|^strat", all_vars)],
c(exclude_vars, spline_helpers)
)
}
# Default forced cuts
if (is.null(conf_force)) {
conf_force <- c("z_age <= 65", "z_bm <= 0", "z_bm <= 1", "z_bm <= 2", "z_bm <= 5")
}
# Report fs_args and sim_args if details
if (details && length(fs_args) > 0) {
message("ForestSearch passthrough arguments (fs_args):")
for (nm in names(fs_args)) {
val <- fs_args[[nm]]
if (is.list(val)) {
message(sprintf(" %s = <list of length %d>", nm, length(val)))
} else {
message(sprintf(" %s = %s", nm, paste(val, collapse = ", ")))
}
}
}
if (details && length(setdiff(names(sim_args), c("rand_ratio", "draw_treatment"))) > 0) {
message("simulate_from_dgm passthrough arguments (sim_args):")
for (nm in names(sim_args)) {
message(sprintf(" %s = %s", nm, paste(sim_args[[nm]], collapse = ", ")))
}
}
# ===========================================================================
# SECTION 3: SETUP PARALLEL PROCESSING
# ===========================================================================
plan_type <- null_or(parallel_args$plan, "multisession")
workers <- parallel_args$workers
show_message <- null_or(parallel_args$show_message, TRUE)
old_plan <- future::plan()
on.exit(future::plan(old_plan), add = TRUE)
if (plan_type == "sequential") {
future::plan(future::sequential)
} else {
if (is.null(workers)) {
workers <- max(1, parallel::detectCores() - 1)
}
if (plan_type == "multisession") {
future::plan(future::multisession, workers = workers)
} else if (plan_type == "callr") {
if (requireNamespace("future.callr", quietly = TRUE)) {
future::plan(future.callr::callr, workers = workers)
} else {
warning("future.callr not available, using multisession")
future::plan(future::multisession, workers = workers)
}
} else if (plan_type == "multicore") {
if (.Platform$OS.type == "unix") {
future::plan(future::multicore, workers = workers)
} else {
future::plan(future::multisession, workers = workers)
}
}
if (show_message) {
message(sprintf("Parallel processing: %d workers using %s backend",
workers, class(future::plan())[1]))
}
}
# ===========================================================================
# SECTION 4: RUN SIMULATIONS
# ===========================================================================
# Setup progress handler (safe for callr and other backends); the caller's
# progressr.handlers option is restored on exit
old_handlers <- getOption("progressr.handlers")
on.exit(options(progressr.handlers = old_handlers), add = TRUE)
progressr::handlers("progress")
# Internal helper bound locally: the worker expression resolves exported
# functions through the attached package only, so the record helper is
# shipped to the workers as a global.
full_record_fn <- .mrct_full_record
mr_record_fn <- .mrct_mr_record
run_foreach <- function() {
p <- progressr::progressor(along = seq_len(n_sims))
foreach::foreach(
sim = seq_len(n_sims),
.options.future = list(seed = TRUE,
packages = c("survival", "data.table", "forestsearch")),
.combine = "rbind",
.errorhandling = "pass"
) %dofuture% {
p(sprintf("Simulation %d/%d", sim, n_sims))
# -----------------------------------------------------------------------
# Simulate data from DGM
# -----------------------------------------------------------------------
# Build simulate_from_dgm arguments: sim_args defaults, overridden by
# explicit mrct_region_sims parameters
sim_call_args <- modifyList(sim_args, list(
dgm = dgm,
n = n_sample,
entry_var = if ("entrytime" %in% names(dgm$df_super)) "entrytime" else NULL,
analysis_time = analysis_time,
cens_adjust = cens_adjust,
seed = if (!is.null(seed)) seed + sim else NULL
))
dfs <- do.call(simulate_from_dgm, sim_call_args)
dfs <- data.table::as.data.table(dfs)
# -----------------------------------------------------------------------
# Split by region
# -----------------------------------------------------------------------
df_nonRegA <- dfs[get(region_var) == 0]
df_regA <- dfs[get(region_var) == 1]
n_test <- nrow(df_regA)
n_train <- nrow(df_nonRegA)
n_itt <- nrow(dfs)
# -----------------------------------------------------------------------
# Safe Cox model fitting
# -----------------------------------------------------------------------
safe_coxph <- function(formula, data) {
fit <- tryCatch(
summary(survival::coxph(formula, data = data))$conf.int,
error = function(e) NULL
)
if (!is.null(fit) && is.numeric(fit[1])) return(fit[1])
return(NA_real_)
}
# -----------------------------------------------------------------------
# Estimate HRs
# -----------------------------------------------------------------------
hr_train <- safe_coxph(
survival::Surv(y_sim, event_sim) ~ treat_sim,
df_nonRegA
)
if ("strat" %in% names(dfs)) {
hr_itt <- safe_coxph(
survival::Surv(y_sim, event_sim) ~ treat_sim + strata(strat),
dfs
)
} else {
hr_itt <- safe_coxph(
survival::Surv(y_sim, event_sim) ~ treat_sim,
dfs
)
}
hr_ittX <- safe_coxph(
stats::as.formula(
paste0("survival::Surv(y_sim, event_sim) ~ treat_sim + strata(", region_var, ")")
),
dfs
)
# -----------------------------------------------------------------------
# Initialize results
# -----------------------------------------------------------------------
hr_test <- NA_real_
any_found <- 0
sg_found <- "none"
n_sg <- n_test
hr_sg <- NA_real_
prev_sg <- 1.0
POhr_sg <- NA_real_
n_sg_train <- n_train
hr_sg_train <- NA_real_
POhr_sg_train <- NA_real_
# Testing region HR
hr_test <- safe_coxph(
survival::Surv(y_sim, event_sim) ~ treat_sim,
df_regA
)
# Determine if we should print verbose diagnostics for this simulation
# Only print for the first verbose_n_sims replicates to avoid flooding output
verbose_fs <- details && (sim <= verbose_n_sims)
# -----------------------------------------------------------------------
# Run ForestSearch if testing HR is valid
# -----------------------------------------------------------------------
if (!is.na(hr_test)) {
if ("loghr_po" %in% names(df_regA)) {
POhr_sg <- exp(mean(df_regA$loghr_po, na.rm = TRUE))
}
# Build forestsearch arguments: fs_args defaults, overridden by
# explicit mrct_region_sims parameters
fs_base_args <- list(
df.analysis = as.data.frame(df_nonRegA),
df.test = as.data.frame(df_regA),
confounders.name = confounders.name,
outcome.name = "y_sim",
treat.name = "treat_sim",
event.name = "event_sim",
id.name = if ("id" %in% names(df_nonRegA)) "id" else NULL,
potentialOutcome.name = if ("loghr_po" %in% names(df_nonRegA)) "loghr_po" else NULL,
hr.threshold = hr.threshold,
hr.consistency = hr.consistency,
pconsistency.threshold = pconsistency.threshold,
sg_focus = sg_focus,
conf_force = conf_force,
maxk = maxk,
show_candidate_summary = verbose_fs,
details = verbose_fs,
plot.sg = FALSE,
parallel_args = list(plan = "sequential")
)
# fs_args provides defaults for anything NOT in fs_base_args
# fs_base_args takes precedence (explicit mrct_region_sims params win)
fs_call_args <- modifyList(fs_args, fs_base_args)
if (verbose_fs) {
cat("\n===================================================================\n")
cat(sprintf("Simulation %d/%d: ForestSearch on training (n=%d), testing (n=%d)\n",
sim, n_sims, n_train, n_test))
cat(sprintf(" HR train = %.4f | HR test = %.4f | HR ITT = %.4f\n",
hr_train, hr_test, hr_itt))
cat(" Confounders: ", paste(confounders.name, collapse = ", "), "\n")
cat(" ForestSearch args: hr.threshold=", hr.threshold,
" hr.consistency=", hr.consistency,
" pconsistency=", pconsistency.threshold,
" sg_focus=", sg_focus,
" maxk=", maxk, "\n")
# Report fs_args passthrough values
fs_extra <- setdiff(names(fs_call_args), names(fs_base_args))
if (length(fs_extra) == 0) {
fs_extra <- intersect(names(fs_args), names(fs_call_args))
}
if (length(fs_extra) > 0) {
for (nm in fs_extra) {
val <- fs_call_args[[nm]]
if (!is.list(val)) {
cat(sprintf(" (fs_args) %s = %s\n", nm, paste(val, collapse = ", ")))
}
}
}
cat("===================================================================\n")
}
fs_call_args$quiet <- TRUE
fs_result <- tryCatch({
withCallingHandlers(
do.call(forestsearch, fs_call_args),
warning = function(w) {
if (grepl("parallel_args missing required elements", conditionMessage(w))) {
invokeRestart("muffleWarning")
}
}
)
}, error = function(e) {
if (verbose_fs) {
cat(sprintf(" *** ForestSearch ERROR in sim %d: %s\n", sim, conditionMessage(e)))
}
NULL
})
# ---------------------------------------------------------------------
# Process ForestSearch results
# ---------------------------------------------------------------------
if (!is.null(fs_result)) {
if (is.null(fs_result$sg.harm)) {
any_found <- 0
sg_found <- "none"
n_sg <- n_test
hr_sg <- hr_test
prev_sg <- 1.0
n_sg_train <- n_train
hr_sg_train <- hr_train
POhr_sg_train <- NA_real_
if (verbose_fs) {
cat(sprintf(" Result: No subgroup identified\n"))
}
} else {
any_found <- 1
sg_found <- paste(fs_result$sg.harm, collapse = " & ")
# --- Testing sample subgroup metrics ---
df_test <- fs_result$df.test
if (!is.null(df_test) && "treat.recommend" %in% names(df_test)) {
df_sg <- df_test[df_test$treat.recommend == 1, ]
n_sg <- nrow(df_sg)
prev_sg <- n_sg / n_test
hr_sg <- safe_coxph(
survival::Surv(y_sim, event_sim) ~ treat_sim,
df_sg
)
if ("loghr_po" %in% names(df_sg)) {
POhr_sg <- exp(mean(df_sg$loghr_po, na.rm = TRUE))
}
}
# --- Training sample subgroup metrics ---
df_est <- fs_result$df.est
if (!is.null(df_est) && "treat.recommend" %in% names(df_est)) {
df_sg_train <- df_est[df_est$treat.recommend == 1, ]
n_sg_train <- nrow(df_sg_train)
hr_sg_train <- safe_coxph(
survival::Surv(y_sim, event_sim) ~ treat_sim,
df_sg_train
)
if ("loghr_po" %in% names(df_sg_train)) {
POhr_sg_train <- exp(mean(df_sg_train$loghr_po, na.rm = TRUE))
}
}
if (verbose_fs) {
cat(sprintf(" Result: Subgroup FOUND = %s\n", sg_found))
cat(sprintf(" Testing: n_sg = %d (%.1f%%) | HR_sg = %.4f | PO_HR = %.4f\n",
n_sg, 100 * prev_sg, hr_sg, POhr_sg))
cat(sprintf(" Training: n_sg = %d | HR_sg = %.4f | PO_HR = %.4f\n",
n_sg_train, hr_sg_train, POhr_sg_train))
}
}
} else if (verbose_fs) {
cat(sprintf(" ForestSearch returned NULL (see error above)\n"))
}
} else {
if (verbose_fs) {
cat(sprintf(" Simulation %d: Skipped ForestSearch (hr_test is NA)\n", sim))
}
}
# -----------------------------------------------------------------------
# Return results
# -----------------------------------------------------------------------
out_point <- data.table::data.table(
sim = sim,
n_itt = n_itt,
hr_itt = hr_itt,
hr_ittX = hr_ittX,
n_train = n_train,
hr_train = hr_train,
n_test = n_test,
hr_test = hr_test,
any_found = any_found,
sg_found = sg_found,
n_sg = n_sg,
hr_sg = hr_sg,
POhr_sg = POhr_sg,
prev_sg = prev_sg,
n_sg_train = n_sg_train,
hr_sg_train = hr_sg_train,
POhr_sg_train = POhr_sg_train
)
if (record == "full") {
sg_harm <- if (any_found == 1) fs_result$sg.harm else NULL
full <- full_record_fn(dfs, region_var, sg_harm, sim, any_found)
out_point <- cbind(out_point, full$counts,
mr_record_fn(if (any_found == 1)
fs_result$mr_inference else NULL))
out_point[, .estimators := list(list(full$estimators))]
}
out_point
}
}
results <- withCallingHandlers(
progressr::with_progress(run_foreach()),
warning = function(w) {
if (grepl("was built under R version", conditionMessage(w))) {
invokeRestart("muffleWarning")
}
}
)
# ===========================================================================
# SECTION 5: POST-PROCESSING
# ===========================================================================
future::plan(future::sequential)
results <- data.table::as.data.table(results)
results[, hr_sg_null := data.table::fifelse(any_found == 0, NA_real_, hr_sg)]
if (record == "full") {
estimators <- data.table::rbindlist(results$.estimators)
results[, .estimators := NULL]
count_cols <- .mrct_count_cols()
mr_cols <- .mrct_mr_cols()
data.table::setcolorder(results, c(setdiff(names(results), c(count_cols, mr_cols)),
count_cols, mr_cols))
if (all(is.na(results$TP_region)) && nrow(results) > 0) {
message("mrct_region_sims(record = \"full\"): the simulated trials have no ",
"flag_harm column; the region_Gstar and Hstar_nonregion rows are ",
"omitted and the H-hat confusion counts are NA.")
}
data.table::setattr(results, "estimators", estimators)
}
# ===========================================================================
# SECTION 6: REPORT SUMMARY
# ===========================================================================
t_now <- proc.time()[3]
t_min <- (t_now - t_start) / 60
if (details) {
message(sprintf("\n=== Simulation Complete ==="))
message(sprintf("Total simulations: %d", n_sims))
message(sprintf("Time elapsed: %.2f minutes", t_min))
message(sprintf("Projection per 1000 sims: %.2f minutes", t_min * (1000 / n_sims)))
message(sprintf("Proportion subgroups found: %.3f", mean(results$any_found, na.rm = TRUE)))
message(sprintf("Mean HR (ITT): %.3f", mean(results$hr_itt, na.rm = TRUE)))
message(sprintf("Mean HR (Test/Region A): %.3f", mean(results$hr_test, na.rm = TRUE)))
message(sprintf("Mean HR (Subgroup): %.3f", mean(results$hr_sg_null, na.rm = TRUE)))
}
return(results)
}
# =============================================================================
# Full per-replicate record (record = "full")
# =============================================================================
#' Names of the H-hat confusion columns of the full record
#' @noRd
.mrct_count_cols <- function() {
paste0(rep(c("TP", "FP", "FN", "TN"), 2),
rep(c("_nonregion", "_region"), each = 4))
}
#' Names of the multiplier-resampling columns of the full record
#' @noRd
.mrct_mr_cols <- function() {
c("mr_ci_method", "mr_debiased_H", "mr_ij_lower_H", "mr_ij_upper_H",
"mr_field_lower_1s_H", "mr_debiased_Hc", "mr_ij_lower_Hc", "mr_ij_upper_Hc",
"mr_field_upper_1s_Hc", "mr_field_upper_1s_s_Hc", "mr_bonf_lower_H",
"mr_bonf_upper_Hc", "mr_p_hat_H", "mr_selection_rate")
}
#' The multiplier-resampling columns of one trial's full record
#'
#' @param mr `fs_result$mr_inference`, or NULL (no MR, or no declaration).
#' @return A one-row data.table with the .mrct_mr_cols() columns; NA where
#' the element is absent.
#' @noRd
.mrct_mr_record <- function(mr) {
num <- function(x) {
if (is.null(x) || length(x) != 1L || !is.numeric(x)) NA_real_ else as.numeric(x)
}
g <- function(...) {
x <- mr
for (k in c(...)) {
if (!is.list(x) || is.null(x[[k]])) return(NULL)
x <- x[[k]]
}
x
}
p_hat <- g("reselection", "p_hat")
sel <- g("selected_index")
p_hat_H <- if (!is.null(p_hat) && length(sel) == 1L && !is.na(sel) &&
sel >= 1L && sel <= length(p_hat)) p_hat[[sel]] else NULL
ci <- g("ci_method")
data.table::data.table(
mr_ci_method = if (is.character(ci) && length(ci) == 1L) ci else NA_character_,
mr_debiased_H = num(g("debiased", "est")),
mr_ij_lower_H = num(g("debiased", "lower")),
mr_ij_upper_H = num(g("debiased", "upper")),
mr_field_lower_1s_H = num(g("field", "lower_1s")),
mr_debiased_Hc = num(g("complement", "debiased", "est")),
mr_ij_lower_Hc = num(g("complement", "debiased", "lower")),
mr_ij_upper_Hc = num(g("complement", "debiased", "upper")),
mr_field_upper_1s_Hc = num(g("field", "complement", "upper_1s")),
mr_field_upper_1s_s_Hc = num(g("field", "complement", "upper_1s_s")),
mr_bonf_lower_H = num(g("field", "joint", "bonf_lower_H")),
mr_bonf_upper_Hc = num(g("field", "joint", "bonf_upper_Hc")),
mr_p_hat_H = num(p_hat_H),
mr_selection_rate = num(g("selection_rate"))
)
}
#' One estimator row of the full record on the patients `idx` of trial `s`
#'
#' The unadjusted two-sample Cox fit (errors give NA; a fit with an arm
#' without events is kept, as safe_coxph()), from one summary(), and the
#' targets AHR = exp(mean(loghr_po)) and CDE = mean(exp(theta_1)) /
#' mean(exp(theta_0)) on the same patients.
#' @noRd
.mrct_record_fit <- function(s, idx) {
d <- s[idx]
ex <- d$treat_sim == 1
f <- tryCatch(
suppressWarnings(summary(survival::coxph(
survival::Surv(y_sim, event_sim) ~ treat_sim, data = d))),
error = function(e) NULL
)
ok <- !is.null(f) && is.numeric(f$conf.int[1])
data.table::data.table(
n = nrow(d),
n_exp = sum(ex),
events_exp = sum(d$event_sim[ex]),
events_ctl = sum(d$event_sim[!ex]),
hr = if (ok) unname(f$conf.int[1, "exp(coef)"]) else NA_real_,
lo = if (ok) unname(f$conf.int[1, "lower .95"]) else NA_real_,
hi = if (ok) unname(f$conf.int[1, "upper .95"]) else NA_real_,
se_loghr = if (ok) unname(f$coefficients[1, "se(coef)"]) else NA_real_,
ahr = if ("loghr_po" %in% names(d)) exp(mean(d$loghr_po)) else NA_real_,
cde = if (all(c("theta_1", "theta_0") %in% names(d))) {
mean(exp(d$theta_1)) / mean(exp(d$theta_0))
} else NA_real_
)
}
#' The full record of one simulated trial
#'
#' @param dfs The trial (data.table), as drawn in the replicate.
#' @param region_var Region indicator column.
#' @param sg_harm The selected subgroup definition (fs_result$sg.harm), or
#' NULL when no subgroup is declared.
#' @param sim Replicate index.
#' @param any_found 0/1.
#' @return list(estimators = data.table, counts = one-row data.table)
#' @noRd
.mrct_full_record <- function(dfs, region_var, sg_harm, sim, any_found) {
reg <- dfs[[region_var]] == 1
H <- if (is.null(sg_harm)) {
rep(FALSE, nrow(dfs))
} else {
get_dfpred(as.data.frame(dfs), sg.harm = sg_harm, version = 2)$treat.recommend == 0
}
has_band <- "flag_harm" %in% names(dfs)
band <- if (has_band) dfs$flag_harm == 1 else NULL
sets <- list(itt_all = rep(TRUE, nrow(dfs)), itt_nonregion = !reg,
itt_region = reg, region_Ghat = reg & !H)
if (has_band) {
sets$region_Gstar <- reg & !band
sets$Hstar_nonregion <- !reg & band
}
est <- data.table::rbindlist(lapply(names(sets), function(k) {
cbind(data.table::data.table(sim = sim, estimator = k),
.mrct_record_fit(dfs, sets[[k]]))
}))
est[, declared := as.integer(any_found)]
cc <- function(h, b) c(sum(h & b), sum(h & !b), sum(!h & b), sum(!h & !b))
counts <- if (has_band) {
as.integer(c(cc(H[!reg], band[!reg]), cc(H[reg], band[reg])))
} else {
rep(NA_integer_, 8)
}
counts <- data.table::as.data.table(as.list(stats::setNames(counts, .mrct_count_cols())))
list(estimators = est, counts = counts)
}
# =============================================================================
# Data Validation Function
# =============================================================================
#' Validate Dataset for MRCT Simulations
#'
#' Checks that a dataset contains all required variables for MRCT simulation
#' functions and reports any issues. Required variables include outcome (tte, event),
#' treatment (treat), continuous covariates (age, bm), and factor covariates
#' (male, histology, prior_treat, regA).
#'
#' @param df.case Data frame to validate
#' @param verbose Logical. Print detailed validation results. Default: TRUE
#'
#' @return Logical. TRUE if all requirements met, FALSE otherwise (invisibly)
#'
#' @details
#' ## Required Variables
#'
#' The function checks for the following variables:
#' \itemize{
#' \item \strong{Outcome}: tte (time-to-event), event (0/1 indicator)
#' \item \strong{Treatment}: treat (0/1 indicator)
#' \item \strong{Continuous}: age, bm (biomarker)
#' \item \strong{Factor}: male (0/1), histology, prior_treat (0/1), regA (0/1)
#' }
#'
#' The function also validates variable types and value ranges.
#'
#' @examples
#' \dontrun{
#' # Check if dataset is ready for MRCT simulations
#' is_valid <- validate_mrct_data(df.case)
#'
#' if (!is_valid) {
#' stop("Please fix data issues before running simulations")
#' }
#' }
#'
#' @seealso \code{\link{create_dgm_for_mrct}} for creating DGM from validated data
#'
#' @export
validate_mrct_data <- function(df.case, verbose = TRUE) {
# Define required variables by category
required <- list(
outcome = c("tte", "event"),
treatment = "treat",
continuous = c("age", "bm"),
factor = c("male", "histology", "prior_treat", "regA")
)
all_required <- unlist(required)
# Check for missing variables
present <- names(df.case)
missing <- setdiff(all_required, present)
found <- intersect(all_required, present)
# Initialize results
is_valid <- TRUE
issues <- list()
# ---------------------------------------------------------------------------
# Check presence of variables
# ---------------------------------------------------------------------------
if (length(missing) > 0) {
is_valid <- FALSE
issues$missing <- missing
}
# ---------------------------------------------------------------------------
# Check variable types and values for found variables
# ---------------------------------------------------------------------------
type_issues <- character()
value_issues <- character()
if ("tte" %in% found) {
if (!is.numeric(df.case$tte)) {
type_issues <- c(type_issues, "tte should be numeric")
} else if (any(df.case$tte < 0, na.rm = TRUE)) {
value_issues <- c(value_issues, "tte contains negative values")
}
}
if ("event" %in% found) {
if (!all(df.case$event %in% c(0, 1, NA))) {
value_issues <- c(value_issues, "event should be binary (0/1)")
}
}
if ("treat" %in% found) {
if (!all(df.case$treat %in% c(0, 1, NA))) {
value_issues <- c(value_issues, "treat should be binary (0/1)")
}
}
if ("age" %in% found) {
if (!is.numeric(df.case$age)) {
type_issues <- c(type_issues, "age should be numeric")
}
}
if ("bm" %in% found) {
if (!is.numeric(df.case$bm)) {
type_issues <- c(type_issues, "bm (biomarker) should be numeric")
}
}
if ("male" %in% found) {
if (!all(df.case$male %in% c(0, 1, NA))) {
value_issues <- c(value_issues, "male should be binary (0/1)")
}
}
if ("regA" %in% found) {
if (!all(df.case$regA %in% c(0, 1, NA))) {
value_issues <- c(value_issues, "regA should be binary (0/1)")
}
}
if (length(type_issues) > 0) {
is_valid <- FALSE
issues$type_issues <- type_issues
}
if (length(value_issues) > 0) {
is_valid <- FALSE
issues$value_issues <- value_issues
}
# ---------------------------------------------------------------------------
# Report results
# ---------------------------------------------------------------------------
if (verbose) {
cat("=== MRCT Data Validation ===\n\n")
cat("Dataset:", deparse(substitute(df.case)), "\n")
cat("Dimensions:", nrow(df.case), "rows x", ncol(df.case), "columns\n\n")
# Report by category
for (cat_name in names(required)) {
cat_vars <- required[[cat_name]]
cat_found <- intersect(cat_vars, found)
cat_missing <- setdiff(cat_vars, found)
cat(sprintf("%-12s: ", tools::toTitleCase(cat_name)))
if (length(cat_missing) == 0) {
cat("All present (", paste(cat_found, collapse = ", "), ")\n", sep = "")
} else {
cat("Missing: ", paste(cat_missing, collapse = ", "), "\n", sep = "")
}
}
cat("\n")
# Report issues
if (length(type_issues) > 0) {
cat("Type issues:\n")
for (issue in type_issues) {
cat(" - ", issue, "\n", sep = "")
}
}
if (length(value_issues) > 0) {
cat("Value issues:\n")
for (issue in value_issues) {
cat(" - ", issue, "\n", sep = "")
}
}
# Summary
cat("\n")
if (is_valid) {
cat("Dataset is valid for MRCT simulations\n")
} else {
cat("Dataset requires fixes before use\n")
}
# Additional info
if (is_valid && "regA" %in% found) {
cat("\nRegion distribution:\n")
cat(" Region A (test): ", sum(df.case$regA == 1, na.rm = TRUE),
" (", round(100 * mean(df.case$regA == 1, na.rm = TRUE), 1), "%)\n", sep = "")
cat(" Non-Region A (train): ", sum(df.case$regA == 0, na.rm = TRUE),
" (", round(100 * mean(df.case$regA == 0, na.rm = TRUE), 1), "%)\n", sep = "")
}
}
invisible(is_valid)
}
# =============================================================================
# DGM Creation Wrapper for MRCT
# =============================================================================
#' Create Data Generating Mechanism for MRCT Simulations
#'
#' Wrapper function to create a data generating mechanism (DGM) for MRCT
#' simulation scenarios using \code{\link{generate_aft_dgm_flex}}.
#'
#' @param df_case Data frame containing case study data
#' @param model_type Character. Either "alt" (alternative hypothesis with
#' heterogeneous treatment effects) or "null" (uniform treatment effect)
#' @param log_hrs Numeric vector. Log hazard ratios for spline specification.
#' If NULL, defaults are used based on model_type
#' @param confounder_var Character. Name of a confounder variable to include with
#' a forced prognostic effect. Default: NULL (no forced effect)
#' @param confounder_effect Numeric. Log hazard ratio for confounder_var effect.
#' Only used if confounder_var is specified
#' @param include_regA Logical. Include regA as a factor in the model.
#' Default: TRUE
#' @param verbose Logical. Print detailed output. Default: FALSE
#'
#' @return An object of class "aft_dgm_flex" for use with
#' \code{\link{simulate_from_dgm}} and \code{\link{mrct_region_sims}}
#'
#' @details
#' ## Model Types
#'
#' \describe{
#' \item{alt}{Alternative hypothesis: Treatment effect varies by biomarker
#' level (heterogeneous treatment effect). Default log_hrs create HR
#' ranging from 2.0 (harm) to 0.5 (benefit) across biomarker range}
#' \item{null}{Null hypothesis: Uniform treatment effect regardless of
#' biomarker level. Default log_hrs = log(0.7) uniformly}
#' }
#'
#' ## Confounder Effects
#'
#' By default, NO prognostic confounder effect is forced. The confounder_var
#' and confounder_effect parameters allow optionally specifying ANY baseline
#' covariate to have a fixed prognostic effect in the outcome model.
#'
#' The regA variable (region indicator) is included as a factor by default
#' but without a forced effect - its coefficient is estimated from data.
#'
#' @examples
#' \dontrun{
#' # Prepare data
#' df_case <- read.csv("data/dfsynthetic.csv")
#' df_case$regA <- df_case$region_asia
#'
#' # Alternative hypothesis (heterogeneous treatment effect)
#' dgm_alt <- create_dgm_for_mrct(
#' df_case = df_case,
#' model_type = "alt",
#' log_hrs = log(c(3, 1.25, 0.50)),
#' verbose = TRUE
#' )
#'
#' # Null hypothesis (uniform effect)
#' dgm_null <- create_dgm_for_mrct(
#' df_case = df_case,
#' model_type = "null",
#' verbose = TRUE
#' )
#'
#' # With forced confounder effect
#' dgm_conf <- create_dgm_for_mrct(
#' df_case = df_case,
#' model_type = "alt",
#' confounder_var = "prior_treat",
#' confounder_effect = log(1.5),
#' verbose = TRUE
#' )
#' }
#'
#' @seealso
#' \code{\link{generate_aft_dgm_flex}} for underlying DGM creation
#' \code{\link{mrct_region_sims}} for running simulations with the DGM
#'
#' @export
create_dgm_for_mrct <- function(
df_case,
model_type = c("alt", "null"),
log_hrs = NULL,
confounder_var = NULL,
confounder_effect = NULL,
include_regA = TRUE,
verbose = FALSE
) {
model_type <- match.arg(model_type)
# ---------------------------------------------------------------------------
# Set default log hazard ratios based on model type
# ---------------------------------------------------------------------------
if (is.null(log_hrs)) {
if (model_type == "alt") {
# HTE: HR varies from 2 (harmful) to 0.5 (protective) across biomarker
log_hrs <- log(c(2, 1.25, 0.5))
} else {
# Null: uniform HR = 0.7
log_hrs <- log(c(0.7, 0.7, 0.7))
}
}
# ---------------------------------------------------------------------------
# Build factor_vars list
# ---------------------------------------------------------------------------
factor_vars <- c("male", "histology", "prior_treat")
if (include_regA) {
factor_vars <- c(factor_vars, "regA")
}
# ---------------------------------------------------------------------------
# Build set_beta_spec for optional confounder effect
# ---------------------------------------------------------------------------
set_beta_spec <- list(set_var = NULL, beta_var = NULL)
if (!is.null(confounder_var) && !is.null(confounder_effect)) {
# Add z_ prefix if not already present
z_confounder_var <- if (grepl("^z_", confounder_var)) {
confounder_var
} else {
paste0("z_", confounder_var)
}
set_beta_spec <- list(
set_var = z_confounder_var,
beta_var = confounder_effect
)
if (verbose) {
message(sprintf("Forcing confounder effect: %s = %.4f (HR = %.3f)",
z_confounder_var, confounder_effect, exp(confounder_effect)))
}
}
# ---------------------------------------------------------------------------
# Generate DGM
# ---------------------------------------------------------------------------
dgm <- generate_aft_dgm_flex(
data = df_case,
continuous_vars = c("age", "bm"),
factor_vars = factor_vars,
set_beta_spec = set_beta_spec,
continuous_vars_cens = c("age"),
factor_vars_cens = c("prior_treat"),
cens_type = "weibull",
outcome_var = "tte",
event_var = "event",
treatment_var = "treat",
subgroup_vars = NULL,
subgroup_cuts = NULL,
model = model_type,
spline_spec = list(
var = "z_bm",
knot = 5,
zeta = 10,
log_hrs = log_hrs
),
k_inter = 0.0,
verbose = verbose,
standardize = FALSE
)
return(dgm)
}
# =============================================================================
# Visualization Function
# =============================================================================
#' Violin/Boxplot Visualization of HR Estimates
#'
#' Creates violin plots with embedded boxplots showing the distribution of
#' hazard ratio estimates across simulations for different analysis populations.
#' Supports symmetric trimming to handle extreme values that can distort
#' the display when small subgroups produce very large HR estimates.
#'
#' @param df data.frame or data.table. Simulation results from
#' \code{\link{mrct_region_sims}}
#' @param label_training Character. Label for training data estimates.
#' Default: "Training"
#' @param label_testing Character. Label for testing data estimates.
#' Default: "Testing"
#' @param label_itt Character. Label for ITT estimates.
#' Default: "ITT (stratified)"
#' @param label_sg Character. Label for subgroup estimates.
#' Default: "Testing (subgroup)"
#' @param trim_fraction Numeric or NULL. Fraction of observations to trim
#' from each tail (e.g., 0.01 trims the lowest 1\% and highest 1\%).
#' When non-NULL, trimmed means and SDs are computed for each group,
#' extreme observations are flagged, and the y-axis is clipped to the
#' trimmed data range. Set to NULL (default) for no trimming (backward
#' compatible).
#' @param ylim Numeric vector of length 2 or NULL. Explicit y-axis limits
#' as \code{c(lower, upper)}. Overrides automatic limits from trimming.
#' Default: NULL (auto).
#' @param show_summary Logical. Annotate each violin with mean (SD) below
#' the x-axis labels. When trimming is active, displays trimmed
#' statistics. Default: \code{NULL}, which resolves to \code{TRUE} when
#' \code{trim_fraction} is non-NULL and \code{FALSE} otherwise.
#' @param title Character. Plot title. Default: "Distribution of HR
#' Estimates Across Simulations".
#' @param subtitle Character or NULL. Plot subtitle. When trimming is
#' active and subtitle is NULL, an auto-generated note indicating the
#' trim fraction and number of flagged observations is shown.
#' Default: NULL.
#'
#' @return List with components:
#' \describe{
#' \item{dfPlot_estimates}{data.table formatted for plotting, with a
#' \code{trimmed} logical column when trimming is active}
#' \item{plot_estimates}{ggplot2 object}
#' \item{trim_info}{List of per-group trimming diagnostics (NULL when
#' no trimming). Each element contains: \code{n_total}, \code{n_trimmed},
#' \code{n_flagged}, \code{raw_mean}, \code{raw_sd}, \code{trimmed_mean},
#' \code{trimmed_sd}, \code{lower_bound}, \code{upper_bound}.}
#' }
#'
#' @examples
#' \dontrun{
#' # Default (no trimming) -- backward compatible
#' plot_results <- SGplot_estimates(
#' results_alt,
#' label_training = "Non-Region A, ITT",
#' label_itt = "Overall, ITT",
#' label_testing = "Region A, ITT",
#' label_sg = "Region A, identified subgroup"
#' )
#' print(plot_results$plot_estimates)
#'
#' # With 1% symmetric trimming
#' plot_results <- SGplot_estimates(
#' results_alt,
#' label_training = "Non-AP, ITT",
#' label_itt = "Overall, ITT",
#' label_testing = "AP, ITT",
#' label_sg = "AP, identified subgroup",
#' trim_fraction = 0.01
#' )
#' print(plot_results$plot_estimates)
#' # Inspect trimming diagnostics
#' print(plot_results$trim_info)
#'
#' # With explicit y-axis limits
#' plot_results <- SGplot_estimates(
#' results_alt,
#' trim_fraction = 0.01,
#' ylim = c(0.2, 3.0)
#' )
#' }
#'
#' @seealso \code{\link{mrct_region_sims}} for generating simulation results,
#' \code{\link{summaryout_mrct}} for tabular summaries with trimming
#'
#' @importFrom data.table data.table rbindlist :=
#' @importFrom stats quantile sd
#' @importFrom ggplot2 ggplot aes geom_violin geom_boxplot geom_hline scale_fill_brewer labs theme_minimal theme element_text coord_cartesian scale_x_discrete
#' @export
SGplot_estimates <- function(
df,
label_training = "Training",
label_testing = "Testing",
label_itt = "ITT (stratified)",
label_sg = "Testing (subgroup)",
trim_fraction = NULL,
ylim = NULL,
show_summary = NULL,
title = "Distribution of HR Estimates Across Simulations",
subtitle = NULL
) {
if (!requireNamespace("ggplot2", quietly = TRUE)) {
stop("Package 'ggplot2' required for plotting. Please install it.")
}
# Resolve show_summary default
if (is.null(show_summary)) {
show_summary <- !is.null(trim_fraction)
}
# ---------------------------------------------------------------------------
# Prepare data for plotting
# ---------------------------------------------------------------------------
df_itt <- data.table::data.table(est = df$hr_itt, analysis = label_itt)
df_training <- data.table::data.table(est = df$hr_train, analysis = label_training)
df_testing <- data.table::data.table(est = df$hr_test, analysis = label_testing)
df_sg <- data.table::data.table(est = df$hr_sg, analysis = label_sg)
hr_estimates <- data.table::rbindlist(
list(df_itt, df_training, df_testing, df_sg)
)
# Set factor order
est_order <- c(label_itt, label_training, label_testing, label_sg)
hr_estimates[, analysis := factor(analysis, levels = est_order)]
# ---------------------------------------------------------------------------
# Trimming (when requested)
# ---------------------------------------------------------------------------
trim_info <- NULL
auto_ylim <- NULL
if (!is.null(trim_fraction)) {
if (trim_fraction <= 0 || trim_fraction >= 0.5) {
stop("trim_fraction must be between 0 (exclusive) and 0.5 (exclusive).")
}
hr_estimates[, trimmed := FALSE]
trim_info <- list()
total_flagged <- 0L
for (grp in est_order) {
idx <- which(hr_estimates$analysis == grp)
vals <- hr_estimates$est[idx]
vals_clean <- vals[!is.na(vals)]
if (length(vals_clean) < 5) {
trim_info[[grp]] <- list(
n_total = length(vals), n_trimmed = NA_integer_,
n_flagged = 0L, raw_mean = mean(vals_clean),
raw_sd = stats::sd(vals_clean),
trimmed_mean = NA_real_, trimmed_sd = NA_real_,
lower_bound = NA_real_, upper_bound = NA_real_
)
next
}
lo <- stats::quantile(vals_clean, trim_fraction, na.rm = TRUE)
hi <- stats::quantile(vals_clean, 1 - trim_fraction, na.rm = TRUE)
# Flag observations outside trim bounds
is_extreme <- !is.na(hr_estimates$est[idx]) &
(hr_estimates$est[idx] < lo | hr_estimates$est[idx] > hi)
hr_estimates[idx[is_extreme], trimmed := TRUE]
vals_trimmed <- vals_clean[vals_clean >= lo & vals_clean <= hi]
n_flagged <- sum(is_extreme)
total_flagged <- total_flagged + n_flagged
trim_info[[grp]] <- list(
n_total = length(vals),
n_trimmed = length(vals_trimmed),
n_flagged = n_flagged,
raw_mean = mean(vals_clean),
raw_sd = stats::sd(vals_clean),
trimmed_mean = mean(vals_trimmed),
trimmed_sd = stats::sd(vals_trimmed),
lower_bound = as.numeric(lo),
upper_bound = as.numeric(hi)
)
}
# Auto y-axis limits from trimmed range (with 5% padding)
all_bounds <- unlist(lapply(trim_info, function(x) c(x$lower_bound, x$upper_bound)))
all_bounds <- all_bounds[!is.na(all_bounds)]
if (length(all_bounds) > 0) {
rng <- range(all_bounds)
pad <- 0.05 * diff(rng)
auto_ylim <- c(rng[1] - pad, rng[2] + pad)
}
# Auto subtitle
if (is.null(subtitle)) {
subtitle <- sprintf(
"Trimmed mean/SD shown (%.0f%% symmetric trim; %d observations flagged)",
100 * trim_fraction, total_flagged
)
}
}
# ---------------------------------------------------------------------------
# Build x-axis labels with summary annotations
# ---------------------------------------------------------------------------
if (show_summary) {
annotated_labels <- vapply(est_order, function(grp) {
vals <- hr_estimates$est[hr_estimates$analysis == grp]
vals <- vals[!is.na(vals)]
if (!is.null(trim_info) && !is.null(trim_info[[grp]])) {
ti <- trim_info[[grp]]
if (!is.na(ti$trimmed_mean)) {
return(sprintf(
"%s\nMean*: %.3f (%.3f)",
grp, ti$trimmed_mean, ti$trimmed_sd
))
}
}
# Raw mean/SD (no trimming or insufficient data for trimming)
if (length(vals) > 1) {
return(sprintf(
"%s\nMean: %.3f (%.3f)",
grp, mean(vals), stats::sd(vals)
))
}
grp
}, character(1))
names(annotated_labels) <- est_order
}
# ---------------------------------------------------------------------------
# Plotting data: use only non-flagged for violins when trimming
# ---------------------------------------------------------------------------
if (!is.null(trim_fraction)) {
plot_data <- hr_estimates[trimmed == FALSE]
} else {
plot_data <- hr_estimates
}
# ---------------------------------------------------------------------------
# Create plot
# ---------------------------------------------------------------------------
p <- ggplot2::ggplot(
plot_data,
ggplot2::aes(x = analysis, y = est, fill = analysis)
) +
ggplot2::geom_violin(trim = FALSE, alpha = 0.7) +
ggplot2::geom_boxplot(width = 0.15, fill = "white", alpha = 0.8) +
ggplot2::geom_hline(
yintercept = 1.0, linetype = "dashed", color = "red", alpha = 0.7
) +
ggplot2::scale_fill_brewer(palette = "Set2") +
ggplot2::labs(
x = "Analysis Population",
y = "Hazard Ratio Estimate",
title = title,
subtitle = subtitle
) +
ggplot2::theme_minimal(base_size = 12) +
ggplot2::theme(
legend.position = "none",
axis.text.x = ggplot2::element_text(angle = 15, hjust = 1),
panel.grid.minor = ggplot2::element_blank()
)
# Annotated x-axis labels
if (show_summary) {
p <- p + ggplot2::scale_x_discrete(labels = annotated_labels)
}
# Y-axis limits: explicit > auto-trim > none
effective_ylim <- if (!is.null(ylim)) ylim else auto_ylim
if (!is.null(effective_ylim)) {
p <- p + ggplot2::coord_cartesian(ylim = effective_ylim)
}
return(list(
dfPlot_estimates = hr_estimates,
plot_estimates = p,
trim_info = trim_info
))
}
# =============================================================================
# Helper Function: Null Coalescing Operator
# =============================================================================
# Null Coalescing Operator (internal helper, no documentation generated)
# Returns the left-hand side if not NULL, otherwise returns the right-hand side.
# @noRd
null_or <- function(x, y) {
if (is.null(x)) y else x
}
#' Summary Tables for MRCT Simulation Results
#'
#' Creates summary tables from MRCT simulation results using the gt package.
#' Summarizes hazard ratio estimates, subgroup identification rates, and
#' classification of identified subgroups. Optionally displays two scenarios
#' (e.g., alternative and null hypotheses) side by side.
#'
#' @param pop_summary List. Population summary from large sample approximation
#' (optional). Default: NULL
#' @param mrct_sims data.table. Simulation results from
#' \code{\link{mrct_region_sims}} (first / primary scenario).
#' @param mrct_sims_null data.table. Optional second set of simulation results
#' (e.g., null hypothesis). When supplied, the table displays two value
#' columns side by side. Default: NULL (single-scenario table).
#' @param scenario_labels Character vector of length 2. Column headers for the
#' two scenarios. Only used when \code{mrct_sims_null} is supplied.
#' Default: \code{c("Alternative", "Null")}.
#' @param pop_summary_null List. Population summary for the null scenario
#' (optional). Default: NULL
#' @param sg_type Integer. Type of subgroup summary: 1 = basic summary
#' (found, biomarker, age); 2 = extended summary (all subgroup types).
#' Default: 1
#' @param tab_caption Character. Caption for the output table.
#' Default: "Identified subgroups and estimation summaries"
#' @param digits Integer. Number of decimal places for numeric summaries.
#' Default: 3
#' @param trim_threshold Numeric. When the raw mean of a metric exceeds this
#' value in absolute terms, the summary switches to a symmetrically trimmed
#' mean and SD (excluding the lower and upper \code{trim_fraction} of
#' observations). Trimmed values are marked with \code{*} and a footnote is
#' added to the table. Set to \code{NULL} to disable trimming entirely.
#' Default: 1000.
#' @param trim_fraction Numeric between 0 and 0.5. Fraction of observations to
#' trim from each tail when trimming is triggered. Default: 0.01 (1 percent
#' from each tail, i.e., the central 98 percent of values).
#' @param table_width Numeric. Total table width in pixels. Column widths are
#' allocated proportionally. Increase for HTML/wide displays (e.g., 750),
#' decrease for beamer slides (e.g., 550). Default: 600.
#' @param font_size Numeric. Base font size in pixels. Title is
#' \code{font_size + 2}, subtitle matches base. Reduce for beamer
#' (e.g., 9 or 10). Default: 11.
#' @param showtable Logical. Print the table. Default: TRUE
#'
#' @return List with components:
#' \describe{
#' \item{res}{List of summary statistics from population. When
#' dual-scenario, contains \code{res_alt} and \code{res_null}.}
#' \item{out_table}{Formatted gt table object, or data.frame if gt
#' is unavailable.}
#' \item{data}{Processed mrct_sims data.table with derived variables.
#' When dual-scenario, also contains \code{data_null}.}
#' \item{summary_df}{Data frame of computed summary statistics.}
#' }
#'
#' @examples
#' \dontrun{
#' # Single scenario (backward-compatible)
#' summaryout_mrct(
#' mrct_sims = results_alt,
#' tab_caption = "H1: Heterogeneous treatment effect"
#' )
#'
#' # Dual scenario: alternative vs null side-by-side
#' summaryout_mrct(
#' mrct_sims = results_alt,
#' mrct_sims_null = results_null,
#' scenario_labels = c("Alternative (HTE)", "Null (uniform)"),
#' tab_caption = "Operating characteristics: Alternative vs Null"
#' )
#'
#' # Custom trimming: 2% from each tail when mean > 500
#' summaryout_mrct(
#' mrct_sims = results_alt,
#' mrct_sims_null = results_null,
#' trim_threshold = 500,
#' trim_fraction = 0.02
#' )
#' }
#'
#' @seealso \code{\link{mrct_region_sims}} for generating simulation results
#'
#' @importFrom data.table as.data.table copy fifelse :=
#' @importFrom stats median sd quantile
#' @importFrom gt gt tab_header tab_spanner tab_style cell_text cell_borders cells_body tab_source_note cols_label cols_width tab_options px md
#' @export
summaryout_mrct <- function(
pop_summary = NULL,
mrct_sims,
mrct_sims_null = NULL,
scenario_labels = c("Alternative", "Null"),
pop_summary_null = NULL,
sg_type = 1,
tab_caption = "Identified subgroups and estimation summaries",
digits = 3,
trim_threshold = 1000,
trim_fraction = 0.01,
table_width = 600,
font_size = 11,
showtable = TRUE
) {
dual <- !is.null(mrct_sims_null)
# ---------------------------------------------------------------------------
# Column width allocation (proportional to table_width)
# Dual: Category 20% | Metric 33% | Alt 23.5% | Null 23.5%
# Single: Category 25% | Metric 43% | Value 32%
# ---------------------------------------------------------------------------
if (dual) {
w_cat <- round(table_width * 0.200)
w_met <- round(table_width * 0.333)
w_val <- round((table_width - w_cat - w_met) / 2)
w_val2 <- w_val
} else {
w_cat <- round(table_width * 0.255)
w_met <- round(table_width * 0.425)
w_val <- table_width - w_cat - w_met
w_val2 <- w_val
}
# Track whether any trimming occurred (for footnote).
# Uses an environment so the fmt_mean_sd closure can update the flag
# without <<-, which CRAN flags as a global-assignment concern.
trim_env <- new.env(parent = emptyenv())
trim_env$trimmed_any <- FALSE
# ===========================================================================
# Helper formatters (shared across scenarios)
# ===========================================================================
fmt_mean_sd <- function(x, d = digits) {
x <- x[!is.na(x)]
if (length(x) == 0) return("--")
raw_mean <- mean(x)
if (!is.null(trim_threshold) && abs(raw_mean) > trim_threshold) {
# Apply symmetric trimming
lo <- stats::quantile(x, trim_fraction)
hi <- stats::quantile(x, 1 - trim_fraction)
x_trim <- x[x >= lo & x <= hi]
if (length(x_trim) < 3) return("--")
trim_env$trimmed_any <- TRUE
sprintf("%.*f (%.*f)*", d, mean(x_trim), d, stats::sd(x_trim))
} else {
sprintf("%.*f (%.*f)", d, mean(x), d, stats::sd(x))
}
}
fmt_median_iqr <- function(x, d = digits) {
x <- x[!is.na(x)]
if (length(x) == 0) return("--")
q <- stats::quantile(x, c(0.25, 0.5, 0.75))
sprintf("%.*f [%.*f, %.*f]", d, q[2], d, q[1], d, q[3])
}
fmt_prop <- function(x) {
sprintf("%.1f%%", 100 * mean(x, na.rm = TRUE))
}
fmt_cat <- function(x, level) {
n <- sum(x == level, na.rm = TRUE)
pct <- 100 * n / length(x)
sprintf("%d (%.1f%%)", n, pct)
}
# ===========================================================================
# Process population summary
# ===========================================================================
process_pop_summary <- function(ps) {
res <- list()
if (!is.null(ps)) {
res$ahr_true <- round(null_or(ps$AHR, NA), 4)
res$ahr_unadj <- round(null_or(ps$ITT_unadj, NA), 4)
res$ahr_sR <- round(null_or(ps$ITT_sR, NA), 4)
res$ahr_sRw <- round(null_or(ps$ITT_sRw, NA), 4)
res$ahr_w1 <- round(null_or(ps$W_1, NA), 4)
if (!is.na(res$ahr_true) && res$ahr_true != 0) {
res$bias_unadj <- round(
100 * (res$ahr_unadj - res$ahr_true) / res$ahr_true, 1
)
res$bias_sR <- round(
100 * (res$ahr_sR - res$ahr_true) / res$ahr_true, 1
)
res$bias_sRw <- round(
100 * (res$ahr_sRw - res$ahr_true) / res$ahr_true, 1
)
if (!is.na(res$ahr_w1)) {
res$bias_w1 <- round(
100 * (res$ahr_w1 - res$ahr_true) / res$ahr_true, 1
)
}
}
}
res
}
# ===========================================================================
# Prepare a single scenario's data.table (derived vars + classification)
# ===========================================================================
prepare_scenario <- function(dt) {
dt <- data.table::as.data.table(data.table::copy(dt))
# Derived variables
dt[, `:=`(
regAflag = data.table::fifelse(
hr_test > 0.9, "RegA > 0.9", "RegA <= 0.9"
),
sg_le85 = data.table::fifelse(
hr_sg <= 0.85, "RegA(sg) <= 0.85", "RegA(sg) > 0.85"
),
regAflag2 = data.table::fifelse(
hr_test > 0.9 & hr_sg <= 0.85,
"RegA > 0.9 & RegA(sg) <= 0.85", "Not"
),
regAflag3 = data.table::fifelse(
hr_test > 0.9 & hr_sg <= 0.80,
"RegA > 0.9 & RegA(sg) <= 0.80", "Not"
),
found = as.factor(any_found)
)]
# Classify subgroups by factor type
dt[, `:=`(
sg_biomarker = data.table::fifelse(
grepl("bm|biomarker", sg_found, ignore.case = TRUE),
"biomarker",
data.table::fifelse(sg_found != "none", "other", "none")
),
sg_age = data.table::fifelse(
grepl("age", sg_found, ignore.case = TRUE), "age", "not_age"
)
)]
# Extended classification for sg_type == 2
if (sg_type == 2) {
dt[, `:=`(
sg_male = data.table::fifelse(
grepl("male|sex", sg_found, ignore.case = TRUE), "sex", "not_sex"
),
sg_ecog = data.table::fifelse(
grepl("ecog", sg_found, ignore.case = TRUE), "ecog", "not_ecog"
),
sg_histology = data.table::fifelse(
grepl("histol", sg_found, ignore.case = TRUE),
"histology", "not_histology"
),
sg_CTregimen = data.table::fifelse(
grepl("CT|regimen", sg_found, ignore.case = TRUE),
"CT_regimen", "not_CT_regimen"
),
sg_region = data.table::fifelse(
grepl("reg|region", sg_found, ignore.case = TRUE),
"region", "not_region"
),
sg_surgery = data.table::fifelse(
grepl("surg", sg_found, ignore.case = TRUE),
"surgery", "not_surgery"
),
sg_prior_treat = data.table::fifelse(
grepl("prior", sg_found, ignore.case = TRUE),
"prior_treat", "not_prior_treat"
)
)]
}
dt
}
# ===========================================================================
# Build summary value vector for one scenario
# ===========================================================================
build_values <- function(dt) {
vals <- c(
# HR Estimates
fmt_mean_sd(dt$hr_itt),
fmt_mean_sd(dt$hr_ittX),
fmt_mean_sd(dt$hr_train),
fmt_mean_sd(dt$hr_test),
fmt_mean_sd(dt$hr_sg),
fmt_mean_sd(dt$POhr_sg),
# Subgroup Identification
fmt_prop(dt$any_found),
fmt_mean_sd(dt$prev_sg[dt$any_found == 1]),
# Region A Classification
fmt_cat(dt$regAflag, "RegA > 0.9"),
fmt_cat(dt$sg_le85, "RegA(sg) <= 0.85"),
fmt_cat(dt$regAflag2, "RegA > 0.9 & RegA(sg) <= 0.85"),
fmt_cat(dt$regAflag3, "RegA > 0.9 & RegA(sg) <= 0.80"),
# Subgroup Classification (basic)
fmt_cat(dt$sg_biomarker, "biomarker"),
fmt_cat(dt$sg_age, "age")
)
# Extended classification for sg_type == 2
if (sg_type == 2) {
vals <- c(vals,
fmt_cat(dt$sg_male, "sex"),
fmt_cat(dt$sg_ecog, "ecog"),
fmt_cat(dt$sg_histology, "histology"),
fmt_cat(dt$sg_CTregimen, "CT_regimen"),
fmt_cat(dt$sg_region, "region"),
fmt_cat(dt$sg_surgery, "surgery"),
fmt_cat(dt$sg_prior_treat, "prior_treat")
)
}
vals
}
# ===========================================================================
# Build the metric labels (shared across scenarios)
# ===========================================================================
build_labels <- function() {
categories <- c(
"HR Estimates", rep("", 5),
"Subgroup Identification", "",
"Region A Classification", rep("", 3),
"Subgroup Classification", ""
)
metrics <- c(
"HR ITT",
"HR ITT (stratified by region)",
"HR Training (non-Region A)",
"HR Testing (Region A)",
"HR Subgroup",
"PO HR Subgroup",
"Subgroup Found",
"Prevalence (when found)",
"RegA HR > 0.9",
"RegA(sg) HR <= 0.85",
"RegA > 0.9 & RegA(sg) <= 0.85",
"RegA > 0.9 & RegA(sg) <= 0.80",
"Biomarker",
"Age"
)
if (sg_type == 2) {
categories <- c(categories, rep("", 7))
metrics <- c(metrics,
"Sex", "ECOG", "Histology", "CT Regimen",
"Region", "Surgery", "Prior Treatment"
)
}
data.frame(Category = categories, Metric = metrics,
stringsAsFactors = FALSE)
}
# ===========================================================================
# MAIN LOGIC
# ===========================================================================
# Process population summaries
res_alt <- process_pop_summary(pop_summary)
res_null <- if (dual) process_pop_summary(pop_summary_null) else list()
# Prepare scenario data
mrct_alt <- prepare_scenario(mrct_sims)
mrct_null_dt <- if (dual) prepare_scenario(mrct_sims_null) else NULL
# Build labels
labels_df <- build_labels()
# Build value columns
vals_alt <- build_values(mrct_alt)
if (dual) {
vals_null <- build_values(mrct_null_dt)
n_sims_alt <- nrow(mrct_alt)
n_sims_null <- nrow(mrct_null_dt)
summary_df <- data.frame(
Category = labels_df$Category,
Metric = labels_df$Metric,
Value_Alt = vals_alt,
Value_Null = vals_null,
stringsAsFactors = FALSE
)
} else {
n_sims <- nrow(mrct_alt)
summary_df <- data.frame(
Category = labels_df$Category,
Metric = labels_df$Metric,
Value = vals_alt,
stringsAsFactors = FALSE
)
}
# ===========================================================================
# Create gt table
# ===========================================================================
if (!requireNamespace("gt", quietly = TRUE)) {
warning("Package 'gt' not available. ",
"Returning data frame instead of formatted table.")
if (showtable) print(summary_df)
res_out <- if (dual) {
list(res_alt = res_alt, res_null = res_null)
} else {
res_alt
}
data_out <- if (dual) {
list(data_alt = mrct_alt, data_null = mrct_null_dt)
} else {
mrct_alt
}
return(list(
res = res_out, out_table = summary_df,
data = data_out, summary_df = summary_df
))
}
# ---------------------------------------------------------------------------
# Build gt table
# ---------------------------------------------------------------------------
# Pre-compute column widths as named list (applied outside pipe)
# Pipe chains capture formula environments where local vars can be invisible
out_table <- gt::gt(summary_df)
if (dual) {
# --- Dual-scenario table ---
subtitle_text <- sprintf(
"%s: %d sims | %s: %d sims",
scenario_labels[1], n_sims_alt,
scenario_labels[2], n_sims_null
)
out_table <- out_table |>
gt::tab_header(
title = tab_caption,
subtitle = subtitle_text
) |>
gt::cols_label(
Category = "Category",
Metric = "Metric",
Value_Alt = scenario_labels[1],
Value_Null = scenario_labels[2]
) |>
gt::tab_spanner(
label = gt::md("**Scenario**"),
columns = c("Value_Alt", "Value_Null")
)
out_table <- eval(bquote(gt::cols_width(
out_table,
Category ~ gt::px(.(w_cat)),
Metric ~ gt::px(.(w_met)),
Value_Alt ~ gt::px(.(w_val)),
Value_Null ~ gt::px(.(w_val2))
)))
} else {
# --- Single-scenario table (backward-compatible) ---
out_table <- out_table |>
gt::tab_header(
title = tab_caption,
subtitle = sprintf("Based on %d simulations", n_sims)
) |>
gt::cols_label(
Category = "Category",
Metric = "Metric",
Value = "Mean (SD) / N (%)"
)
out_table <- eval(bquote(gt::cols_width(
out_table,
Category ~ gt::px(.(w_cat)),
Metric ~ gt::px(.(w_met)),
Value ~ gt::px(.(w_val))
)))
}
# --- Shared styling ---
out_table <- out_table |>
gt::tab_style(
style = gt::cell_text(weight = "bold"),
locations = gt::cells_body(
columns = "Category",
rows = Category != ""
)
) |>
gt::tab_style(
style = gt::cell_borders(
sides = "bottom",
color = "#D3D3D3",
weight = gt::px(1)
),
locations = gt::cells_body()
) |>
gt::tab_options(
table.font.size = gt::px(font_size),
table.align = "center",
heading.title.font.size = gt::px(font_size + 2),
heading.subtitle.font.size = gt::px(font_size),
column_labels.font.weight = "bold"
)
# --- Population summary footnotes ---
if (!is.null(pop_summary) && length(res_alt) > 0) {
if (dual) {
pop_note <- sprintf(
"Population AHR -- %s: %.4f | %s: %.4f",
scenario_labels[1], null_or(res_alt$ahr_true, NA),
scenario_labels[2], null_or(res_null$ahr_true, NA)
)
} else {
pop_note <- sprintf("Population AHR: %.4f", null_or(res_alt$ahr_true, NA))
}
out_table <- gt::tab_source_note(out_table, source_note = pop_note)
}
# --- Trimming footnote ---
if (trim_env$trimmed_any) {
pct <- round(trim_fraction * 100)
trim_note <- sprintf(
"* Trimmed mean/SD: lower and upper %d%% excluded (raw mean exceeded %s)",
pct, format(trim_threshold, big.mark = ",")
)
out_table <- gt::tab_source_note(out_table, source_note = trim_note)
}
if (showtable) print(out_table)
# ===========================================================================
# Return
# ===========================================================================
if (dual) {
return(list(
res = list(res_alt = res_alt, res_null = res_null),
out_table = out_table,
data = list(data_alt = mrct_alt, data_null = mrct_null_dt),
summary_df = summary_df
))
}
return(list(
res = res_alt,
out_table = out_table,
data = mrct_alt,
summary_df = summary_df
))
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.