Nothing
#' Enhanced Bootstrap Results Summary
#'
#' Creates comprehensive output including formatted table with subgroup footnote,
#' diagnostic plots, bootstrap quality metrics, and detailed timing analysis.
#'
#' @param sgharm The selected subgroup object from forestsearch results. Can be:
#' \itemize{
#' \item Character vector of factor definitions (e.g., c("\{age>=50\}", "\{nodes>=3\}"))
#' \item List with `sgharm` element containing factor definitions
#' \item List with `sg.harm_label` element (human-readable labels)
#' }
#' @param boot_results List. Output from forestsearch_bootstrap_dofuture()
#' @param create_plots Logical. Generate diagnostic plots (default: FALSE)
#' @param est.scale Character. "hr" or "1/hr" for effect scale
#' @param digits Integer or NULL. Decimal places for display formatting of
#' numeric columns in the rendered table (per-arm summaries, Diff,
#' effect estimate CI, bias-corrected CI). Default 2. When set, the
#' formatted strings in \code{boot_results$FSsg_tab} are parsed back to
#' numeric and re-formatted at the requested precision; this works
#' reliably as long as the construction-time precision (default 4
#' decimals; controlled by \code{digits} in
#' \code{forestsearch_bootstrap_dofuture}) is at least as high as
#' \code{digits} requested here. Set \code{digits = NULL} to display
#' the construction-time strings unchanged. The \code{n} and \code{n1}
#' columns are \strong{not} reformatted -- their count-with-percent
#' format is preserved as constructed.
#'
#' @return List with components:
#' \describe{
#' \item{table}{gt table with treatment effects and subgroup footnote}
#' \item{diagnostics}{List of bootstrap quality metrics}
#' \item{diagnostics_table_gt}{gt table of diagnostics}
#' \item{plots}{List of ggplot2 diagnostic plots (if create_plots=TRUE)}
#' \item{timing}{List of timing analysis (if timing data available)}
#' \item{subgroup_summary}{List from summarize_bootstrap_subgroups()}
#' }
#'
#' @details
#' The `table` output includes a footnote displaying the identified subgroup
#' definition, analogous to the `tab_estimates` table from \code{\link{sg_tables}}.
#' This is achieved by extracting the subgroup definition from `sgharm` and
#' passing it to \code{\link{format_bootstrap_table}}.
#'
#' @seealso
#' \code{\link{format_bootstrap_table}} for table creation
#' \code{\link{sg_tables}} for analogous main analysis tables
#' \code{\link{summarize_bootstrap_subgroups}} for subgroup stability analysis
#'
#' @examples
#' \dontrun{
#' library(survival)
#' df <- survival::gbsg
#' df$grade3 <- as.integer(df$grade == "3")
#' fs <- forestsearch(df,
#' confounders.name = c("age", "meno", "size", "grade3", "nodes", "pgr", "er"),
#' outcome.name = "rfstime", treat.name = "hormon", event.name = "status")
#' fs_bc <- forestsearch_bootstrap_dofuture(fs, nb_boots = 100)
#' summaries <- summarize_bootstrap_results(fs$sg.harm, fs_bc)
#' summaries$table
#' }
#' @export
summarize_bootstrap_results <- function(sgharm,
boot_results,
create_plots = FALSE,
est.scale = "hr",
digits = 2) {
# ===========================================================================
# SECTION 1: EXTRACT COMPONENTS
# ===========================================================================
FSsg_tab <- boot_results$FSsg_tab
results <- boot_results$results
H_estimates <- boot_results$H_estimates
Hc_estimates <- boot_results$Hc_estimates
# ---------------------------------------------------------------------------
# Display-time digit reformatting (Reading C of the Feb 2026 design).
# FSsg_tab arrives with construction-time precision baked in (typically
# 4 decimals). We parse the formatted strings back to numerics and
# reformat at the requested `digits`, which must be <= construction
# precision to avoid spurious zero-padding.
# ---------------------------------------------------------------------------
if (!is.null(digits) && (is.data.frame(FSsg_tab) || is.matrix(FSsg_tab))) {
FSsg_tab <- .reformat_FSsg_tab_digits(FSsg_tab, digits = digits)
}
# ===========================================================================
# SECTION 2: CALCULATE BOOTSTRAP SUCCESS METRICS
# ===========================================================================
boot_success_rate <- mean(!is.na(results$H_biasadj_2))
nb_boots <- nrow(results)
# ===========================================================================
# SECTION 3: EXTRACT SUBGROUP DEFINITION FOR FOOTNOTE
# ===========================================================================
# Extract subgroup definition string from sgharm
# This mirrors the approach in sg_tables() for tab_estimates
sg_definition <- NULL
if (!is.null(sgharm)) {
if (is.character(sgharm)) {
# Direct character vector: c("{age>=50}", "{nodes>=3}")
sg_valid <- sgharm[!is.na(sgharm) & sgharm != ""]
if (length(sg_valid) > 0) {
sg_definition <- paste(sg_valid, collapse = " & ")
}
} else if (is.factor(sgharm)) {
# Factor: convert to character first
sg_valid <- as.character(sgharm)
sg_valid <- sg_valid[!is.na(sg_valid) & sg_valid != ""]
if (length(sg_valid) > 0) {
sg_definition <- paste(sg_valid, collapse = " & ")
}
} else if (is.list(sgharm)) {
# List structure: check for common element names
# Priority: sg.harm_label > sgharm > sg.harm
if (!is.null(sgharm$sg.harm_label)) {
# Human-readable labels (preferred)
sg_valid <- sgharm$sg.harm_label
sg_valid <- sg_valid[!is.na(sg_valid) & sg_valid != ""]
if (length(sg_valid) > 0) {
sg_definition <- paste(sg_valid, collapse = " & ")
}
} else if (!is.null(sgharm$sgharm)) {
# Technical factor names
sg_valid <- sgharm$sgharm
sg_valid <- sg_valid[!is.na(sg_valid) & sg_valid != ""]
if (length(sg_valid) > 0) {
sg_definition <- paste(sg_valid, collapse = " & ")
}
} else if (!is.null(sgharm$sg.harm)) {
# Alternative naming
sg_valid <- sgharm$sg.harm
sg_valid <- sg_valid[!is.na(sg_valid) & sg_valid != ""]
if (length(sg_valid) > 0) {
sg_definition <- paste(sg_valid, collapse = " & ")
}
}
}
}
# ===========================================================================
# SECTION 4: CREATE FORMATTED TABLE WITH SUBGROUP FOOTNOTE
# ===========================================================================
# Auto-detect effect measure from FSsg_tab column names
# GLM tables have "IRR (95% CI)" or "OR (95% CI)" etc.; survival has "HR (95% CI)"
effect_label <- "HR"
if (is.data.frame(FSsg_tab) || is.matrix(FSsg_tab)) {
tab_cols <- colnames(FSsg_tab)
eff_match <- regmatches(
tab_cols,
regexpr("^(IRR|OR|RR|RD|IRD|MD|HR)", tab_cols)
)
eff_match <- eff_match[nchar(eff_match) > 0]
if (length(eff_match) > 0 && eff_match[1] != "HR") {
effect_label <- eff_match[1]
}
}
formatted_table <- format_bootstrap_table(
FSsg_tab = FSsg_tab,
nb_boots = nb_boots,
est.scale = est.scale,
boot_success_rate = boot_success_rate,
sg_definition = sg_definition
)
# ===========================================================================
# SECTION 5: EXTRACT AND ANALYZE TIMING INFORMATION
# ===========================================================================
has_timing <- !is.null(attr(results, "timing"))
overall_timing <- NULL
iteration_stats <- NULL
fs_stats <- NULL
overhead_stats <- NULL
timing_summary_table <- NULL
timing_table_gt <- NULL
if (has_timing) {
overall_timing <- attr(results, "timing")
has_iteration_timing <- "tmins_iteration" %in% names(results)
has_search_timing <- "tmins_search" %in% names(results)
if (has_iteration_timing) {
iteration_stats <- list(
mean = mean(results$tmins_iteration, na.rm = TRUE),
median = median(results$tmins_iteration, na.rm = TRUE),
sd = sd(results$tmins_iteration, na.rm = TRUE),
min = min(results$tmins_iteration, na.rm = TRUE),
max = max(results$tmins_iteration, na.rm = TRUE),
q25 = quantile(results$tmins_iteration, 0.25, na.rm = TRUE),
q75 = quantile(results$tmins_iteration, 0.75, na.rm = TRUE)
)
}
if (has_search_timing) {
fs_times <- results$tmins_search[!is.na(results$tmins_search)]
if (length(fs_times) > 0) {
fs_stats <- list(
n_runs = length(fs_times),
pct_runs = 100 * length(fs_times) / nb_boots,
mean = mean(fs_times),
median = median(fs_times),
sd = sd(fs_times),
min = min(fs_times),
max = max(fs_times),
total = sum(fs_times)
)
}
}
if (has_iteration_timing && has_search_timing) {
overhead <- results$tmins_iteration - results$tmins_search
overhead <- overhead[!is.na(overhead)]
if (length(overhead) > 0) {
overhead_stats <- list(
mean = mean(overhead),
median = median(overhead),
total = sum(overhead),
pct_of_total = 100 * sum(overhead) / overall_timing$total_minutes
)
}
}
# Create timing summary table
timing_summary_table <- tryCatch({
create_timing_summary_table(
overall_timing = overall_timing,
iteration_stats = iteration_stats,
fs_stats = fs_stats,
overhead_stats = overhead_stats,
nb_boots = nb_boots,
boot_success_rate = boot_success_rate
)
}, error = function(e) {
warning("Could not create timing summary table: ", e$message)
NULL
})
# Create gt timing table
timing_table_gt <- tryCatch({
format_bootstrap_timing_table(
timing_list = list(
overall = overall_timing,
iteration_stats = iteration_stats,
fs_stats = fs_stats,
overhead_stats = overhead_stats
),
nb_boots = nb_boots,
boot_success_rate = boot_success_rate
)
}, error = function(e) {
warning("Could not create gt timing table: ", e$message)
NULL
})
}
# ===========================================================================
# SECTION 6: CREATE DIAGNOSTICS
# ===========================================================================
diagnostics <- list(
n_boots = nb_boots,
n_successful = sum(!is.na(results$H_biasadj_2)),
n_failed = sum(is.na(results$H_biasadj_2)),
success_rate = boot_success_rate
)
diagnostics_table_gt <- NULL
if (requireNamespace("gt", quietly = TRUE)) {
diagnostics_table_gt <- tryCatch({
format_bootstrap_diagnostics_table(
diagnostics = diagnostics,
nb_boots = nb_boots,
results = results,
H_estimates = H_estimates,
Hc_estimates = Hc_estimates,
effect_label = effect_label
)
}, error = function(e) {
warning("Could not create gt diagnostics table: ", e$message)
NULL
})
}
# ===========================================================================
# SECTION 7: CREATE PLOTS (if requested)
# ===========================================================================
plots <- NULL
if (create_plots && requireNamespace("ggplot2", quietly = TRUE)) {
plots <- tryCatch({
create_bootstrap_diagnostic_plots(
results = results,
H_estimates = H_estimates,
Hc_estimates = Hc_estimates,
overall_timing = overall_timing,
effect_label = effect_label
)
}, error = function(e) {
warning("Could not create diagnostic plots: ", e$message)
NULL
})
}
# ===========================================================================
# SECTION 8: PRINT SUMMARY
# ===========================================================================
cat("\n")
cat("===============================================================\n")
cat(" BOOTSTRAP ANALYSIS SUMMARY \n")
cat("===============================================================\n\n")
# Subgroup definition (NEW)
if (!is.null(sg_definition)) {
cat("IDENTIFIED SUBGROUP:\n")
cat("-------------------------------------------------------------\n")
cat(sprintf(" H: %s\n\n", sg_definition))
}
# Success metrics
cat("BOOTSTRAP SUCCESS METRICS:\n")
cat("-------------------------------------------------------------\n")
cat(sprintf(" Total iterations: %d\n", diagnostics$n_boots))
cat(sprintf(" Successful subgroup ID: %d (%.1f%%)\n",
diagnostics$n_successful, diagnostics$success_rate * 100))
cat(sprintf(" Failed to find subgroup: %d (%.1f%%)\n",
diagnostics$n_failed, (1 - diagnostics$success_rate) * 100))
cat("\n")
# Timing summary
if (has_timing) {
cat("TIMING ANALYSIS:\n")
cat("-------------------------------------------------------------\n")
cat("Overall:\n")
cat(sprintf(" Total bootstrap time: %.2f minutes (%.2f hours)\n",
overall_timing$total_minutes, overall_timing$total_hours))
cat(sprintf(" Average per iteration: %.2f min (%.1f sec)\n",
overall_timing$avg_minutes_per_boot,
overall_timing$avg_seconds_per_boot))
if (nb_boots < 1000) {
projected_min <- overall_timing$avg_minutes_per_boot * 1000
cat(sprintf(" Projected for 1000 boots: %.2f min (%.2f hrs)\n",
projected_min, projected_min / 60))
}
cat("\n")
}
# ===========================================================================
# SECTION 9: CREATE SUBGROUP SUMMARY
# ===========================================================================
subgroup_summary <- NULL
if (!is.null(results) && "Pcons" %in% names(results)) {
# Prepare original_sg for summarize_bootstrap_subgroups
original_sg <- NULL
if (!is.null(sgharm)) {
if (is.character(sgharm) || is.factor(sgharm)) {
original_sg <- as.character(sgharm)
} else if (is.list(sgharm)) {
if (!is.null(sgharm$sgharm)) {
original_sg <- sgharm$sgharm
} else if (!is.null(sgharm$sg.harm)) {
original_sg <- sgharm$sg.harm
} else if (!is.null(sgharm$sg.harm_label)) {
original_sg <- sgharm$sg.harm_label
}
}
}
# Extract maxk from boot_results attributes or detect from columns
maxk <- attr(boot_results, "maxk")
if (is.null(maxk)) {
maxk <- sum(c("M.1", "M.2", "M.3", "M.4", "M.5") %in% names(results))
if (maxk == 0) maxk <- 2
}
subgroup_summary <- tryCatch({
summarize_bootstrap_subgroups(
results = results,
nb_boots = nb_boots,
original_sg = original_sg,
maxk = maxk
)
}, error = function(e) {
warning("Failed to create subgroup summary: ", e$message)
NULL
})
}
# ===========================================================================
# SECTION 10: COMPILE AND RETURN OUTPUT
# ===========================================================================
output <- list(
table = formatted_table,
diagnostics = diagnostics,
diagnostics_table_gt = diagnostics_table_gt,
plots = plots,
sg_definition = sg_definition, # NEW: include for reference
subgroup_summary = subgroup_summary
)
# Add timing information if available
if (has_timing) {
output$timing <- list(
overall = overall_timing,
iteration_stats = iteration_stats,
fs_stats = fs_stats,
overhead_stats = overhead_stats,
time_table = timing_summary_table,
time_table_gt = timing_table_gt
)
}
invisible(output)
}
# =============================================================================
# INTERNAL HELPERS
# =============================================================================
#' Re-format Numeric Cells in FSsg_tab at a Lower Precision
#'
#' Parses formatted-string cells in \code{FSsg_tab} back to numerics and
#' re-formats at the requested \code{digits}. Designed for display-time
#' precision control in \code{\link{summarize_bootstrap_results}}.
#'
#' Cells are identified by column name pattern, not content sniffing.
#' Three cell formats are recognized:
#' \enumerate{
#' \item Single value with optional sign and percent suffix (Mean(C)/(T),
#' Rate(C)/(T), Diff): \code{"-56.4321"}, \code{"+12.5"}, \code{"42.1\%"}.
#' \item Three-value CI (effect-measure column,
#' \code{"\{measure\} (95\% CI)"}): \code{"82.7831 (14.8067, 150.7585)"}.
#' \item Three-value CI without space (bias-corrected
#' \code{"\{measure\}*"} column): \code{"72.4500 (-61.5400,206.4400)"}.
#' }
#'
#' Columns NOT touched: \code{Subgroup} (text label), \code{n} and
#' \code{n1} (count-with-percent format like \code{"87 (8.0\%)"} —
#' different semantics).
#'
#' Robustness contract: cells that don't match any expected pattern are
#' returned unchanged. Construction-time precision must be at least
#' \code{digits} for the reformat to be informative; if construction was
#' at lower precision, this function will zero-pad to \code{digits} but
#' cannot recover information.
#'
#' @param tab Data frame or matrix with formatted-string cells.
#' @param digits Integer. Decimal places.
#' @return Reformatted \code{tab}, same shape.
#' @keywords internal
.reformat_FSsg_tab_digits <- function(tab, digits) {
if (is.matrix(tab)) tab <- as.data.frame(tab, stringsAsFactors = FALSE)
col_names <- colnames(tab)
# Column-name patterns — match on what should be reformatted. Excludes
# Subgroup, n, n1. Effect-measure columns are recognized by the
# measure mnemonic followed by either " (" (CI form) or "*" (bias-
# corrected form).
reformat_cols <- character(0)
# Single-value columns (arm summaries and Diff)
reformat_cols <- c(
reformat_cols,
grep("^Rate\\(C\\)$|^Rate\\(T\\)$|^Mean\\(C\\)$|^Mean\\(T\\)$|^Diff$",
col_names, value = TRUE)
)
# CI columns: HR (95% CI), MD (95% CI), etc.
reformat_cols <- c(
reformat_cols,
grep("^(HR|IRR|OR|RR|RD|IRD|MD)\\s*\\(.*CI\\)$", col_names, value = TRUE)
)
# Bias-corrected CI columns: HR*, MD*, etc.
reformat_cols <- c(
reformat_cols,
grep("^(HR|IRR|OR|RR|RD|IRD|MD)\\*$", col_names, value = TRUE)
)
reformat_cols <- unique(reformat_cols)
if (length(reformat_cols) == 0) return(tab)
# Format strings
fmt_val <- paste0("%.", digits, "f")
fmt_signed <- paste0("%+.", digits, "f")
fmt_pct <- paste0("%.", digits, "f%%")
fmt_signed_pct <- paste0("%+.", digits, "f%%")
fmt_ci_space <- paste0(fmt_val, " (", fmt_val, ", ", fmt_val, ")")
fmt_ci_nospace <- paste0(fmt_val, " (", fmt_val, ",", fmt_val, ")")
# Regex patterns — anchored, well-defined
re_single <- "^([+-]?[0-9]+(?:\\.[0-9]+)?)$"
re_single_pct <- "^([+-]?[0-9]+(?:\\.[0-9]+)?)%$"
re_ci <- paste0("^([+-]?[0-9]+(?:\\.[0-9]+)?)\\s*\\(",
"([+-]?[0-9]+(?:\\.[0-9]+)?)\\s*,\\s*",
"([+-]?[0-9]+(?:\\.[0-9]+)?)\\)$")
reformat_one <- function(cell) {
if (is.na(cell) || !nzchar(cell)) return(cell)
s <- trimws(cell)
# CI pattern
m <- regmatches(s, regexec(re_ci, s))[[1]]
if (length(m) == 4) {
vals <- as.numeric(m[2:4])
if (all(is.finite(vals))) {
# Detect whether original had a space after comma (used to
# preserve construction style; falls back to space if ambiguous)
has_space <- grepl(",\\s+[-+0-9]", s)
fmt <- if (has_space) fmt_ci_space else fmt_ci_nospace
return(sprintf(fmt, vals[1], vals[2], vals[3]))
}
}
# Percent single value
m <- regmatches(s, regexec(re_single_pct, s))[[1]]
if (length(m) == 2) {
v <- as.numeric(m[2])
if (is.finite(v)) {
fmt <- if (substr(m[2], 1L, 1L) == "+") fmt_signed_pct else fmt_pct
return(sprintf(fmt, v))
}
}
# Plain single value
m <- regmatches(s, regexec(re_single, s))[[1]]
if (length(m) == 2) {
v <- as.numeric(m[2])
if (is.finite(v)) {
fmt <- if (substr(m[2], 1L, 1L) == "+") fmt_signed else fmt_val
return(sprintf(fmt, v))
}
}
# Unknown pattern — leave unchanged
cell
}
for (cn in reformat_cols) {
tab[[cn]] <- vapply(tab[[cn]], reformat_one, character(1L))
}
tab
}
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.