R/compare_selection_rules.R

Defines functions print.forestsearch_comparison compare_selection_rules extract_selected_subgroups extract_candidate_diagnostics

Documented in compare_selection_rules extract_selected_subgroups print.forestsearch_comparison

# ============================================================================
# compare_selection_rules.R
# ============================================================================
# Wrapper to run forestsearch() across multiple (sg_focus, selection_rule)
# combinations with all other parameters held fixed, capture each run's
# in-flight diagnostic output, build the Pareto-frontier plots, and
# return a structured comparison object.  Pairs naturally with
# `pareto_frontier_table()`, `explain_pareto_selection()`, and the dual
# diagnostic printed by `forestsearch(show_candidate_summary = TRUE)`.
# ----------------------------------------------------------------------------

# Silence R CMD check NOTE for the inline data.table column reference.
utils::globalVariables(c("m"))


# ============================================================================
# extract_candidate_diagnostics() -- internal helper
# ============================================================================
# Slice forestsearch()'s captured stdout into the PREVIEW and SUMMARY
# blocks so the comparison qmd (or any downstream caller) can present
# just the diagnostic tables as the main display, with the full
# captured output kept accessible as a collapsible / on-demand view.
#
# Banner format (defined by print_candidate_preview / print_candidate_summary):
#
#   ====================== ... (line of '=')
#   CANDIDATE EVALUATION PREVIEW (pre-consistency) (...)
#   ====================== ... (line of '=')
#   ... body ...
#   ====================== ... (line of '=')
#
#   ====================== ... (line of '=')
#   CANDIDATE EVALUATION SUMMARY  (...)
#   ====================== ... (line of '=')
#   ... body ...
#   ====================== ... (line of '=')
#
# A block is delimited by THREE '=' lines: the top, the post-banner
# divider, and the bottom.  We slice from the FIRST '=' line of the
# header to the THIRD '=' line, inclusive, so the user sees the full
# framed block.
# ----------------------------------------------------------------------------

#' Slice the PREVIEW and SUMMARY blocks out of captured forestsearch stdout
#'
#' Internal helper used by \code{\link{compare_selection_rules}} to
#' populate the per-combo \code{diagnostics} slot.  Identifies the
#' \code{CANDIDATE EVALUATION PREVIEW (pre-consistency)} and
#' \code{CANDIDATE EVALUATION SUMMARY} blocks in a captured-output
#' character vector and returns them as separate strings, alongside
#' the full original.
#'
#' If a block is not found (e.g.\ \code{show_candidate_summary = FALSE}
#' was passed, or the run errored before reaching that block) the
#' corresponding element is \code{NA_character_}.
#'
#' @param captured Character vector as returned by
#'   \code{\link{capture.output}}.  One element per line.
#'
#' @return A list with character-scalar fields \code{preview},
#'   \code{summary}, and \code{full}.  The first two are NA when the
#'   block is absent; \code{full} always has the original text.
#'
#' @keywords internal
#' @noRd
extract_candidate_diagnostics <- function(captured) {
  if (is.null(captured) || length(captured) == 0L) {
    return(list(preview = NA_character_,
                summary = NA_character_,
                full    = ""))
  }

  # Find the header lines.  Use fixed = TRUE so the banner phrase is
  # treated literally (not regex), and trimws() to be tolerant of any
  # leading/trailing whitespace that might creep in via different cat()
  # call sites.
  ix_preview_hdr <- which(grepl(
    "CANDIDATE EVALUATION PREVIEW", captured, fixed = TRUE))
  ix_summary_hdr <- which(grepl(
    "CANDIDATE EVALUATION SUMMARY", captured, fixed = TRUE))

  # Bar separator: a line of one or more '=' characters (no other
  # printable content).
  is_bar <- grepl("^=+\\s*$", captured)
  bar_ix <- which(is_bar)

  slice_block <- function(hdr_line) {
    # The first bar above the header is the block-open bar; we want
    # the three-bar window: open / under-header / close.
    if (length(hdr_line) == 0L) return(NA_character_)
    hdr_line <- hdr_line[1L]
    bars_before <- bar_ix[bar_ix < hdr_line]
    bars_after  <- bar_ix[bar_ix > hdr_line]
    if (length(bars_before) < 1L || length(bars_after) < 2L) {
      # Not enough bars to bound the block; fall back to including
      # everything from the header to the next bar (or end).
      start_ix <- hdr_line
      end_ix   <- if (length(bars_after) >= 1L) bars_after[1L] else length(captured)
    } else {
      start_ix <- max(bars_before)        # bar immediately above header
      end_ix   <- bars_after[2L]          # second bar after header = closing bar
    }
    paste(captured[start_ix:end_ix], collapse = "\n")
  }

  list(
    preview = slice_block(ix_preview_hdr),
    summary = slice_block(ix_summary_hdr),
    full    = paste(captured, collapse = "\n")
  )
}


# ============================================================================
# extract_selected_subgroups() -- tidy summary of winner per combo
# ============================================================================
# Reduces a `forestsearch_comparison` object to a one-row-per-combo
# data.frame summarizing each configuration's selected subgroup.  The
# selection is `fs$sg.harm` (the top row of `out_sg$result` per
# `sort_subgroups()`); supporting columns come from the same row.
#
# Designed for post-hoc summarization across analyses -- e.g. combining
# the continuous-outcome and binary-outcome comparison vignettes into a
# single side-by-side table.  Save each comparison's tidy summary with
# `saveRDS()` from the vignette, then load and `rbind()` them in a
# separate document.
#
# The function is robust to combos that failed (sg.harm = NULL or
# missing fs) and to mixed effect measures across combos (the
# effect-measure label is recorded per row, not assumed).

#' Tidy summary of selected subgroups across a comparison run
#'
#' Reduces a \code{forestsearch_comparison} object to a tidy
#' data.frame with one row per combo, summarizing each configuration's
#' selected subgroup.  Intended for post-hoc aggregation across
#' analyses (e.g.\ side-by-side summary of a continuous-outcome
#' comparison and a binary-outcome comparison in a single document).
#'
#' @param x A \code{forestsearch_comparison} object as returned by
#'   \code{\link{compare_selection_rules}}.
#' @param analysis_label Optional character scalar identifying the
#'   parent analysis (e.g.\ \code{"continuous"} or \code{"binary"}).
#'   When supplied, it appears as the first column.  Useful when
#'   row-binding tidy summaries from multiple analyses.
#'
#' @return A \code{data.frame} with columns:
#'   \describe{
#'     \item{\code{analysis}}{If \code{analysis_label} is supplied;
#'       otherwise omitted.}
#'     \item{\code{combo}}{Integer index, \code{1..n_combos}.}
#'     \item{\code{combo_label}}{Pretty label (e.g.\
#'       \code{"effMaxSG / pareto"}).}
#'     \item{\code{sg_focus}, \code{selection_rule}}{The two
#'       comparison axes.}
#'     \item{\code{outcome_type}, \code{effect_measure}}{Recorded
#'       per row from \code{fs$outcome_type} /
#'       \code{fs$effect_measure}, so mixed-effect-measure runs
#'       remain comparable.}
#'     \item{\code{subgroup}}{Selected subgroup definition --
#'       \code{NA_character_} if no subgroup was identified;
#'       otherwise \code{paste(fs$sg.harm, collapse = " & ")}.}
#'     \item{\code{N_H}, \code{N_Hc}}{Sample sizes in the harm
#'       subgroup H (\code{treat.recommend == 0}) and its complement
#'       Hc.}
#'     \item{\code{effect}}{The winner's effect estimate on the
#'       natural scale (\eqn{\exp} applied to the stored
#'       \code{hr} column for ratio-scale measures
#'       \code{OR}/\code{RR}/\code{IRR}; passed through otherwise).}
#'     \item{\code{Pcons}}{The winner's consistency probability.}
#'     \item{\code{K}}{Number of factors in the winner's
#'       subgroup definition.}
#'     \item{\code{n_passed}}{Number of candidates that passed
#'       consistency (= \code{nrow(out_sg$result)}).}
#'     \item{\code{on_frontier}}{Logical -- did the selected
#'       subgroup lie on the Pareto frontier?  \code{NA} when the
#'       frontier is unavailable.}
#'     \item{\code{error}}{The error message for failed combos
#'       (\code{NA_character_} on success).}
#'   }
#'
#' @examples
#' \dontrun{
#' cmp_cont <- compare_selection_rules(...)   # continuous analysis
#' cmp_bin  <- compare_selection_rules(...)   # binary analysis
#'
#' tidy_cont <- extract_selected_subgroups(cmp_cont, analysis_label = "continuous")
#' tidy_bin  <- extract_selected_subgroups(cmp_bin,  analysis_label = "binary")
#'
#' all_selected <- rbind(tidy_cont, tidy_bin)
#' saveRDS(all_selected, "selected_subgroups_all.rds")
#' }
#'
#' @export
extract_selected_subgroups <- function(x, analysis_label = NULL) {
  if (!inherits(x, "forestsearch_comparison")) {
    stop("`x` must be a forestsearch_comparison object as returned ",
         "by compare_selection_rules().", call. = FALSE)
  }

  # Local null-coalesce to avoid depending on a sibling-file export
  # when this file is source()d standalone from a vignette.
  `%||%` <- function(a, b) if (is.null(a) || length(a) == 0L) b else a

  n_combos <- nrow(x$combos)
  if (is.null(n_combos) || n_combos == 0L) {
    return(data.frame())  # empty comparison
  }

  rows <- lapply(seq_len(n_combos), function(i) {
    # Bounds-safe accessors.  A correctly-built forestsearch_comparison
    # has $fs and $errors of length n_combos, but defensive indexing
    # makes this function robust to:
    #   (a) Older installed-package versions with different list-sizing
    #       behavior than the source-of-truth here;
    #   (b) Hand-built or partially-assembled comparison objects from
    #       user code that bypasses compare_selection_rules();
    #   (c) Future internal changes that filter slot lengths.
    safe_get <- function(slot, idx) {
      if (is.null(slot) || idx > length(slot)) NULL else slot[[idx]]
    }
    fs   <- safe_get(x$fs,     i)
    err  <- safe_get(x$errors, i)
    lbl  <- if (i <= length(x$combos$label))          x$combos$label[i]          else NA_character_
    sgf  <- if (i <= length(x$combos$sg_focus))       x$combos$sg_focus[i]       else NA_character_
    rule <- if (i <= length(x$combos$selection_rule)) x$combos$selection_rule[i] else NA_character_

    # Defaults for missing / failed combos
    out <- data.frame(
      combo          = i,
      combo_label    = lbl,
      sg_focus       = sgf,
      selection_rule = rule,
      outcome_type   = NA_character_,
      effect_measure = NA_character_,
      subgroup       = NA_character_,
      N_H            = NA_integer_,
      N_Hc           = NA_integer_,
      effect         = NA_real_,
      Pcons          = NA_real_,
      K              = NA_integer_,
      n_passed       = NA_integer_,
      on_frontier    = NA,
      error          = if (is.null(err)) NA_character_ else as.character(err),
      stringsAsFactors = FALSE
    )

    if (is.null(fs)) return(out)

    # Outcome/effect type
    out$outcome_type   <- fs$outcome_type   %||% NA_character_
    out$effect_measure <- fs$effect_measure %||% NA_character_

    # If no subgroup was identified, keep NA fields except defaults set above
    if (is.null(fs$sg.harm) || length(fs$sg.harm) == 0L) {
      out$subgroup <- NA_character_
      # We can still report Hc/H sizes if df.est is present (all in Hc).
      if (!is.null(fs$df.est) && "treat.recommend" %in% names(fs$df.est)) {
        out$N_H  <- as.integer(sum(fs$df.est$treat.recommend == 0L, na.rm = TRUE))
        out$N_Hc <- as.integer(sum(fs$df.est$treat.recommend == 1L, na.rm = TRUE))
      }
      return(out)
    }

    # Selected subgroup definition
    out$subgroup <- paste(fs$sg.harm, collapse = " & ")

    # H/Hc sizes from df.est
    if (!is.null(fs$df.est) && "treat.recommend" %in% names(fs$df.est)) {
      out$N_H  <- as.integer(sum(fs$df.est$treat.recommend == 0L, na.rm = TRUE))
      out$N_Hc <- as.integer(sum(fs$df.est$treat.recommend == 1L, na.rm = TRUE))
    }

    # Effect, Pcons, K, on_frontier from out_sg$result (top row = winner)
    out_sg <- tryCatch(fs$grp.consistency$out_sg, error = function(e) NULL)
    if (!is.null(out_sg) && !is.null(out_sg$result) &&
        nrow(out_sg$result) > 0L) {
      res <- out_sg$result
      out$n_passed <- nrow(res)
      win <- res[1L, ]                # sort_subgroups places winner at row 1
      hr_raw <- as.numeric(win$hr)
      out$effect <- if (out$effect_measure %in% c("OR", "RR", "IRR")) {
        exp(hr_raw)
      } else {
        hr_raw
      }
      out$Pcons <- as.numeric(win$Pcons)
      out$K     <- as.integer(win$K)
      # Frontier membership
      fr <- out_sg$pareto_frontier
      out$on_frontier <- if (!is.null(fr) && nrow(fr) > 0L) {
        as.integer(win$m) %in% as.integer(fr$m)
      } else {
        NA
      }
    }
    out
  })

  result <- do.call(rbind, rows)

  if (!is.null(analysis_label)) {
    result <- cbind(
      analysis = rep(as.character(analysis_label), nrow(result)),
      result,
      stringsAsFactors = FALSE
    )
  }
  result
}


#' Compare forestsearch Runs Across Selection-Rule Combinations
#'
#' Runs \code{\link{forestsearch}} once per combination of
#' \code{sg_focus[i]} + \code{selection_rule[i]} (tuple semantics; the
#' two vectors are paired element-by-element and must have the same
#' length).  All other arguments are held fixed across runs and passed
#' through via \code{...}.
#'
#' For each combination the wrapper:
#' \enumerate{
#'   \item Captures the in-flight console output from forestsearch
#'     (including the pre-consistency \strong{Candidate Evaluation
#'     Preview} and post-consistency \strong{Candidate Evaluation
#'     Summary} when \code{show_candidate_summary = TRUE} is passed).
#'   \item Optionally computes the frontier CIs via
#'     \code{\link{compute_frontier_cis}}.
#'   \item Builds the Pareto-frontier plot via
#'     \code{\link{plot_pareto_frontier}}.
#' }
#'
#' The captured stdout is returned per combination so the caller can
#' \code{cat()} it later for side-by-side inspection in a Quarto chunk.
#' Plot objects are returned individually and (when
#' \pkg{patchwork} is installed) composed into a single side-by-side
#' figure.  The full \code{fs} object for each combination is returned
#' so downstream diagnostics (\code{\link{pareto_frontier_table}},
#' \code{\link{explain_pareto_selection}}) can be run without re-fitting.
#'
#' @section Tuple semantics:
#' With \code{sg_focus = c("hrMaxSG", "hrMaxSG")} and
#' \code{selection_rule = c("pareto", "both")}, two runs are
#' performed: one with \code{(hrMaxSG, pareto)} and one with
#' \code{(hrMaxSG, both)}.  The length-mismatch case raises an error.
#'
#' @section Console capture:
#' All stdout from each \code{forestsearch()} call is captured (not
#' just the diagnostic tables) via \code{capture.output()}.  The
#' PREVIEW / SUMMARY blocks are clearly delineated by banner separators
#' within the captured text.  Use \code{cat(out$console[[i]])} to
#' replay the output in a Quarto chunk; \code{results = "asis"} works
#' but is not required since the captured text already includes
#' newlines.
#'
#' @param df.analysis Analysis-ready data frame; passed to
#'   \code{forestsearch()}.
#' @param sg_focus Character vector of \code{sg_focus} values to try.
#' @param selection_rule Character vector of \code{selection_rule}
#'   values to try.  Must have the same length as \code{sg_focus}.
#' @param compute_cis Logical.  If \code{TRUE} (default), runs
#'   \code{compute_frontier_cis()} for each fit so the plot includes
#'   CI bars.  Set to \code{FALSE} to skip the (often expensive) CI
#'   step.
#' @param n_splits Integer.  Passed to
#'   \code{compute_frontier_cis(n_splits = )}.  Default \code{1000L}.
#' @param ci_seed Integer.  Passed to
#'   \code{compute_frontier_cis(seed = )}.  Default \code{1L}.
#' @param plot_xlim Numeric vector of length 2 (or \code{NULL}).
#'   Common x-axis range to apply to all plots so they're directly
#'   comparable.  Default \code{NULL} = let each plot auto-range.
#' @param show_band Logical.  Whether to draw the effect-band
#'   shading on each plot.  Default \code{TRUE}.
#' @param combo_labels Character vector of length \code{length(sg_focus)},
#'   used as the title for each plot and key for the returned lists.
#'   Default \code{NULL} = auto, e.g.\ \code{"hrMaxSG / pareto"}.
#' @param verbose Logical.  Print one line per combination during
#'   execution.  Default \code{TRUE}.
#' @param ... Additional arguments passed through to every
#'   \code{forestsearch()} call (data names, thresholds, parallel
#'   args, etc.).  Do NOT pass \code{sg_focus} or
#'   \code{selection_rule} here -- they're handled by the wrapper.
#'
#' @return A list with class \code{"forestsearch_comparison"} and
#'   components:
#'   \describe{
#'     \item{\code{combos}}{\code{data.frame} with columns
#'       \code{sg_focus}, \code{selection_rule}, \code{label}.}
#'     \item{\code{fs}}{Named list of \code{forestsearch} result
#'       objects, one per combination.  NULL entries mark fits that
#'       errored.}
#'     \item{\code{ci_tab}}{Named list of frontier-CI tables (or all
#'       NULL if \code{compute_cis = FALSE}).}
#'     \item{\code{plots}}{Named list of \code{ggplot} objects, one per
#'       combination.}
#'     \item{\code{plot_grid}}{A single \pkg{patchwork} object placing
#'       the plots side by side, or \code{NULL} if patchwork isn't
#'       installed.}
#'     \item{\code{plot_combined}}{A single \code{ggplot} composing all
#'       configurations onto one Pareto plot, with each winner labeled
#'       \code{S1: <combo_label>}, \code{S2: <combo_label>}, etc.
#'       Returned only when ALL successful configurations share an
#'       identical passing set (see \code{\link{plot_pareto_combined}}
#'       for the equality criterion); \code{NULL} otherwise.  See
#'       \code{plot_combined_subsets} below for the per-subset
#'       fallback when some -- but not all -- configurations match.}
#'     \item{\code{plot_combined_subsets}}{Named list of \code{ggplot}
#'       objects, one per equivalence class of configurations sharing
#'       an identical passing set.  Only groups of size \eqn{\ge 2}
#'       are included (a singleton group has no peer to combine
#'       with).  Names are derived from the shared \code{sg_focus}
#'       when constant within a group (e.g., \code{"effMaxSG"}); from
#'       the concatenated combo labels otherwise.  When all valid
#'       combos share one passing set this list contains exactly one
#'       element, equal to \code{plot_combined}.  The list is empty
#'       when no two combos match.}
#'     \item{\code{combined_skip_reason}}{Character scalar or
#'       \code{NULL}.  When \code{plot_combined} is \code{NULL}
#'       because the equality precondition failed, this captures the
#'       specific reason -- size mismatch, definition-set mismatch,
#'       or value drift on a named column -- as a single string.
#'       \code{NULL} when the combined plot was built or when fewer
#'       than two fits succeeded.}
#'     \item{\code{console}}{Named list of character vectors -- the
#'       captured stdout from each forestsearch run (full output).}
#'     \item{\code{diagnostics}}{Named list of per-combo slices of the
#'       captured output: each element is a list with character-scalar
#'       fields \code{preview} (the \code{CANDIDATE EVALUATION
#'       PREVIEW} block), \code{summary} (the \code{CANDIDATE
#'       EVALUATION SUMMARY} block), and \code{full} (the entire
#'       captured stdout, same content as \code{console[[i]]}
#'       collapsed to a single string).  \code{preview} and
#'       \code{summary} are \code{NA_character_} when the corresponding
#'       banner is absent (e.g.\ \code{show_candidate_summary} was
#'       \code{FALSE}, or the run errored before reaching it).  This
#'       slice is what a comparison document should display as the
#'       primary diagnostic; \code{full} (or \code{console[[i]]})
#'       remains available for an expandable / on-demand view of the
#'       complete run output.}
#'     \item{\code{errors}}{Named list of error messages (or NULL) for
#'       combos that failed.}
#'   }
#'
#' @examples
#' \dontrun{
#' out <- compare_selection_rules(
#'   df.analysis      = actg_df,
#'   sg_focus         = c("hrMaxSG", "hrMaxSG"),
#'   selection_rule   = c("pareto",  "both"),
#'   # All other forestsearch args:
#'   confounders.name = confounders.name,
#'   outcome.name     = adverse_outcome,
#'   treat.name       = treat.name,
#'   id.name          = id.name,
#'   outcome_type     = "continuous",
#'   effect_measure   = "MD",
#'   adverse_outcome  = TRUE,
#'   hr.threshold     = 10,
#'   hr.consistency   = 5,
#'   pconsistency.threshold = 0.90,
#'   show_candidate_summary = TRUE,
#'   details          = TRUE
#' )
#'
#' # Inspect captured console output for combo 1
#' cat(out$console[[1]])
#'
#' # Side-by-side plot
#' print(out$plot_grid)
#'
#' # Use fs object for downstream diagnostics
#' pareto_frontier_table(out$fs[[1]], ci_table = out$ci_tab[[1]])
#' explain_pareto_selection(out$fs[[2]], ci_table = out$ci_tab[[2]])
#' }
#'
#' @seealso \code{\link{forestsearch}},
#'   \code{\link{plot_pareto_frontier}},
#'   \code{\link{plot_pareto_combined}},
#'   \code{\link{pareto_frontier_table}},
#'   \code{\link{explain_pareto_selection}},
#'   \code{\link{compute_frontier_cis}}.
#' @export
compare_selection_rules <- function(df.analysis,
                                    sg_focus,
                                    selection_rule,
                                    compute_cis  = TRUE,
                                    n_splits     = 1000L,
                                    ci_seed      = 1L,
                                    plot_xlim    = NULL,
                                    show_band    = TRUE,
                                    combo_labels = NULL,
                                    verbose      = TRUE,
                                    ...) {
  .fs_preserve_rng()
  # --- 1. Validate inputs --------------------------------------------------
  if (!is.character(sg_focus) || !is.character(selection_rule)) {
    stop("`sg_focus` and `selection_rule` must be character vectors.",
         call. = FALSE)
  }
  if (length(sg_focus) != length(selection_rule)) {
    stop(sprintf(
      "Tuple-semantics mismatch: length(sg_focus) = %d but length(selection_rule) = %d.  The two vectors are paired element-by-element and must have the same length.  See ?compare_selection_rules for grid alternatives.",
      length(sg_focus), length(selection_rule)),
      call. = FALSE)
  }
  n_combos <- length(sg_focus)
  if (n_combos == 0L) {
    stop("`sg_focus` and `selection_rule` must have at least one element.",
         call. = FALSE)
  }

  # Auto-generate labels if not provided
  if (is.null(combo_labels)) {
    combo_labels <- paste(sg_focus, selection_rule, sep = " / ")
  } else {
    if (length(combo_labels) != n_combos) {
      stop("`combo_labels` length must match `sg_focus` and `selection_rule`.",
           call. = FALSE)
    }
  }
  # Ensure label uniqueness (used as list names)
  if (anyDuplicated(combo_labels) > 0L) {
    combo_labels <- make.unique(combo_labels, sep = "_")
  }

  # Guard against the user accidentally passing sg_focus/selection_rule in ...
  dots <- list(...)
  if (any(c("sg_focus", "selection_rule") %in% names(dots))) {
    stop("`sg_focus` and `selection_rule` are wrapper-controlled axes; do not pass them via `...`.",
         call. = FALSE)
  }

  # --- 2. Loop combinations -----------------------------------------------
  fs_list          <- vector("list", n_combos); names(fs_list)          <- combo_labels
  ci_list          <- vector("list", n_combos); names(ci_list)          <- combo_labels
  plot_list        <- vector("list", n_combos); names(plot_list)        <- combo_labels
  console_list     <- vector("list", n_combos); names(console_list)     <- combo_labels
  diagnostics_list <- vector("list", n_combos); names(diagnostics_list) <- combo_labels
  error_list       <- vector("list", n_combos); names(error_list)       <- combo_labels

  for (k in seq_len(n_combos)) {
    label_k <- combo_labels[k]
    focus_k <- sg_focus[k]
    rule_k  <- selection_rule[k]

    if (verbose) {
      cat(sprintf("[%d/%d] Running forestsearch: sg_focus = %s, selection_rule = %s\n",
                  k, n_combos, focus_k, rule_k))
    }

    # Capture stdout from the forestsearch call, including the
    # show_candidate_summary diagnostic banners.  Use an explicit
    # holder environment so the assignment survives the
    # capture.output / tryCatch nesting (a bare `<<-` can leak to the
    # global env depending on where the lookup finds a match).
    holder <- new.env(parent = emptyenv())
    holder$fs    <- NULL
    holder$error <- NULL
    captured <- tryCatch(
      utils::capture.output({
        holder$fs <- tryCatch(
          do.call(forestsearch, c(
            list(df.analysis    = df.analysis,
                 sg_focus       = focus_k,
                 selection_rule = rule_k),
            dots
          )),
          error = function(e) {
            holder$error <- conditionMessage(e)
            cat(sprintf("ERROR: %s\n", conditionMessage(e)))
            NULL
          }
        )
      }),
      error = function(e) {
        holder$error <- conditionMessage(e)
        character(0)
      }
    )
    fs_k  <- holder$fs
    err_k <- holder$error

    fs_list[[k]]          <- fs_k
    console_list[[k]]     <- captured
    diagnostics_list[[k]] <- extract_candidate_diagnostics(captured)
    error_list[[k]]       <- err_k

    if (is.null(fs_k)) {
      if (verbose) cat(sprintf("    failed: %s\n",
                               if (is.null(err_k)) "no error reported" else err_k))
      next
    }

    # Compute frontier CIs (optional)
    if (isTRUE(compute_cis)) {
      ci_k <- tryCatch(
        compute_frontier_cis(fs_k, n_splits = n_splits, seed = ci_seed),
        error = function(e) {
          if (verbose) cat(sprintf("    compute_frontier_cis() failed: %s\n",
                                   conditionMessage(e)))
          NULL
        }
      )
      ci_list[[k]] <- ci_k
    }

    # Build the plot
    plot_k <- tryCatch(
      plot_pareto_frontier(
        fs        = fs_k,
        ci_table  = ci_list[[k]],
        show_band = show_band,
        xlim      = plot_xlim
      ),
      error = function(e) {
        if (verbose) cat(sprintf("    plot_pareto_frontier() failed: %s\n",
                                 conditionMessage(e)))
        NULL
      }
    )

    # Annotate each plot with its label (so a side-by-side composition reads cleanly)
    if (!is.null(plot_k) && requireNamespace("ggplot2", quietly = TRUE)) {
      plot_k <- plot_k + ggplot2::labs(subtitle = label_k)
    }
    plot_list[[k]] <- plot_k
  }

  # --- 3. Side-by-side composition (patchwork if available) ---------------
  plot_grid <- NULL
  if (requireNamespace("patchwork", quietly = TRUE)) {
    valid_plots <- Filter(Negate(is.null), plot_list)
    if (length(valid_plots) > 0L) {
      plot_grid <- patchwork::wrap_plots(valid_plots, ncol = length(valid_plots))
    }
  } else if (verbose) {
    cat("Note: package 'patchwork' not installed; returning individual plots without side-by-side composition.\n")
  }

  # --- 3b. Combined plot(s) by matching passing-set group ---------------
  #
  # plot_pareto_combined() requires combos to share an identical passing
  # set (same subgroup definitions, same hr/N/E/K values).  The first
  # version of this wrapper passed ALL valid combos at once: if even one
  # disagreed, no combined plot was built.  That all-or-nothing behavior
  # missed cases where natural subsets DO agree.  For example, the
  # comparison vignette with
  #
  #     sg_focus       = c("effMaxSG", "effMaxSG", "effMinSG", "effMinSG")
  #     selection_rule = c("pareto",   "both",     "pareto",   "both")
  #
  # produces matching passing sets within each sg_focus value (combos
  # 1+2 agree; combos 3+4 agree) but not across them (the preview-sort
  # order under effMaxSG vs effMinSG drives different random-split
  # seeds, which can push borderline candidates over or under the
  # pconsistency threshold).
  #
  # Strategy: compute a passing-set signature for each valid fs object,
  # group combos by signature, then build one combined plot per group
  # of size >= 2.  Populate the backward-compatible $plot_combined slot
  # iff there's a single group covering all valid combos.
  plot_combined         <- NULL
  plot_combined_subsets <- list()
  combined_warn         <- NULL
  valid_idx <- which(!vapply(fs_list, is.null, logical(1)))

  if (length(valid_idx) >= 2L && exists("plot_pareto_combined", mode = "function")) {

    # Compute a signature per valid fs: the sorted-collapsed
    # subgroup-definition set.  Two fs objects with identical
    # signatures share an identical passing set (modulo value drift,
    # which plot_pareto_combined() also checks but is typically zero
    # across rules on the same data).
    sig_for_fs <- function(fs) {
      out_sg <- tryCatch(fs$grp.consistency$out_sg, error = function(e) NULL)
      if (is.null(out_sg) || is.null(out_sg$result) ||
          nrow(out_sg$result) == 0L) return(NA_character_)
      res <- out_sg$result
      m_cols <- grep("^M\\.", names(res), value = TRUE)
      keys <- vapply(seq_len(nrow(res)), function(i) {
        v <- unlist(res[i, m_cols, with = FALSE], use.names = FALSE)
        v <- v[!is.na(v) & nzchar(v)]
        if (length(v) == 0L) "(empty)" else paste(sort(v), collapse = " & ")
      }, character(1))
      paste(sort(keys), collapse = " | ")
    }
    sigs <- vapply(fs_list[valid_idx], sig_for_fs, character(1))

    # Group valid combo indices by signature.
    groups <- split(valid_idx, sigs)
    # Drop singleton groups (combined plot needs >= 2 combos).
    groups <- groups[lengths(groups) >= 2L]

    # Build a combined plot per group.  Use the first combo's
    # sg_focus + selection_rule as the group's natural label,
    # falling back to combo labels otherwise.
    for (g in seq_along(groups)) {
      idx <- groups[[g]]
      group_warn <- NULL
      group_plot <- tryCatch(
        withCallingHandlers(
          plot_pareto_combined(
            fs_list       = fs_list[idx],
            combo_labels  = combo_labels[idx],
            ci_table_list = ci_list[idx],
            show_band     = show_band,
            xlim          = plot_xlim,
            verbose       = TRUE
          ),
          warning = function(w) {
            group_warn <<- conditionMessage(w)
            invokeRestart("muffleWarning")
          }
        ),
        error = function(e) NULL
      )
      if (!is.null(group_plot)) {
        # Label this group by the shared sg_focus, when constant; else
        # by the concatenated combo labels.
        sg_in_group <- unique(sg_focus[idx])
        group_label <- if (length(sg_in_group) == 1L) {
          sg_in_group
        } else {
          paste(combo_labels[idx], collapse = " + ")
        }
        plot_combined_subsets[[group_label]] <- group_plot
      } else if (!is.null(group_warn)) {
        # A group that signature-matched but plot_pareto_combined()
        # still rejected (e.g. value drift inside matching definitions).
        # Surface the most recent such reason via combined_warn.
        combined_warn <- group_warn
      }
    }

    # Backward-compatible: $plot_combined is set when ALL valid combos
    # share one signature (i.e., exactly one group, covering everything).
    if (length(groups) == 1L && length(groups[[1L]]) == length(valid_idx)) {
      plot_combined <- plot_combined_subsets[[1L]]
    } else if (length(groups) == 0L) {
      # No group of size >= 2; report a useful reason.
      if (is.null(combined_warn)) {
        combined_warn <- sprintf(
          "All %d valid configurations have distinct passing sets; no two combos can be combined.",
          length(valid_idx))
      }
    } else {
      # Multiple matching subsets, but no single group covers all combos.
      sizes <- vapply(groups, length, integer(1))
      combined_warn <- sprintf(
        paste0("Passing sets fall into %d matching group(s) of sizes %s; ",
               "no single combined plot covers all %d configurations.  ",
               "See $plot_combined_subsets for per-group plots."),
        length(groups), paste(sizes, collapse = ", "), length(valid_idx))
    }

    if (verbose) {
      n_subsets <- length(plot_combined_subsets)
      if (!is.null(plot_combined)) {
        cat("Combined plot built (all", length(valid_idx),
            "configurations share one passing set).\n")
      } else if (n_subsets > 0L) {
        cat(sprintf(
          "Combined plot built per matching subset (%d subset%s: %s).\n",
          n_subsets, if (n_subsets == 1L) "" else "s",
          paste(names(plot_combined_subsets), collapse = ", ")))
        if (!is.null(combined_warn)) {
          cat("  ", combined_warn, "\n", sep = "")
        }
      } else if (!is.null(combined_warn)) {
        cat("Combined plot skipped:\n  ", combined_warn, "\n", sep = "")
      } else {
        cat("Combined plot skipped (no diagnostic captured).\n")
      }
    }
  }

  # --- 4. Assemble return -------------------------------------------------
  combos_df <- data.frame(
    sg_focus       = sg_focus,
    selection_rule = selection_rule,
    label          = combo_labels,
    stringsAsFactors = FALSE
  )

  out <- list(
    combos        = combos_df,
    fs            = fs_list,
    ci_tab        = ci_list,
    plots         = plot_list,
    plot_grid     = plot_grid,
    plot_combined = plot_combined,
    plot_combined_subsets = plot_combined_subsets,
    combined_skip_reason = combined_warn,  # NULL if combined built or never attempted
    console       = console_list,
    diagnostics   = diagnostics_list,
    errors        = error_list
  )
  class(out) <- c("forestsearch_comparison", "list")
  out
}


#' Print Method for forestsearch_comparison
#'
#' Short summary of the comparison.  Use \code{print(x$plot_grid)} for
#' the side-by-side plot and \code{cat(x$console[[i]])} for each
#' combo's diagnostic output.
#'
#' @param x A \code{forestsearch_comparison} object.
#' @param ... Ignored.
#' @return `x`, invisibly. Called for its side effect of printing the
#'   comparison summary.
#' @export
print.forestsearch_comparison <- function(x, ...) {
  cat("forestsearch comparison across selection-rule combinations\n")
  cat("---\n")
  print(x$combos)
  cat("---\n")
  n_ok    <- sum(!vapply(x$fs,     is.null, logical(1)))
  n_plots <- sum(!vapply(x$plots,  is.null, logical(1)))
  n_ci    <- sum(!vapply(x$ci_tab, is.null, logical(1)))
  n_prev  <- sum(vapply(x$diagnostics,
                        function(d) !is.null(d) && !is.na(d$preview),
                        logical(1)))
  n_sumb  <- sum(vapply(x$diagnostics,
                        function(d) !is.null(d) && !is.na(d$summary),
                        logical(1)))
  cat(sprintf("Successful fits: %d / %d\n", n_ok, nrow(x$combos)))
  cat(sprintf("Plots built:     %d / %d\n", n_plots, nrow(x$combos)))
  cat(sprintf("CIs computed:    %d / %d\n", n_ci, nrow(x$combos)))
  cat(sprintf("Diagnostics:     PREVIEW found %d / %d; SUMMARY found %d / %d\n",
              n_prev, nrow(x$combos), n_sumb, nrow(x$combos)))
  n_subsets <- if (is.null(x$plot_combined_subsets)) 0L
               else length(x$plot_combined_subsets)
  cat(sprintf("Combined plot:   %s\n",
              if (!is.null(x$plot_combined)) "yes (all configurations share one passing set)"
              else if (n_subsets > 0L)
                sprintf("per-subset only (%d matching subset%s: %s)",
                        n_subsets,
                        if (n_subsets == 1L) "" else "s",
                        paste(names(x$plot_combined_subsets), collapse = ", "))
              else "no (see combined_skip_reason)"))
  if (!is.null(x$combined_skip_reason)) {
    msg <- x$combined_skip_reason
    cat("  note:   ", msg, "\n", sep = "")
  }
  cat("\nAccess the contents via x$fs, x$ci_tab, x$plots, x$plot_grid,\n",
      "  x$plot_combined, x$plot_combined_subsets, x$diagnostics, x$console.\n", sep = "")
  cat("Show PREVIEW + SUMMARY for combo i:    cat(x$diagnostics[[i]]$preview,\n",
      "                                          x$diagnostics[[i]]$summary,\n",
      "                                          sep = \"\\n\\n\")\n", sep = "")
  cat("Full captured output for combo i:      cat(x$console[[i]], sep = \"\\n\")\n")
  cat("View side-by-side plot:                print(x$plot_grid)\n")
  cat("View combined plot (if available):     print(x$plot_combined)\n")
  invisible(x)
}

Try the forestsearch package in your browser

Any scripts or data that you put into this service are public.

forestsearch documentation built on Nov. 15, 2026, 9:06 a.m.