Nothing
# =============================================================================
# Helper: Sync resolved values into args_call_all
# =============================================================================
#' Sync resolved parameter values into \code{args_call_all}
#'
#' For parameters whose values are resolved late in \code{forestsearch()}
#' (after the initial argument capture in Section 1B), this helper
#' copies the current value of each named formal from the calling
#' environment back into \code{args_call_all}. Centralising this
#' pattern avoids the historical drift where scattered
#' \code{args_call_all$X <- X} mirror lines silently fell out of sync
#' with newly-added formals.
#'
#' @param args_call_all The captured argument list to update.
#' @param env Environment to read values from (typically
#' \code{environment()} of the caller).
#' @param names Character vector of formal names to sync.
#' @return The updated \code{args_call_all} list.
#' @noRd
.sync_args_call_all <- function(args_call_all, env, names) {
for (n in names) {
# Single-bracket assignment of a length-1 list, NOT `[[<-`. Assigning NULL
# with `args_call_all[[n]] <- NULL` DELETES the element, so a formal that
# resolved to NULL (stop_threshold under the hrMaxSG family at ~1430,
# adjust_covariates at ~1885) would vanish from the capture rather than be
# recorded as NULL. `[<-` with list(NULL) stores the NULL.
args_call_all[n] <- list(get(n, envir = env))
}
args_call_all
}
# =============================================================================
# Helper: the effect / consistency threshold pair
# =============================================================================
#' Validate, and where silent derive, the (c1, c2) threshold pair
#'
#' The two effect thresholds are one pair, not two independent knobs. \code{c1}
#' (\code{effect.threshold} / \code{hr.threshold}) admits a candidate subgroup
#' to the family; \code{c2} (\code{consistency.threshold} /
#' \code{hr.consistency}) is the per-split floor that candidate must then clear
#' on both halves of every random split. A \code{c2} above \code{c1} makes the
#' pair degenerate: the consistency-stage entry condition re-filters the
#' screened family on the \emph{higher} threshold, so candidates the screen
#' admitted are discarded at the stage boundary and, when none survives, the
#' whole consistency stage silently does not run. That configuration is
#' rejected here -- before any model is fit -- rather than producing an empty
#' selection that reads like a finding of no subgroup.
#'
#' A \code{c1} supplied \emph{without} a \code{c2} used to leave \code{c2} at
#' the package default \code{1.0} whatever \code{c1} was, which on a ratio
#' estimand silently unlinks the pair -- \code{c1 = 1.5} with \code{c2 = 1.0}
#' screens for a 50\% excess and then accepts any split above parity. It now
#' derives \code{c2 = 0.80 * c1} on the \strong{ratio} scale, announced. On
#' the log scale that is an additive shift of \code{log(0.80)}, never
#' \code{0.80 * log(c1)}: 1.25 -> 1.00, 1.00 -> 0.80, 0.90 -> 0.72. The
#' default pair (1.25, 1.0) is the fixed point of the rule, so a call that sets
#' neither threshold is unmoved. An explicitly supplied \code{c2}, in either
#' spelling, is never overridden.
#'
#' \strong{Scope, deliberately narrow.} The check applies only where the
#' consistency stage actually runs (\code{subgroup_method = "consistency"};
#' \code{"dina"} and \code{"grf"} return from their own sections long before
#' the stage boundary and never consult \code{c2}) and only on the two
#' ratio-scale estimands whose threshold pair is on one comparable scale:
#' survival (HR) and binary \code{"OR"}. \code{RD}, \code{IRD}, \code{MD} and
#' \code{IRR} are untouched, in every branch.
#'
#' Supplying both spellings of one quantity at disagreeing values is also
#' rejected here: the alias merge silently prefers the new spelling, and a
#' pair rule that then reports a value the caller did not write would be worse
#' than no rule.
#'
#' @param outcome_type Resolved outcome type.
#' @param effect_measure Resolved effect measure (\code{NULL} on survival).
#' @param subgroup_method Resolved subgroup method.
#' @param c1,c2 The two thresholds on the natural scale, \emph{after} the alias
#' merge -- i.e. the values this fit will use.
#' @param c1_new,c2_new The new-spelling arguments as supplied
#' (\code{NULL} when absent).
#' @param c1_legacy,c2_legacy The legacy-spelling arguments as supplied,
#' captured \emph{before} the alias merge overwrote them (\code{NULL} when
#' absent).
#' @param user_set_threshold,user_set_consistency The supply flags.
#' @param quiet Suppress the announcement.
#' @return \code{c2}, on the natural scale.
#' @noRd
.fs_resolve_threshold_pair <- function(outcome_type, effect_measure,
subgroup_method, c1, c2,
c1_new, c2_new, c1_legacy, c2_legacy,
user_set_threshold,
user_set_consistency,
quiet = FALSE) {
# The pair rule governs the consistency path on a ratio estimand only.
ratio_pair <- identical(as.character(subgroup_method)[1L], "consistency") &&
(identical(outcome_type, "survival") ||
(identical(outcome_type, "binary") && identical(effect_measure, "OR")))
if (!ratio_pair) return(c2)
# Which name to report: the one the caller wrote; the preferred spelling
# when the value is the package default and the caller wrote neither.
.nm <- function(new, legacy, new_name, legacy_name) {
if (!is.null(new)) new_name else if (!is.null(legacy)) legacy_name
else new_name
}
.disagrees <- function(new, legacy) {
!is.null(new) && !is.null(legacy) &&
!isTRUE(all.equal(as.numeric(new), as.numeric(legacy)))
}
if (.disagrees(c1_new, c1_legacy)) {
stop(sprintf(paste0("effect.threshold = %s and hr.threshold = %s are two ",
"spellings of the same threshold (c1) and disagree; ",
"supply one."),
format(c1_new), format(c1_legacy)), call. = FALSE)
}
if (.disagrees(c2_new, c2_legacy)) {
stop(sprintf(paste0("consistency.threshold = %s and hr.consistency = %s ",
"are two spellings of the same threshold (c2) and ",
"disagree; supply one."),
format(c2_new), format(c2_legacy)), call. = FALSE)
}
c1_name <- .nm(c1_new, c1_legacy, "effect.threshold", "hr.threshold")
c2_name <- .nm(c2_new, c2_legacy, "consistency.threshold", "hr.consistency")
# Derive a silent c2 from c1 on the RATIO scale. Done before the pair check
# below, not after: a derived value satisfies c2 <= c1 for every positive c1,
# so the check that follows is what guarantees the invariant on both routes.
# The announcement is held until the check has passed, so a rejected call
# never reports a threshold it will not use.
derived <- isTRUE(user_set_threshold) && !isTRUE(user_set_consistency)
if (derived) c2 <- 0.80 * c1
# isTRUE(), not a bare comparison: an NA or a non-scalar threshold must
# reach the resolution branches that already handle it, not fail here with
# "missing value where TRUE/FALSE needed".
if (isTRUE(c2 > c1)) {
stop(sprintf("c2 > c1 not allowed for FS: %s = %.2f exceeds %s = %.2f",
c2_name, c2, c1_name, c1), call. = FALSE)
}
# Once per fit, in forestsearch()'s own frame: a replicate receives the
# derived c2 explicitly (SECTION 2B-ii writes it into consistency.threshold,
# which the replay supplies), so user_set_consistency is TRUE there and this
# branch is not re-entered.
if (derived && !isTRUE(quiet)) {
message(sprintf(paste0(
"[forestsearch] consistency.threshold not supplied; derived as ",
"0.80 * %s = 0.80 * %s = %s (ratio scale). Supply ",
"consistency.threshold to override."),
c1_name, sprintf("%g", c1), sprintf("%g", c2)))
}
c2
}
# =============================================================================
# Default Worker Count for parallel_args
# =============================================================================
#' Compute the default worker count for \code{parallel_args}
#'
#' Returns \code{floor(0.80 * N)} where \code{N} is the number of
#' physical (non-hyperthreaded) cores, with a floor of 1 worker.
#' When the environment variable \code{_R_CHECK_LIMIT_CORES_} is
#' set (as during \code{R CMD check}), the result is capped at 2
#' to comply with CRAN policy. When \code{detectCores(logical =
#' FALSE)} returns \code{NA} (some non-x86 platforms), falls back
#' to assuming 2 cores.
#'
#' This helper is used as the default value for
#' \code{parallel_args$workers} in \code{forestsearch()} and
#' related entry points; users can override at the call site.
#'
#' @return Positive integer worker count.
#' @noRd
.default_parallel_workers <- function() {
n_phys <- parallel::detectCores(logical = FALSE)
if (length(n_phys) != 1L || is.na(n_phys) || n_phys < 1L) n_phys <- 2L
cran_cap <- isTRUE(as.logical(
Sys.getenv("_R_CHECK_LIMIT_CORES_", "FALSE")))
if (cran_cap) {
return(min(2L, as.integer(n_phys)))
}
max(1L, as.integer(floor(0.80 * n_phys)))
}
# =============================================================================
# Validation Helper: Outcome / Threshold Consistency
# =============================================================================
#' Validate outcome type, effect measure, and threshold consistency
#'
#' Checks for common misconfigurations that produce silent nonsense:
#' (1) binary data declared as survival, (2) ratio-scale thresholds
#' with identity-scale measures, (3) implausibly small ratio thresholds.
#'
#' @noRd
.validate_outcome_threshold_config <- function(
df.analysis, outcome.name, event.name,
outcome_type, effect_measure,
hr.threshold, hr.consistency,
user_set_threshold, user_set_consistency) {
Y <- df.analysis[[outcome.name]]
# --- Check 1: Data looks binary but outcome_type is survival ---
y_unique <- sort(unique(Y[!is.na(Y)]))
y_is_binary <- length(y_unique) == 2 && all(y_unique %in% c(0, 1))
if (y_is_binary && outcome_type == "survival") {
# Could be legitimate (0/1 event indicator with separate time variable)
# but warn if there's no time-like variation
if (!is.null(event.name) && event.name %in% names(df.analysis)) {
E <- df.analysis[[event.name]]
if (identical(sort(unique(Y)), sort(unique(E)))) {
warning(
sprintf(paste0(
"outcome '%s' is binary (0/1) and identical to event ",
"column '%s'.\n",
" If this is a binary endpoint (not survival), set ",
"outcome_type = 'binary'.\n",
" If this IS survival, the outcome should be a ",
"time-to-event variable, not the event indicator."),
outcome.name, event.name),
call. = FALSE)
}
} else if (is.null(event.name) || !event.name %in% names(df.analysis)) {
warning(
sprintf(paste0(
"outcome '%s' is binary (0/1) but outcome_type = 'survival' ",
"and no event column found.\n",
" Did you mean outcome_type = 'binary'?"),
outcome.name),
call. = FALSE)
}
}
# --- Check 2: Data looks continuous but outcome_type is binary ---
if (outcome_type == "binary" && length(y_unique) > 10) {
warning(
sprintf(paste0(
"outcome '%s' has %d unique values but outcome_type = 'binary'.\n",
" Binary outcomes should have exactly 2 values (0/1).\n",
" Did you mean outcome_type = 'continuous' or 'survival'?"),
outcome.name, length(y_unique)),
call. = FALSE)
}
# --- Check 3: Suspiciously small thresholds for ratio-scale ---
# If outcome_type is survival (ratio scale) and user passed very
# small thresholds, they likely intended an identity-scale measure
is_ratio <- outcome_type == "survival" ||
(!is.null(effect_measure) && effect_measure %in% c("OR", "RR", "IRR"))
if (is_ratio && user_set_threshold && hr.threshold > 0 &&
hr.threshold < 0.5) {
warning(
sprintf(paste0(
"effect.threshold = %.3f is very small for a ratio-scale ",
"measure (%s).\n",
" HR/OR >= %.3f means virtually all subgroups pass screening.\n",
" If you intended an identity-scale threshold (e.g., risk ",
"difference), set:\n",
" outcome_type = 'binary', effect_measure = 'RD', ",
"effect.threshold = %.3f"),
hr.threshold,
if (outcome_type == "survival") "HR" else effect_measure,
hr.threshold, hr.threshold),
call. = FALSE)
}
if (is_ratio && user_set_consistency && hr.consistency > 0 &&
hr.consistency < 0.5) {
warning(
sprintf(paste0(
"consistency.threshold = %.3f is very small for a ratio-scale ",
"measure (%s).\n",
" This means virtually all splits pass consistency.\n",
" If you intended an identity-scale threshold, set:\n",
" effect_measure = 'RD', consistency.threshold = %.3f"),
hr.consistency,
if (outcome_type == "survival") "HR" else effect_measure,
hr.consistency),
call. = FALSE)
}
# --- Check 4: Thresholds > 1 with identity-scale measure ---
# RD/IRD are probability/rate differences bounded in [-1, 1].
# MD (mean difference) has no natural bounds -- skip this check for MD.
is_bounded_identity <- !is.null(effect_measure) &&
effect_measure %in% c("RD", "IRD")
if (is_bounded_identity && user_set_threshold && hr.threshold > 1.0) {
# Name the measure and its ratio-scale counterpart: RD -> OR, IRD -> IRR
# (the ratio measure of the same rate model). A rate difference is not
# bounded by 1 in itself; [-1, 1] is the range the threshold remap uses.
bound_line <- switch(effect_measure,
RD = " A risk difference cannot exceed 1.0.\n",
IRD = " A rate-difference threshold above 1.0 is outside that range.\n")
ratio_measure <- switch(effect_measure, RD = "OR", IRD = "IRR")
warning(
sprintf(paste0(
"effect.threshold = %.2f but effect_measure = '%s' ",
"(identity scale, range [-1, 1]).\n",
"%s",
" Did you mean effect_measure = '%s' (ratio scale)?"),
hr.threshold, effect_measure, bound_line, ratio_measure),
call. = FALSE)
}
invisible(NULL)
}
#' @title ForestSearch: Exploratory Subgroup Identification
#'
#' @description
#' Implements advanced statistical methods for exploratory subgroup
#' identification in clinical trials. Provides tools for identifying
#' patient subgroups with differential treatment effects using machine
#' learning approaches including Generalized Random Forests ('GRF'),
#' LASSO regularization, and exhaustive combinatorial search algorithms.
#' Supports survival endpoints (Cox proportional hazards), binary
#' outcomes (log odds ratio, log relative risk, risk difference),
#' continuous outcomes (mean difference), and count / rate outcomes
#' (log incidence rate ratio via Poisson, quasi-Poisson, or
#' negative-binomial GLMs with optional person-time offset). Features
#' bootstrap bias correction using infinitesimal jackknife methods to
#' address selection bias in post-hoc analyses. Designed for clinical
#' researchers conducting exploratory subgroup analyses in randomized
#' controlled trials, particularly for multi-regional clinical trials
#' ('MRCT') requiring regional consistency evaluation. Methods are
#' described in Leon et al. (2024) \doi{10.1002/sim.10163}.
#' Post-selection inference for the reported subgroup (multiplier
#' resampling, \code{mr_inference = TRUE}) follows León and Anderson
#' (2026a) \doi{10.48550/arXiv.2609.38361}. The current methodology for
#' the search itself -- forest search as closed-form stability selection
#' on splitting consistency, the family-wise false-declaration rate and
#' the two-subgroup claim -- is given in León and Anderson (2026b)
#' \doi{10.48550/arXiv.2610.28379}.
#'
#' @param df.analysis Data frame. Analysis dataset with required columns.
#' @param outcome.name Character. Name of time-to-event outcome variable. Default "tte".
#' @param event.name Character. Name of event indicator (1=event, 0=censored). Default "event".
#' @param treat.name Character. Name of treatment variable (1=treatment, 0=control). Default "treat".
#' @param id.name Character. Name of subject ID variable. Default "id".
#' @param potentialOutcome.name Character. Name of potential outcome variable (optional).
#' @param flag_harm.name Character. Name of true harm flag for simulations (optional).
#' @param confounders.name Character vector. Names of candidate subgroup-defining variables.
#' @param parallel_args List. Parallel processing configuration:
#' \describe{
#' \item{plan}{Character. One of \code{"multisession"} (default;
#' cross-platform, reuses workers across calls), \code{"multicore"}
#' (Linux/macOS only, fastest startup but fails in RStudio interactive
#' sessions), \code{"callr"} (slower per-call, fully isolated R
#' processes), or \code{"sequential"} (no parallelism).}
#' \item{workers}{Integer. Number of parallel workers. Default:
#' \code{floor(0.80 * N)} where \code{N} is the number of physical
#' (non-hyperthreaded) cores, capped to 2 when
#' \code{_R_CHECK_LIMIT_CORES_} is set (e.g., during \code{R CMD
#' check}). On a 4-core laptop the default is 3 workers; on a
#' 16-core workstation it is 12.}
#' \item{show_message}{Logical. Show parallel setup messages.}
#' \item{batch_size}{Integer. Number of \emph{candidate subgroups}
#' dispatched to the workers per batch during consistency evaluation.
#' Default: chosen from the worker count and pool size.
#' \strong{This is a performance knob only -- it does not affect the
#' selected subgroup.} Smaller batches let an early stop take effect
#' sooner (relevant only for \code{sg_focus = "maxeffCons"}, the one
#' focus that early-stops); larger batches amortise dispatch overhead.
#' Not to be confused with \code{twostage_args$batch.size}, which
#' batches \emph{splits} within Stage 2 of the two-stage consistency
#' algorithm -- a different quantity in different units.}
#' }
#' To disable parallelism entirely, pass
#' \code{parallel_args = list(plan = "sequential")}.
#' A sequential and a parallel plan can give different consistency
#' proportions, and possibly a different selection, whenever literal
#' splitting runs (\code{consistency_method = "split"}, an incidence-rate
#' difference (\code{effect_measure = "IRD"}) under \code{"resample"}, or a
#' candidate whose closed form is not available), except under
#' \code{sg_focus = "maxeff"}, which runs the same loop on every plan.
#' @param df.predict Data frame. Prediction dataset (optional).
#' @param df.test Data frame. Test dataset (optional).
#' @param is.RCT Logical. Is this a randomized controlled trial? Default TRUE.
#' @param seedit Integer. Random seed. Default 8316951.
#' @param est.scale Character. Estimation scale ("hr" or "1/hr"). Default "hr".
#' @param use_lasso Logical. Use LASSO for variable selection. Default FALSE.
#' The default changed from \code{TRUE} in an earlier release: with
#' \code{subgroup_method = "consistency"} a model-based front end makes the
#' candidate family data-dependent, which multiplier resampling
#' (\code{mr_inference = TRUE}) requires be fixed. Set \code{TRUE} to
#' restore the prognostic-lasso prefilter used in Leon et al. (2024).
#' @param use_grf Logical. Generate additional candidate cuts from a GRF
#' fit: tree-derived cutpoints are extracted via
#' \code{grf.subg.harm.survival()} / \code{grf.subg.harm.glm()} (or taken
#' from \code{grf_res} / \code{grf_cuts} when supplied) and enter the
#' candidate family through \code{\link{get_FSdata}} alongside the
#' quartile (and any DINA) cuts. This is the only switch that fits a
#' GRF in the forest-search path (the former variable-importance
#' screening, \code{vi.grf.min}, is deprecated and inert). Default FALSE.
#' The default changed from \code{TRUE} in an earlier release, for the same
#' fixed-candidate-family reason given under \code{use_lasso}.
#' @param grf_res GRF results object (optional, for reuse).
#' @param grf_cuts List. Custom GRF cut points (optional).
#' @param use_dina Logical. Generate additional screening-stage candidate
#' cuts from a DINA per-covariate Pareto frontier, fed into
#' \code{\link{get_FSdata}} alongside the GRF cuts. Default FALSE
#' (opt-in); existing behaviour is unchanged when FALSE.
#' @param dina_res A fitted DINA object (optional, for reuse). When NULL
#' and \code{use_dina = TRUE}, a DINA model is fit at the screening
#' stage.
#' @param dina_cuts Character vector of pre-supplied DINA cut expressions
#' (optional). When supplied, the DINA fit / frontier step is skipped
#' and these are used directly.
#' @param dina_args Named list of DINA tuning options, all optional.
#' Recognised keys: \code{family} (defaults to the mapping from
#' \code{outcome_type}: survival -> cox, binary -> binomial,
#' continuous -> gaussian, count -> poisson), \code{seed} (defaults to
#' \code{seedit}), and the fit-only keys \code{n_folds},
#' \code{cens_type}, \code{cens_params} (passed to \code{\link{dina}}
#' only when set); plus the frontier keys forwarded to
#' \code{\link{dina_frontier}}: \code{scope} (default \code{"wide"}),
#' \code{m_diff}, \code{n_min} (defaults to the \code{n.min} of this
#' call), \code{direction}, \code{max_per_covariate}, \code{max_subgroups},
#' and \code{digits}; plus the screening-behavior keys \code{selected_only}
#' (default \code{TRUE}, matching GRF's \code{return_selected_cuts_only}),
#' \code{max_depth} (\code{2L} default -- aligning DINA with \code{maxk = 2}
#' and \code{grf_depth = 2} so the selected cut may be an AND-conjunction of
#' two covariates; set \code{1L} for single-covariate cuts only), and
#' \code{grid_probs}
#' (the per-covariate quantile grid for depth-2 pair thresholds; default
#' interior deciles). \code{max_depth} / \code{grid_probs} are forwarded
#' to \code{\link{dina_subgroup}} and apply to both the selected-cut
#' screening and \code{subgroup_method = "dina"}. (The selector statistic
#' formerly accepted here as \code{select_statistic} is now the top-level
#' \code{dina_select_statistic} argument; a value supplied inside
#' \code{dina_args} is deprecated and overridden with a warning.)
#' When \code{selected_only = TRUE} (the default), \code{use_dina} screening
#' contributes the cut(s) chosen by \code{\link{dina_subgroup}} -- using
#' this call's \code{sg_focus} / \code{selection_rule} /
#' \code{effect_neighborhood} / \code{n.min} / \code{hr.threshold}, ranked by
#' \code{sg_focus} with DINA's native tau-hat as the effect statistic (under
#' \code{"maxSG"} / \code{"minSG"} size ranks first and tau-hat breaks
#' ties). That is the cut \code{subgroup_method = "dina"}
#' would select only under \code{dina_select_statistic = "dina"}; under the
#' default \code{dina_select_statistic = "effect"},
#' \code{subgroup_method = "dina"} re-ranks the qualifying family on the
#' inferential effect and can select a different cut, while this screening
#' step does not re-rank. Set \code{FALSE} to contribute the full frontier
#' candidate set instead.
#'
#' \strong{\code{m_diff} is the candidacy floor, on the link scale, and is
#' derived rather than taken from this list.} It is the harm floor a
#' candidate must clear to enter the qualifying family that \code{sg_focus}
#' then ranks -- \code{log(HR)} for \code{cox}, \code{log(OR)} for
#' \code{binomial}, the log mean-count ratio for \code{poisson} (DINA takes
#' no exposure offset -- \code{offset.name} is not passed to its fit -- so
#' this equals \code{log(IRR)} only when mean follow-up does not depend on
#' arm given the covariates), and the raw mean
#' difference for \code{gaussian}. Under \code{subgroup_method = "dina"}
#' (and under \code{selected_only = TRUE} screening) it is computed as
#' \code{log(hr.threshold)} -- identity for \code{gaussian} -- from the
#' resolved \code{effect.threshold}, and an \code{m_diff} supplied here is
#' \strong{ignored}. Set the floor with \code{effect.threshold} /
#' \code{hr.threshold}. The key remains meaningful only where the raw
#' \code{\link{dina_frontier}} candidate set is used directly.
#'
#' \strong{The same holds for every frontier key, not only
#' \code{m_diff}.} All seven -- \code{scope}, \code{m_diff},
#' \code{n_min}, \code{direction}, \code{max_per_covariate},
#' \code{max_subgroups} and \code{digits} -- are \strong{inert under}
#' \code{subgroup_method = "dina"}, which selects with
#' \code{\link{dina_subgroup}} and never consults a frontier table. Under
#' \code{use_dina = TRUE} screening with \code{selected_only = TRUE} (the
#' default) a frontier is computed and then discarded in favour of the
#' selected cut, so six of the seven change nothing; only \code{digits}
#' still acts, rounding the threshold in the emitted cut expression. The
#' seven keys govern the candidate pool only under
#' \code{selected_only = FALSE}, where
#' \code{\link{dina_frontier}}'s \code{cut_expr} column \emph{is} the pool.
#' Supplying any of the seven under \code{subgroup_method = "dina"} now
#' raises a single \code{warning()} naming every offending key.
#'
#' Under \code{dina_select_statistic = "effect"} the floor still defines the
#' qualifying family on the tau-hat scale while selection re-ranks that
#' family on the refit inferential effect; because multiplier resampling
#' de-biases over the realized selection event, \code{m_diff} fixes the
#' family MR de-biases over. See \code{\link{dina_subgroup}}.
#' Unknown keys raise
#' an error.
#' @param dina_select_statistic Character, one of \code{"effect"} (default) or
#' \code{"dina"}, used only when \code{subgroup_method = "dina"}. The DINA
#' analogue of \code{grf_select_statistic}. \code{"dina"} ranks DINA's
#' qualifying family on its native subgroup-mean tau-hat (unchanged legacy
#' behaviour). \code{"effect"} re-ranks the same family on the inferential
#' effect measure (Cox HR for survival; the resolved GLM effect otherwise),
#' scored with the same per-candidate estimator multiplier resampling (MR)
#' uses, so the realized selection is the exact event MR de-biases (and
#' MR's native-family restriction follows the effect rather than
#' tau-hat). \code{"effect"} is the default because only it ranks on the
#' inferential coefficient; \code{"dina"} is rejected under
#' \code{mr_inference = TRUE}.
#' @param subgroup_method Character, one of \code{"consistency"} (default),
#' \code{"dina"}, or \code{"grf"}. \code{"consistency"} is the standard
#' ForestSearch pipeline (GRF/LASSO screening then the consistency search).
#' \code{"dina"} delegates subgroup \emph{selection} to
#' \code{\link{dina_subgroup}} and bypasses GRF, LASSO and the consistency
#' search: a DINA model is fit, a single subgroup is selected using this
#' call's \code{sg_focus} / \code{selection_rule} /
#' \code{effect_neighborhood} / \code{n.min} / \code{hr.threshold}, and
#' that subgroup is returned as \code{sg.harm}. \code{dina_args} supplies
#' only the DINA \emph{fit} tuning in this mode (frontier keys are
#' ignored). \code{"grf"} is the GRF analogue: it delegates selection to the
#' GRF subgroup-identification routine
#' (\code{\link{grf.subg.harm.survival}} for survival,
#' \code{\link{grf.subg.harm.glm}} for GLM outcomes), again bypassing LASSO,
#' DINA and the consistency search, and returns the policy-tree harm leaf as
#' \code{sg.harm}. GRF-selection mode is configured from this call's existing
#' GRF arguments (\code{frac.tau}, \code{dmin.grf}, \code{grf_depth},
#' \code{is.RCT}, \code{seedit}, and the GLM extras) -- there is no separate
#' argument list -- so it uses the same settings GRF screening would. For
#' both \code{"dina"} and \code{"grf"}, the existing bootstrap de-biasing
#' applies unchanged, re-fitting and re-selecting on each replicate. The
#' selected subgroup may be a single covariate or, where the method's depth
#' allows (DINA \code{max_depth = 2}; GRF \code{grf_depth >= 2}), an
#' AND-conjunction.
#' @param max_n_confounders \strong{Deprecated} (0.4.0.9000): accepted and
#' ignored with a warning. GRF variable-importance screening of the
#' candidate cut columns was removed so that the candidate family is the
#' cut grid alone unless \code{use_lasso}, \code{use_grf} or
#' \code{use_dina} is \code{TRUE}. It capped the importance-ordered
#' column list, which no longer exists. Will be removed in a future
#' release; drop it from the call.
#' @param grf_depth Integer. GRF tree depth. Default 2.
#' @param grf_selection Character, one of \code{"frontier"} (default) or
#' \code{"tree"}, used only when \code{subgroup_method = "grf"}.
#' \code{"tree"} selects via the GRF policy tree. \code{"frontier"} selects
#' from the Pareto frontier of the doubly-robust scores (see
#' \code{\link{grf.subg.harm.survival}}); the frontier rule is taken from
#' \code{sg_focus} -- \code{"eff"}, \code{"effMaxSG"}, \code{"effMinSG"},
#' \code{"maxSG"} and \code{"minSG"} each map to the aligned frontier rule,
#' as in \code{dina_subgroup()} -- and the relative band from
#' \code{effect_neighborhood}. \code{"maxeff"} and \code{"maxeffCons"} map
#' \strong{explicitly} to the plain effect-argmax rule (\code{"eff"}), the
#' same rule \code{"hr"} takes: GRF computes no \code{Pcons}, so the
#' \code{Cons} qualifier has nothing to bind to. The mapping is exhaustive
#' over the canonical foci and raises an error rather than falling through,
#' so no focus can silently select under a rule the caller did not request.
#' (Earlier versions had no branch for these two and defaulted them to
#' \code{"effMaxSG"} silently; pairing them with
#' \code{grf_selection = "frontier"} is now well defined.)
#' \code{"frontier"} is the default
#' because it enumerates a family that can be ranked on the inferential
#' effect; the policy tree exposes no such family, so \code{"tree"} is
#' rejected under \code{mr_inference = TRUE}.
#' @param grf_select_statistic Character, one of \code{"effect"} (default) or
#' \code{"dr"}, used only when \code{subgroup_method = "grf"} and
#' \code{grf_selection = "frontier"}. \code{"dr"} selects the frontier winner
#' on GRF's native doubly-robust score (legacy behaviour). \code{"effect"}
#' re-ranks the same DR-candidate frontier on the inferential effect measure
#' (Cox HR for survival; the resolved GLM effect otherwise), scored with the
#' same per-candidate estimator multiplier resampling (MR) uses, so the realized
#' selection is the exact event MR de-biases (and MR's
#' native-family restriction follows the effect rather than the DR score).
#' \code{"effect"} is the default because only it ranks on the inferential
#' coefficient; \code{"dr"} is rejected under \code{mr_inference = TRUE}.
#' Under \code{"effect"}, \code{dmin.grf} is applied first, on the DR scale,
#' as an existence gate: if no DR candidate reaches it, no subgroup is
#' returned. Otherwise it is not applied per candidate: the whole
#' DR-candidate family (filtered by \code{n.min}, not by \code{dmin.grf}) is
#' re-ranked, and admission uses the effect floor from \code{hr.threshold}
#' (the resolved \code{effect.threshold} for GLM outcomes). If no candidate
#' can be scored on the effect, the DR winner, which did reach
#' \code{dmin.grf}, is kept; if candidates are scored but none clears the
#' effect floor, no subgroup is returned.
#' Ignored for \code{grf_selection = "tree"} (the policy-tree leaf is the
#' selection, with no enumerated family to rank).
#' @param dmin.grf Numeric. Harm threshold on GRF's doubly robust (DR) scale,
#' not a number of events. It is compared with a subgroup's DR harm effect,
#' the subgroup mean of the DR score for control minus the subgroup mean of
#' the DR score for treatment (the two columns of
#' \code{policytree::double_robust_scores()}, computed for every patient):
#' for survival a difference in restricted mean survival time up
#' to the GRF horizon (see \code{frac.tau}); for other outcomes a difference
#' on the scale of the outcome given to GRF (see \code{grf_count_transform}).
#' Under \code{grf_selection = "tree"} (and in \code{use_grf} screening) the
#' policy-tree subgroup with the largest DR harm effect must reach it; under
#' \code{grf_selection = "frontier"} with \code{grf_select_statistic = "dr"}
#' it is applied to every frontier candidate. Under
#' \code{grf_select_statistic = "effect"} it is applied first as an existence
#' gate on the DR scale and is then not applied per candidate; see
#' \code{grf_select_statistic}. Default 0.0.
#' @param frac.tau Numeric in (0, 1]. Multiplier on the GRF time horizon
#' passed to \code{grf::causal_survival_forest()}. The effective
#' horizon is
#' \code{frac.tau * min(max(Y[treated, event]), max(Y[control, event]))},
#' i.e. \code{frac.tau} times the smaller of the two arm-specific
#' maximum event times. Values < 1 truncate the horizon inward of
#' that maximum (the conservative choice when events are sparse near
#' the tail). Used by the downstream call to
#' \code{\link{grf.subg.harm.survival}}. Used only when
#' \code{outcome_type = "survival"}; ignored for GLM outcomes
#' (binary, continuous, count). Default 0.8.
#' @param return_selected_cuts_only Logical. If TRUE (default), GRF returns only cuts from the
#' tree depth that identified the selected subgroup meeting `dmin.grf`. If FALSE
#' returns all cuts from all fitted trees (depths 1 through `grf_depth`).
#' See \code{\link{grf.subg.harm.survival}} for details.
#' @param conf_force Character vector of forced cut expressions (optional),
#' e.g. `c("er <= 0", "pgr <= 10")`. Literal cut locations: unlike the
#' `conf.cont_*` arguments these do not move with a resample.
#' @param defaultcut_names Character vector. Default cut variable names (optional).
#' @param cut_type Character. Cut strategy: `"default"` or `"median"`. Default
#' `"default"`. These are the only permitted values -- `get_FSdata()`
#' validates against them and errors otherwise.
#' @param exclude_cuts Character vector. Variables to exclude from cutting (optional).
#' @param replace_med_grf Logical. Replace median with GRF cuts. Default FALSE.
#' @param cont.cutoff Integer. Cutoff for continuous vs categorical. Default 4.
#' @param conf.cont_medians Character vector of continuous confounders to cut at
#' their median (optional). **Names, not values** -- the cut location is the
#' median computed from the supplied data, so it is not fixed by this
#' argument and moves with a resample. To pin a cut location, pass a literal
#' cut expression via `conf_force`.
#' @param conf.cont_medians_force Character vector of additional continuous
#' confounders to force a median cut on (optional). Names, not values, with
#' the same consequence as `conf.cont_medians` above.
#' @param conf.cont_jcuts Named integer list (each value >= 1). Per-variable
#' J-quantile cut override for continuous covariates: for an entry
#' \code{X = J}, the default cut set for X is replaced by \code{J}
#' binary cut points at the (k/(J+1))-th quantiles of X
#' (k = 1, ..., J), defining J+1 non-overlapping intervals. Names
#' must be in \code{confounders.name} and must not overlap with
#' \code{defaultcut_names} or \code{conf.cont_medians_force}. J-cut
#' variables bypass LASSO filtering, matching \code{defaultcut_names}
#' semantics. Variables not listed retain default behaviour.
#' Forwarded to \code{\link{get_FSdata}} via \code{filter_call_args()};
#' see there for full semantics.
#' @param collapse_cuts Logical. If TRUE, collapse near-redundant continuous
#' candidate cuts before the search. Continuous covariates can generate many
#' thresholds that are practically redundant (e.g. \code{"age <= 35.7"} and
#' \code{"age <= 35"}); when enabled, cuts on the same variable and operator
#' within a per-variable standard-error band are merged to a single
#' rounded-centroid threshold, subject to a membership safety check.
#' Forwarded to \code{\link{get_FSdata}}; see \code{\link{collapse_redundant_cuts}}
#' for the algorithm. Default TRUE. Pass \code{collapse_cuts = FALSE} to
#' recover the un-coarsened candidate pool used by earlier package versions.
#' @param collapse_cuts_args List of overrides merged onto the defaults
#' \code{list(c = 1.0, tol = 0.05, digits = 0L)}: band multiplier \code{c}
#' (\code{band = c * sd(x)/sqrt(n)}), membership safety tolerance \code{tol}
#' (fraction of n when < 1, absolute count when >= 1), and representative
#' rounding \code{digits}. Ignored when \code{collapse_cuts = FALSE}.
#' @param n.min Integer or \code{NULL}. Minimum subgroup size. Default 60.
#' Supplying a value (or omitting the argument) uses that fixed floor, as in
#' prior versions. Passing \code{n.min = NULL} opts into a sample-size-adaptive
#' floor \code{max(60, ceiling(n.min.frac * N))}, where \code{N} is the
#' analysis sample size -- at least 60, and at least \code{n.min.frac} of
#' \code{N}. Growing the minimum subgroup size with \code{N} curbs false
#' discovery from very small subgroups in large samples. The resolved integer
#' is used everywhere downstream (screening, DINA, GRF, the consistency
#' search, and the bootstrap).
#' @param n.min.frac Numeric in (0, 1). Fraction of the analysis sample size
#' used for the adaptive \code{n.min} floor when \code{n.min = NULL}. Default
#' 0.10. Ignored when \code{n.min} is supplied.
#' @param effect.threshold Numeric or NULL. `c1`, the \strong{screening
#' threshold on a candidate subgroup's own effect}, estimated on the full
#' sample. A candidate must clear it to enter the consistency stage. For
#' ratio-scale measures (OR, RR, IRR, HR): on the ratio
#' scale (e.g., 1.5 means OR >= 1.5). For identity-scale measures
#' (RD, IRD, MD): on the identity scale (e.g., 0.07 means RD >= 7 pct
#' points). If NULL (default), falls back to \code{hr.threshold}.
#' Distinct from \code{consistency.threshold} (`c2`), which is applied
#' within each split half, and from \code{pconsistency.threshold} (`p*`),
#' which is a proportion rather than an effect. On the consistency path with
#' a ratio estimand (survival HR, binary \code{"OR"}), supplying `c1` and
#' \strong{not} `c2` derives \code{c2 = 0.80 * c1} on the ratio scale, with
#' a message; see the \emph{Threshold vocabulary and resolved defaults}
#' section for that rule and for the value this resolves to under each
#' estimand.
#' @param consistency.threshold Numeric or NULL. `c2`, \strong{an effect
#' threshold} -- \strong{not} a proportion, and \strong{not} the
#' consistency rate. It is applied to the subgroup's effect estimated
#' \emph{within each split half}; a split counts as consistent when both of
#' its halves clear `c2`. Same scale conventions as
#' \code{effect.threshold}.
#' If NULL (default), falls back to \code{hr.consistency}.
#' Its companion is \code{pconsistency.threshold} (`p*`), the
#' \emph{fraction} of splits that must clear `c2`: this argument sets the
#' bar, that one counts how often the bar is met. Both names contain the
#' word "consistency" and they are different quantities. On the consistency
#' path with a ratio estimand (survival HR, binary \code{"OR"}) `c2` must be
#' \strong{less than or equal to} `c1`; \code{c2 > c1} is an error. Left
#' unsupplied there, it is derived as \code{0.80 * c1} rather than left at
#' its default. See the \emph{Threshold vocabulary and resolved defaults}
#' section for both rules and for the value this resolves to under each
#' estimand.
#' @param hr.threshold Numeric. Legacy name for \code{effect.threshold} --
#' `c1`, the screening threshold on a candidate subgroup's own effect.
#' Retained for backward compatibility. Default 1.25. When
#' \code{effect.threshold} is provided, \code{hr.threshold} is ignored;
#' supplying both at disagreeing values is an error. Carries the same
#' `c2` derivation as \code{effect.threshold}.
#' @param hr.consistency Numeric. Legacy name for
#' \code{consistency.threshold} -- `c2`, the per-split \strong{effect}
#' threshold, not a proportion and not the consistency rate.
#' Retained for backward compatibility. Default 1.0. When
#' \code{consistency.threshold} is provided, \code{hr.consistency} is
#' ignored; supplying both at disagreeing values is an error. Carries the
#' same \code{c2 <= c1} requirement as \code{consistency.threshold}.
#' @param sg_focus Character. Subgroup selection focus -- \emph{what} is
#' selected, not merely how candidates are sorted. Except for
#' \code{"maxeff"}, every focus selects among \strong{qualifiers}: candidates
#' whose consistency rate reaches \code{pconsistency.threshold}. One of:
#' \describe{
#' \item{\code{"hr"} (or \code{"eff"}, \code{"maxcons"})}{Pick the
#' qualifier with the highest consistency (\code{Pcons}); ties broken by
#' largest effect. \strong{This is consistency-primary with effect only
#' as a tiebreak} -- despite the name, it does not maximise the effect.
#' Use \code{"maxeffCons"} for that. \code{"maxcons"} is the
#' recommended spelling, since it says what the rule does.}
#' \item{\code{"maxeffCons"}}{Pick the qualifier with the largest effect;
#' ties broken by fewest cuts (\code{K}). The effect maximiser
#' \emph{subject to} the consistency floor -- as against \code{"maxeff"},
#' which applies no floor. This is the only focus for which early
#' stopping is sound; see \code{stop_threshold}.}
#' \item{\code{"maxSG"}}{Pick the qualifier with the largest sample
#' size; ties broken by consistency. Not a spelling of
#' \code{"hrMaxSG"}: it applies no effect band.}
#' \item{\code{"minSG"}}{Pick the qualifier with the smallest sample
#' size; ties broken by consistency. Not a spelling of
#' \code{"hrMinSG"}.}
#' \item{\code{"hrMaxSG"} (or \code{"effMaxSG"})}{Among candidates
#' with effect size within \code{effect_neighborhood} of the
#' maximum, pick the one with the \emph{largest} sample size.}
#' \item{\code{"hrMinSG"} (or \code{"effMinSG"})}{Among candidates
#' with effect size within \code{effect_neighborhood} of the
#' maximum, pick the one with the \emph{smallest} sample size.}
#' \item{\code{"maxeff"}}{The effect maximiser over the enumerated
#' family, with no consistency threshold, effect threshold, early
#' stopping, two-stage screening or candidate-pool truncation.
#' Implements the argmax primitive of Guo and He (2021). Size/event
#' minima (\code{n.min}, \code{d0.min}, \code{d1.min}) still apply as
#' estimability constraints; prevalence and redundancy pruning are
#' relaxed to their most permissive setting (\code{minp} -> 0,
#' \code{rmin} -> 0) and duplicate removal collapses identical-membership
#' candidates to their fewest-cut representative, so only degenerate or
#' exactly-duplicated candidates are dropped and the argmax is invariant.
#' Because consistency (\code{Pcons}) never enters the argmax, it is
#' computed for the SELECTED subgroup only (reported alongside it) rather
#' than for every candidate, avoiding the per-candidate consistency refits.
#' Contrast \code{"maxeffCons"}, which applies the same argmax but only
#' among candidates clearing \code{pconsistency.threshold}, and
#' \code{"hr"}, which ranks by consistency first and uses effect only as
#' a tiebreaker.}
#' }
#' \strong{The descriptions above are for \code{subgroup_method =
#' "consistency"}.} There, \code{"maxeffCons"} retains \emph{both} the
#' consistency floor (\code{pconsistency.threshold}) and the effect floor,
#' while \code{"maxeff"} disables both -- the distinction the \code{Cons}
#' suffix names.
#'
#' For \code{subgroup_method = "dina"} and \code{"grf"}, \code{"maxeff"} and
#' \code{"maxeffCons"} are \strong{synonyms}, both selecting the effect
#' maximiser over the identifier's qualifiers with the harm floor active.
#' Neither engine has a consistency floor -- neither computes \code{Pcons},
#' and no DINA or GRF sort key contains one -- so the \code{Cons} qualifier
#' has nothing to bind to. The two could in principle have been separated
#' by the effect floor alone; they deliberately are not, because the
#' manuscript keeps the harm threshold in a common form across all three
#' identifiers, and \code{"maxeff"} exists for \code{"consistency"} as a
#' comparison against the argmax primitive of Guo and He (2021), which has
#' no DINA or GRF counterpart. No floor is disabled by this on any path,
#' and the collapse raises no condition: it is intended behaviour, and a
#' warning would fire on every such run.
#'
#' \strong{Per-engine resolution.} Every accepted spelling, and the rule
#' that actually runs for it on each engine:
#'
#' \tabular{lll}{
#' \strong{sg_focus} \tab \strong{consistency} \tab \strong{dina / grf} \cr
#' \code{eff}, \code{hr}, \code{maxcons} \tab consistency argmax
#' (\code{Pcons}-primary, effect breaks ties) \tab effect argmax,
#' \code{order(-eff)} \cr
#' \code{maxeff} \tab effect argmax, no floors \tab effect argmax,
#' \code{order(-eff)} \cr
#' \code{maxeffCons} \tab effect argmax with the consistency floor \tab
#' effect argmax, \code{order(-eff)} \cr
#' \code{effMaxSG}, \code{hrMaxSG} \tab largest N within the effect band,
#' per \code{selection_rule} \tab as documented in
#' \code{\link{dina_subgroup}} \cr
#' \code{effMinSG}, \code{hrMinSG} \tab smallest N within the effect band,
#' per \code{selection_rule} \tab as documented in
#' \code{\link{dina_subgroup}} \cr
#' \code{maxSG} \tab largest N among qualifiers \tab largest N \cr
#' \code{minSG} \tab smallest N among qualifiers \tab smallest N \cr
#' }
#'
#' The collapse sets, stated explicitly. On \code{"consistency"},
#' \{\code{eff}, \code{hr}, \code{maxcons}\} is one rule, and \code{maxeff}
#' and \code{maxeffCons} are two further \emph{distinct} rules. On
#' \code{"dina"} and \code{"grf"}, \{\code{eff}, \code{hr}, \code{maxcons},
#' \code{maxeff}, \code{maxeffCons}\} is \strong{one} rule -- five spellings,
#' one \code{order(-eff)}.
#'
#' \code{forestsearch()} announces both collapses at run time: when the
#' canonical rule differs from the spelling passed, it emits one
#' \code{message()} (suppressed by \code{quiet}) naming the rule that will
#' actually run. \code{\link{fs_focus_tag}} returns the stem tag for each
#' cell of the table above, and is the supported way to label output files by
#' the rule that ran rather than by the spelling requested.
#'
#' Default \code{"hr"}. The \code{"eff*"} forms are aliases for the
#' \code{"hr*"} forms and read more naturally in GLM contexts
#' (continuous MD, binary OR/RR/RD, count IRR) where there is no
#' hazard ratio. Both vocabularies produce identical results; pick
#' whichever fits the outcome type. See \code{\link{sort_subgroups}}
#' for full sort keys and tiebreakers.
#'
#' \strong{Scope of the band arguments.} \code{selection_rule} and
#' \code{effect_neighborhood} configure the effect band, which only
#' \code{"hrMaxSG"} / \code{"hrMinSG"} (equivalently \code{"effMaxSG"} /
#' \code{"effMinSG"}) consult. They are inert for every other focus, and
#' supplying \code{selection_rule} other than \code{"neighborhood"} with a
#' non-band focus is an error rather than a silent no-op.
#'
#' \strong{Choosing between the three effect-oriented rules.}
#' \code{"maxeff"} answers "what is the most extreme subgroup in this
#' family?"; \code{"maxeffCons"} answers "what is the most extreme subgroup
#' that also replicates across splits?"; \code{"hr"}/\code{"maxcons"} answers
#' "which subgroup replicates most reliably?". They can and do select
#' different subgroups on the same data.
#' @param selection_rule Character. Rule defining the candidate
#' inclusion set for \code{"hrMaxSG"} / \code{"hrMinSG"}. One of
#' \code{"neighborhood"} (default; current behaviour),
#' \code{"pareto"} (2D Pareto-non-dominated set in (effect, N)),
#' or \code{"both"} (intersection of the two). Forwarded to
#' \code{\link{sort_subgroups}} via \code{filter_call_args()};
#' see there for full semantics. Must be \code{"neighborhood"} for
#' other \code{sg_focus} values.
#' @param effect_neighborhood Numeric in \code{[0, 1)}. Relative
#' tolerance for \code{"hrMaxSG"} and \code{"hrMinSG"} selection. A
#' candidate is in the \emph{effect-size neighborhood} iff its
#' (natural-scale) effect is at least
#' \code{(1 - effect_neighborhood) * max(effect)}. Default
#' \code{0.10} (within 10\% of the strongest effect). Setting
#' \code{effect_neighborhood = 0} reduces \code{"hrMaxSG"}/
#' \code{"hrMinSG"} to a strict max-effect filter (only candidates
#' tied at the maximum qualify). For GLM ratio measures (OR, IRR),
#' the neighborhood test is applied on the natural scale. Ignored
#' when \code{sg_focus} is \code{"hr"}, \code{"maxSG"}, or
#' \code{"minSG"}.
#' @param stop_threshold Numeric in \code{[0, 1]} or \code{NULL}.
#' Early stopping threshold for consistency evaluation. When a candidate
#' subgroup's consistency probability (\code{Pcons}) meets or exceeds this
#' threshold, evaluation stops early -- remaining candidates are skipped.
#' Set to \code{NULL} to disable early stopping and force evaluation of
#' all candidates up to \code{max_subgroups_search}. Defaults to
#' \code{pconsistency.threshold}, so it tracks the consistency floor
#' automatically if that is changed.
#'
#' \strong{Applies to \code{sg_focus = "maxeffCons"} only.} Early stopping
#' halts the scan and then applies the focus's selection key to the resulting
#' prefix, so it is sound only when that key is fully determined by the
#' enumeration order. \code{Pcons} is not -- it is unknown until a candidate
#' is evaluated -- so any focus whose key contains a \code{Pcons} term can be
#' beaten by a candidate the scan never reached. \code{"maxeffCons"} is the
#' only focus with no such term: its key \code{(-hr, K)} is exactly the
#' enumeration order \code{(-HR, K)}, ties included, so the first qualifying
#' candidate is provably the winner.
#'
#' For every other focus \code{stop_threshold} is reset to \code{NULL}, with a
#' warning if it was supplied explicitly:
#' \itemize{
#' \item \code{"hr"} (\code{"eff"}, \code{"maxcons"}) selects on
#' \code{Pcons} directly;
#' \item \code{"maxSG"} / \code{"minSG"} use \code{Pcons} to break ties in
#' subgroup size, which a truncated scan can miss;
#' \item \code{"hrMaxSG"} / \code{"hrMinSG"} additionally need the whole
#' pool to compute the effect neighborhood;
#' \item \code{"maxeff"} evaluates only its winner, so early stopping has
#' nothing to skip.
#' }
#'
#' \strong{Note:} Values > 1.0 are not permitted. To disable early
#' stopping, use \code{stop_threshold = NULL}, not a value above 1.
#' @param fs.splits Integer. Number of splits for consistency evaluation (or maximum
#' splits when \code{use_twostage = TRUE}). Default 1000.
#' @param m1.threshold Numeric. Maximum median survival threshold. Default Inf.
#' @param pconsistency.threshold Numeric. `p*`, a \strong{proportion} in
#' \code{[0, 1]} -- the fraction of random splits that must be consistent, where a
#' split is consistent when both of its halves clear
#' \code{consistency.threshold} (`c2`). It is a rate, not an effect
#' threshold: it never enters an effect comparison, and unlike `c1` and `c2`
#' it is \strong{not} remapped per estimand -- the same number means the
#' same thing for every \code{outcome_type}. Default 0.90.
#' Overridden to \code{0} under \code{sg_focus = "maxeff"} (no consistency filter).
#' @param pconsistency.digits Integer. Number of decimal places to which the
#' consistency proportion is rounded \strong{before} it is compared with
#' \code{pconsistency.threshold}. The rounded value decides admission and
#' is the value the selection sort orders on, so this setting affects which
#' subgroups are admitted, not only what is displayed. At the default of 2,
#' a threshold of `p*` admits any candidate whose unrounded proportion is at
#' or above the largest 0.01 grid point strictly below `p*` plus half a step
#' (0.005) -- so `p* = 0.99` admits from about 0.985. Raising the setting
#' makes admission finer-grained and produces fewer exact ties for the
#' selection rule to break. Under \code{consistency_method = "resample"}
#' the proportion is a continuous closed-form quantity, so the rounding is a
#' deliberate coarsening rather than a formatting step.
#' Passed to \code{\link{subgroup.consistency}}. Default 2.
#' @param show_candidate_summary Logical. If \code{TRUE}, prints a
#' post-consistency summary table of all passing candidates with
#' Frontier/InBand/Selected flags. See
#' \code{\link{subgroup.consistency}} for details. Default
#' \code{FALSE}.
#' @param max_print Integer. Maximum number of candidate subgroups to print in
#' the pre- and post-consistency candidate summaries when
#' \code{show_candidate_summary = TRUE}. Candidates are printed in sorted
#' order with the selected subgroup first, so \code{max_print = 10} shows the
#' selected subgroup and the next nine, followed by a "... N more not shown"
#' line. Only the per-candidate rows are capped; the banner, header, legend,
#' and summary footer are always printed. Default \code{10} (the selected
#' subgroup and the next nine); use \code{Inf} to print all candidates.
#' @param d0.min Integer. Minimum per-arm filter for candidate subgroups.
#' For \code{"survival"} and \code{"binary"} outcomes, this is the minimum
#' number of events in the control arm (for binary, events are Y = 1).
#' Ignored for \code{"continuous"} outcomes (only \code{n.min} applies).
#' Default 10.
#' @param d1.min Integer. Same as \code{d0.min} for the treatment arm.
#' Default 10.
#' @param max.minutes \strong{Deprecated} (0.4.0.9000): accepted and
#' ignored. It was documented as a wall-clock budget for the
#' combination search but was never enforced in the parallel search
#' path. A non-default value emits one warning. Search scope is governed
#' by \code{maxk}, the candidate-factor front ends (\code{use_grf},
#' \code{use_lasso}, \code{conf_force}) and the number of workers.
#' The formal will be removed in a later release; drop it from calls.
#' @param minp Numeric. Minimum prevalence threshold. Default 0.025.
#' @param details Logical. Print progress details. Default FALSE.
#' @param quiet Logical. If TRUE, suppress the configuration summary
#' message printed at startup. Useful when \code{forestsearch()} is
#' called repeatedly inside bootstrap or cross-validation loops.
#' Default FALSE.
#' @param maxk Integer. Maximum number of factors per subgroup. Default 2.
#' @param by.risk Integer. Risk table interval. Default 12.
#' @param plot.sg Logical. Plot subgroup survival curves. Default FALSE.
#' @param plot.grf Logical. Plot GRF results. Default FALSE.
#' @param max_subgroups_search Numeric. Maximum subgroups to evaluate.
#' \strong{Default \code{Inf}} -- no truncation. The cap has no counterpart
#' in the method: the candidate family is every conjunction of at most two
#' conditions, less empty intersections and size/event failures, and
#' selection ranges over that family. A finite value truncates the pool
#' under a \emph{preview} ordering, so the subgroup that is optimal under
#' the actual criterion can be discarded before it is ever evaluated -- most
#' acutely for the size foci \code{"maxSG"} / \code{"minSG"}, where small
#' high-effect subgroups sort last, and for the band foci
#' \code{"effMaxSG"} / \code{"effMinSG"}. When a finite value does truncate
#' the pool a warning naming both counts is emitted.
#'
#' Set a finite value only to bound runtime, knowing it can change which
#' subgroup is selected. The default was \code{200} in earlier versions.
#' @param vi.grf.min \strong{Deprecated} (0.4.0.9000): accepted and ignored
#' with a warning. GRF variable-importance screening of the candidate cut
#' columns was removed so that the candidate family is the cut grid alone
#' unless \code{use_lasso}, \code{use_grf} or \code{use_dina} is
#' \code{TRUE}. Will be removed in a future release; drop it from the call.
#' @param use_twostage Logical. Use two-stage sequential consistency algorithm for
#' improved performance. Default TRUE. When TRUE,
#' \code{fs.splits} becomes the maximum number of splits, and early stopping
#' is enabled. See Details. Overridden to \code{FALSE} under
#' \code{sg_focus = "maxeff"} (no two-stage screening).
#' @param twostage_args List. Parameters for two-stage algorithm (only used when
#' \code{use_twostage = TRUE}):
#' \describe{
#' \item{n.splits.screen}{Integer. Splits for Stage 1 screening. Default 30.}
#' \item{screen.threshold}{Numeric. Consistency threshold for Stage 1. Default
#' is automatically calculated to provide ~2.5 SE margin.}
#' \item{batch.size}{Integer. Splits per batch in Stage 2. Default 20.}
#' \item{conf.level}{Numeric. Confidence level for early stopping. Default 0.95.}
#' \item{min.valid.screen}{Integer. Minimum valid Stage 1 splits. Default 10.}
#' }
#' @param mr_inference Logical. Whether to follow the search with multiplier
#' resampling (MR): a refit-free de-biased estimate of the selected
#' subgroup's treatment effect, an interval for it, and a harm-confirmation
#' flag. \strong{Default \code{FALSE}}, so by default this function performs
#' \emph{identification only} -- no de-biasing, no harm confirmation, and
#' \code{mr_inference} / \code{mr_harm_confirmed} come back \code{NULL} /
#' \code{NA}. Setting it \code{TRUE} adds a step that runs \emph{after} the
#' subgroup has been chosen and cannot change that choice. Supported on the
#' GLM resample-consistency path (\code{consistency_method = "resample"} with
#' a GLM effect) and on the survival/Cox path
#' (\code{outcome_type = "survival"}), where it runs under the default
#' split-consistency search. MR approximates the full bootstrap
#' (\code{\link{forestsearch_bootstrap_dofuture}}) to leading order and does
#' not replace it. See the vocabulary section.
#' @param mr_inference_args List of optional MR controls; used only when
#' \code{mr_inference = TRUE}.
#' \describe{
#' \item{\code{confirm_rule}}{Which harm-confirmation rule to apply to the
#' de-biased estimate: \code{"point"} (default) compares the de-biased
#' point estimate to \code{t_confirm}; \code{"ci"} compares the one-sided
#' 95% selection-adjusted lower bound, and is therefore the stricter
#' requirement.}
#' \item{\code{t_confirm}}{The threshold \code{confirm_rule} compares
#' against, on the \strong{effect} scale (not the working log scale).
#' \code{NULL} (default) resolves to the null effect: \code{1} for ratio
#' measures, \code{0} for differences. Set near the null rather than at
#' the screening threshold, because the correction over-shrinks true
#' effects.}
#' \item{\code{reselection}}{Which selection rule to replay on each
#' perturbed draw when forming the bias term. Defaults to the rule
#' \code{sg_focus} implies, so it normally needs no setting.}
#' \item{\code{draws}}{Number of multiplier draws. Default \code{2000}.}
#' \item{\code{multiplier}}{Multiplier distribution, default
#' \code{"poisson"} (centred Poisson(1) weights, the multiplier-bootstrap
#' analogue of nonparametric-bootstrap multiplicities); also
#' \code{"gaussian"}, \code{"rademacher"}.}
#' \item{\code{ci_method}}{\code{"field"} (default under
#' \code{subgroup_method = "consistency"}; the \code{"dina"} and
#' \code{"grf"} methods default to \code{"ij"}) additionally runs the
#' field-calibrated block, whose one-sided bounds are the primary
#' reported products; the de-biased element, its infinitesimal-jackknife SE and its
#' IJ intervals are returned in every call regardless, so nothing is
#' removed -- only a per-fit Monte Carlo cost is added. \code{"ij"}
#' restores the previous default: the de-biased interval from the
#' infinitesimal-jackknife variance, the leading-order analogue of the
#' full-bootstrap interval, with the field block omitted.
#' \code{"wald"} uses the subgroup robust SE and also omits the field
#' block. The naive interval always uses the robust SE.}
#' \item{\code{include_complement}}{Also de-bias the complement subgroup.
#' Passed as \code{TRUE} by every internal caller.}
#' \item{\code{seed}}{Seed for the multiplier draws; defaults to
#' \code{seedit}.}
#' \item{\code{return_reselection}}{Logical, default \code{TRUE}. When
#' \code{TRUE} the gate's return gains the \code{reselection} element
#' (per-draw winners and the re-selection frequencies \code{p_hat});
#' nothing in the arithmetic depends on it, and \code{FALSE} restores
#' the smaller return object.}
#' \item{\code{field_M_cap}}{Optional override of the uniform (kappa)
#' sweep's mass-carrying cap; \code{NULL} (default) keeps
#' \code{fs_mr_field_uniform()}'s default. Consulted only when
#' \code{field_uniform = TRUE}.}
#' \item{\code{field_complement}}{Logical, default \code{TRUE}. Under
#' \code{ci_method = "field"} with \code{include_complement = TRUE},
#' also evaluate the field block for the complement subgroup, attached
#' as \code{field$complement} with the one-sided 95\% \emph{upper}
#' bound as its primary product (the benefit-claim orientation; see
#' \code{\link{fs_mr_inference}}). \code{FALSE} omits the complement's
#' field block (the prior behaviour).}
#' \item{\code{ij_residual}}{\code{"two_term"} (default), \code{"winner"}
#' or \code{"winner_floor"}: which infinitesimal-jackknife residual
#' populates the reported de-biased SE and interval (both blocks); all
#' three SEs are returned side by side regardless (see
#' \code{\link{fs_mr_inference}}). Add-only pass-through: the default
#' reproduces prior output exactly.}
#' \item{\code{keep_declaration_field}, \code{keep_field_matrix}}{Logical,
#' both default \code{FALSE}. Retain the standardized perturbation
#' field that \code{\link{fs_declaration_calibration}} reads, as
#' \code{mr_inference$declaration_field}; \code{keep_field_matrix}
#' additionally keeps the full draws-by-candidates matrix (needed for
#' \code{family = "reduced"}). Add-only pass-through: unset, nothing is
#' computed or stored and the default reproduces prior output exactly.}
#' \item{\code{declaration_c0}}{\code{NULL} (default) or a numeric vector
#' of pre-specified protected null levels \code{c0} on the natural scale
#' of \code{hr.consistency} (\code{c0 <= c2}); consulted only with
#' \code{keep_declaration_field = TRUE}. The capture then also stores
#' the shifted family maxima \code{Mstar_c0} that
#' \code{fs_declaration_calibration(fit, c0 = )} reads (see
#' \code{\link{fs_mr_inference}}). Add-only pass-through: unset,
#' nothing is computed or stored.}
#' }
#' @param consistency_method Character. \code{"resample"} (default) uses the
#' multiplier (influence-function / \code{dfbeta}) approximation
#' (\code{\link{consistency_resample}}), returning the rate from a single
#' subgroup fit; \code{"split"} is retained as the fallback and runs the
#' literal repeated 50/50 split-and-refit calculation, which costs
#' \code{fs.splits * 2} refits per candidate evaluation. Despite the name, \code{"resample"} performs no
#' numerical resampling at evaluation time -- the rate is a closed-form
#' expression. The name reflects the method's derivation: the repeated-split
#' consistency rate admits an equivalent multiplier-resampling (MR)
#' representation, and taking that representation to its analytic limit
#' yields the closed form implemented here. The \code{"resample"} path applies to the Cox
#' (survival) outcome and to GLM outcomes whose effect is a single model
#' coefficient (OR, RR, RD, MD, IRR); an IRD effect, or a candidate whose
#' closed form is not available (for example a non-convergent fit), falls
#' back to \code{"split"} automatically. The route is decided by the
#' effect measure alone: propensity adjustment
#' (\code{ps_adjust_method = "iptw"} or \code{"dr_gcomp"}, with
#' \code{ps_method} other than \code{"none"}) does not send a supported
#' measure to \code{"split"}. Under propensity adjustment the
#' closed form fits the treatment effect without the propensity weights,
#' and without covariates (\code{adjust_covariates} cannot be combined with
#' \code{ps_method} other than \code{"none"}), so the consistency rate is
#' that of the unadjusted effect. When
#' \code{use_twostage = TRUE}, \code{"resample"} bypasses the two-stage
#' split screening entirely (the rate is computed directly).
#' A sequential and a parallel plan can give different consistency
#' proportions, and possibly a different selection, whenever literal
#' splitting runs (\code{consistency_method = "split"}, an incidence-rate
#' difference (\code{effect_measure = "IRD"}) under \code{"resample"}, or a
#' candidate whose closed form is not available), except under
#' \code{sg_focus = "maxeff"}, which runs the same loop on every plan.
#' @param outcome_type Character. One of \code{"survival"} (default),
#' \code{"binary"}, \code{"continuous"}, or \code{"count"}.
#' @param effect_measure Character or \code{NULL}. Effect measure for GLM
#' outcomes. For binary: \code{"OR"} (default), \code{"RD"},
#' \code{"RR"}, \code{"IRR"}, \code{"IRD"}. For continuous:
#' \code{"MD"} (default). For count: \code{"IRR"} (default),
#' \code{"IRD"}. \code{NULL} resolves to the per-outcome default shown
#' here; the resolved measure then fixes the scale on which
#' \code{effect.threshold} and \code{consistency.threshold} are compared
#' -- log for the ratio measures (\code{"OR"}, \code{"RR"},
#' \code{"IRR"}), identity for \code{"RD"}, \code{"IRD"} and
#' \code{"MD"} -- so an unset binary call screens on log(1.25) rather
#' than 0.05. See the \emph{Threshold vocabulary and resolved defaults}
#' section. Ignored for \code{outcome_type = "survival"}, which always
#' uses the hazard ratio.
#' @param offset.name Character or \code{NULL}. Name of the follow-up time
#' column for rate-based measures (IRR, IRD).
#' @param adverse_outcome Logical or \code{NULL} (default, resolved by
#' outcome type). If \code{TRUE}, higher
#' outcome values indicate harm (default for binary and count). If \code{FALSE},
#' higher values indicate benefit (default for continuous).
#' @param overdispersion Character. Overdispersion correction for
#' \code{outcome_type = "count"}. One of \code{"none"} (default,
#' standard Poisson), \code{"quasi"} (quasi-Poisson), or \code{"negbin"}
#' (negative binomial via \code{MASS::glm.nb}). Ignored for other
#' outcome types.
#' @param grf_count_transform Character. Transformation applied to the
#' count outcome before passing to \code{grf::causal_forest()} for
#' factor screening. \code{"log"} (default) applies
#' \eqn{\log(Y + 0.5)}; \code{"identity"} passes raw counts.
#' Ignored for non-count outcomes.
#' @param tune_grf Logical. If \code{TRUE}, enables cross-validated
#' hyperparameter tuning for GRF's \code{causal_forest()} via
#' \code{tune.parameters = "all"}. If \code{FALSE} (default), all
#' GRF parameters remain at their defaults, preserving existing
#' behavior. Applies to both internal GRF pre-screening and
#' standalone GRF analysis when passed through
#' \code{run_simulation_analysis()}.
#' @param adjust_covariates This option is implemented but has not been
#' tested against the manuscript analyses or the simulation studies of
#' León and Anderson (2026a, 2026b), which use the unadjusted
#' treatment-only fits.
#' Character vector or \code{NULL}. Additional terms
#' used to adjust the Cox model that scores survival subgroups during
#' consistency evaluation. Terms are appended verbatim to the model
#' right-hand side after the treatment term, so survival modelling helpers
#' may be used directly: \code{adjust_covariates = "strata(x1)"} fits a
#' model stratified by \code{x1}, whereas \code{adjust_covariates = "x1"}
#' includes \code{x1} as a linear covariate. The referenced raw columns
#' must be present in \code{df.analysis}; they are carried into the
#' internal scoring frame automatically. Applies to the survival (Cox)
#' consistency path and to GLM outcomes (the effect-estimator closure
#' adds the terms to the outcome model, e.g. logistic for binary/OR).
#' The candidate-search ranking is adjusted on both paths. Mutually
#' exclusive with \code{ps_method != "none"}. Default \code{NULL}
#' (treatment-only, unadjusted -- the previous behaviour).
#' @param ps_method This option is implemented but has not been
#' tested against the manuscript analyses or the simulation studies of
#' León and Anderson (2026a, 2026b), which use the unadjusted
#' treatment-only fits.
#' Character or \code{NULL}. Propensity score estimation
#' method: \code{"grf"}, \code{"lasso"}, \code{"logistic"}, or
#' \code{"none"}. Default: \code{NULL}, which resolves to \code{"none"}
#' for RCT and \code{"grf"} for observational.
#'
#' **GLM outcome types only** (\code{"binary"}, \code{"continuous"},
#' \code{"count"}). Propensity adjustment is **not implemented for
#' \code{outcome_type = "survival"}**: no Cox estimation path reads the
#' resulting weights, so any value other than \code{"none"} is an error there
#' rather than a silent no-op. For confounding control on a survival outcome
#' use \code{adjust_covariates}. Note the default resolves to \code{"grf"}
#' when \code{is.RCT = FALSE}, so an observational survival analysis must
#' pass \code{ps_method = "none"} explicitly.
#' @param ps_adjust_method This option is implemented but has not been
#' tested against the manuscript analyses or the simulation studies of
#' León and Anderson (2026a, 2026b), which use the unadjusted
#' treatment-only fits.
#' Character. PS adjustment method: \code{"none"}
#' (default), \code{"iptw"} (stabilized inverse probability of treatment
#' weights), or \code{"dr_gcomp"} (IPS covariate).
#'
#' **GLM outcome types only**, and consumed only when \code{ps_method} is not
#' \code{"none"} -- it selects how the estimator closure is rebuilt, and that
#' rebuild is GLM-gated. It has no effect on a survival outcome, which is
#' refused at \code{ps_method}.
#' @param ps_hat This option is implemented but has not been
#' tested against the manuscript analyses or the simulation studies of
#' León and Anderson (2026a, 2026b), which use the unadjusted
#' treatment-only fits.
#' Numeric vector or \code{NULL}. User-supplied propensity
#' scores. Must have length equal to \code{nrow(df.analysis)}, and is
#' applied **positionally** to \code{df.analysis}.
#'
#' Not carried into bootstrap replicates or cross-validation folds: a
#' resample has the same row count but different subjects, so a supplied
#' score would be attached to the wrong people. Both re-estimate their own
#' score per replicate/fold under \code{ps_method}.
#'
#' @return A list of class "forestsearch" containing:
#' \describe{
#' \item{grp.consistency}{Consistency evaluation results including:
#' \itemize{
#' \item out_sg: Selected subgroup based on sg_focus
#' \item sg_focus: Focus criterion used
#' \item df_flag: Treatment recommendations
#' \item sg.harm: Subgroup definition labels (character vector
#' of cut names) -- same as the top-level \code{sg.harm}
#' \item sg.harm.id: per-subject 0/1 membership indicator
#' (\emph{not} a character vector of cut expressions; see
#' the \emph{Field naming collision} section below)
#' \item algorithm: "twostage" or "fixed"
#' \item n_candidates_evaluated: Number evaluated
#' \item n_passed: Number passing threshold
#' }}
#' \item{find.grps}{Subgroup search results}
#' \item{confounders.candidate}{Candidate confounders considered}
#' \item{confounders.evaluated}{Confounders after variable selection}
#' \item{df.est}{Analysis data with treatment recommendations}
#' \item{df.predict}{Prediction data with recommendations (if provided)}
#' \item{df.test}{Test data with recommendations (if provided)}
#' \item{minutes_all}{Total computation time}
#' \item{grf_res}{GRF results object}
#' \item{sg_focus}{Subgroup focus criterion used}
#' \item{sg.harm}{Selected subgroup definition -- character vector
#' of factor-level cut names. \strong{Recommended accessor} for
#' displaying the identified subgroup (e.g.,
#' \code{paste(obj$sg.harm, collapse = " & ")}). \code{NULL} if
#' no subgroup was identified.}
#' \item{grf_cuts}{GRF cut points used}
#' \item{prop_maxk}{Proportion of max combinations searched}
#' \item{max_sg_est}{Maximum subgroup HR estimate}
#' \item{grf_plot}{GRF plot object (if plot.grf = TRUE)}
#' \item{args_call_all}{All arguments for reproducibility}
#' \item{threshold_config}{The resolved threshold configuration:
#' \code{outcome_type}, \code{effect_measure}, \code{screening},
#' \code{consistency}, \code{screening_natural},
#' \code{consistency_natural}, \code{scale}, \code{pconsistency} and
#' two description strings. \strong{Read \code{$scale} before reading
#' \code{$screening}.} The phrase "the screening threshold" names two
#' different numbers depending on which object is inspected:
#' \itemize{
#' \item On the \strong{survival} path \code{$screening} is
#' \code{log(hr.threshold)} -- the scale the admission set and
#' multiplier resampling work on -- while the candidate search
#' itself compares the fitted hazard ratio against
#' \code{hr.threshold} on the \strong{natural} scale. The two
#' are the same threshold on two scales, and
#' \code{$screening_natural} holds the search's value.
#' \item On the \strong{GLM} paths \code{$screening} is the value
#' the search compares against directly: the link scale for ratio
#' measures (\code{log} of the supplied ratio) and the identity
#' scale for \code{RD}, \code{IRD} and \code{MD}.
#' }
#' \code{$consistency} follows the same convention, and
#' \code{$pconsistency} is the rate \code{pconsistency.threshold},
#' which has no scale.}
#' \item{family_status}{Character scalar recording whether the candidate
#' family the identifier ranked over is fixed -- the condition
#' multiplier resampling requires (see \code{mr_inference}).
#' \code{"no-front-end"}: \code{subgroup_method = "consistency"} with
#' \code{use_lasso}, \code{use_grf} and \code{use_dina} all
#' \code{FALSE}. Named for what it checks: no fitted model shapes the
#' family on the observed data. This is weaker than the manuscript's
#' Section 2.1 fixed family, which additionally requires resample-
#' invariant cut locations -- quantile-derived cuts are not. \code{"conditional-removable"}: the same method with
#' at least one front end on -- data-dependent, but fixed by turning
#' those off. \code{"conditional-inherent"}: \code{subgroup_method} of
#' \code{"dina"} or \code{"grf"}, where the family is generated by
#' fitting a model to the same data and cannot be made fixed.
#' Descriptive only; it never raises a condition.}
#' \item{mr_inference}{Multiplier-resampling (MR) result, or \code{NULL}
#' when MR did not run. See \code{\link{fs_mr_inference}} for fields
#' (\code{naive}, \code{debiased}, \code{selection_bias},
#' \code{settings}, \code{harm_flag}, \code{timing_seconds}). MR
#' approximates the full bootstrap (FB) to leading order; its interval is
#' the infinitesimal-jackknife analogue of the FB interval under
#' \code{ci_method = "field"} (the default under
#' \code{subgroup_method = "consistency"}) and under \code{"ij"}, and the
#' subgroup robust-SE interval under \code{"wald"}. Under \code{"field"}
#' the return also carries the \code{field} element.}
#' \item{mr_harm_confirmed}{Logical, three-valued. \code{TRUE} when MR ran
#' and the de-biased estimate still indicates harm under
#' \code{confirm_rule}; \code{FALSE} when MR ran and it does not;
#' \code{NA} when MR did \strong{not} run or could not be computed.
#' \code{NA} is therefore \emph{absence of evidence, not evidence
#' against harm} -- test it with \code{is.na()} before
#' \code{isTRUE()}, which collapses \code{NA} to \code{FALSE} and so
#' reports "harm not confirmed" for an analysis that never ran. See
#' the vocabulary section.}
#' }
#'
#' @section Threshold vocabulary and resolved defaults:
#' Three arguments carry thresholds, and two of them have the word
#' "consistency" in the name. They are different quantities:
#'
#' \describe{
#' \item{`c1` -- \code{effect.threshold} (legacy \code{hr.threshold})}{The
#' \strong{screening} threshold on a candidate subgroup's own effect,
#' estimated on the full sample. A candidate must clear it to enter the
#' consistency stage.}
#' \item{`c2` -- \code{consistency.threshold} (legacy
#' \code{hr.consistency})}{An \strong{effect} threshold, applied to the
#' subgroup's effect estimated within each split half. \strong{Not} a
#' proportion, and \strong{not} the consistency rate.}
#' \item{`p*` -- \code{pconsistency.threshold}}{A \strong{proportion} in
#' \code{[0, 1]}: the fraction of splits that must clear `c2`.
#' \strong{Not} an effect threshold.}
#' }
#'
#' In one line: `c2` sets the bar a split half must clear, and `p*` counts how
#' often that bar is met.
#'
#' \strong{Resolved defaults, per estimand.} Reading
#' \code{hr.consistency}'s default as "1.0" is misleading on the GLM paths:
#' when neither threshold is supplied, the value a run actually uses is
#' resolved from the estimand. The resolved pairs are:
#'
#' \tabular{lll}{
#' \strong{resolved estimand} \tab \strong{c1} \tab \strong{c2} \cr
#' \code{HR} (survival) \tab 1.25, compared by the search on the natural HR scale \tab 1.0 \cr
#' \code{OR}, \code{RR}, \code{IRR} \tab log(1.25) \tab log(1.0), i.e. 0 \cr
#' \code{RD} \tab 0.05 \tab 0.0 \cr
#' \code{IRD} \tab 0.01 \tab 0.0 \cr
#' \code{MD} \tab 0.0 \tab 0.0
#' }
#'
#' Supplying \code{effect.threshold} or \code{consistency.threshold} (or the
#' legacy names) suppresses the corresponding default remap, and the supplied
#' value is used on the scale shown above, with one exception: for \code{RD}
#' and \code{IRD} a supplied value greater than 1 is taken to be on a ratio
#' scale and is replaced by the default in the table: \code{effect.threshold}
#' by 0.05 for \code{RD} or 0.01 for \code{IRD}, with two warnings (one from
#' the input check, one from the remap), and \code{consistency.threshold} by
#' 0, with one warning. The remapped \code{effect.threshold}
#' is the value the fit records (in \code{threshold_config} and
#' \code{args_call_all}, which a bootstrap or cross-validation replay
#' re-uses), and it is also the DINA harm floor wherever DINA selects a cut
#' (\code{subgroup_method = "dina"}, or \code{use_dina = TRUE} screening with
#' \code{selected_only = TRUE}): on these two routes \code{RD} and \code{IRD}
#' run with DINA only on the \code{gaussian} family, whose floor is the
#' resolved \code{effect.threshold} (see \code{dina_args}). Screening with
#' \code{selected_only = FALSE} has neither the restriction nor this floor:
#' it contributes the frontier candidate set on any family, for \code{RD} and
#' \code{IRD} too.
#'
#' \strong{The pair rule, on the consistency path with a ratio estimand.} For
#' \code{subgroup_method = "consistency"} with survival (HR) or binary
#' \code{effect_measure = "OR"} -- the two estimands whose `c1` and `c2` sit on
#' one comparable ratio scale -- the two thresholds are treated as a pair:
#'
#' \itemize{
#' \item \code{c2 > c1} is an \strong{error}. It is degenerate: the
#' consistency-stage entry condition re-screens the admitted family on `c2`,
#' so candidates the screen let through are discarded at the stage boundary,
#' and when none survives the consistency stage does not run at all and the
#' fit reads as a finding of no subgroup. \code{c2 = c1} is allowed.
#' \item `c1` supplied \strong{without} `c2` derives
#' \code{c2 = 0.80 * c1} on the \strong{ratio} scale (on the log scale an
#' additive shift of \code{log(0.80)}, never \code{0.80 * log(c1)}):
#' 1.25 -> 1.00, 1.00 -> 0.80, 0.90 -> 0.72. Announced with a message, and
#' carried into every bootstrap replicate and CV fold. The default pair
#' (1.25, 1.0) is the rule's fixed point, so a call that sets neither
#' threshold is unaffected. An explicitly supplied `c2`, in either
#' spelling, is never overridden.
#' \item Supplying both spellings of one threshold at disagreeing values is
#' an error naming both.
#' }
#'
#' Neither rule applies under \code{subgroup_method = "dina"} or
#' \code{"grf"} (which return before the consistency stage and never consult
#' `c2`), nor to the identity-scale estimands \code{RD}, \code{IRD},
#' \code{MD}, nor to \code{IRR}.
#'
#' \code{pconsistency.threshold} is \strong{not} remapped. It is a rate, and
#' it is identical for every \code{outcome_type} and every estimand.
#'
#' @section Field naming collision with GRF results:
#' The top-level \code{sg.harm} on this object and the
#' \code{grp.consistency$sg.harm} nested field both hold a character
#' vector of cut expressions. The nested \code{grp.consistency$sg.harm.id}
#' field holds a \emph{per-subject 0/1 membership indicator}, not a cut
#' vector -- unlike \code{sg.harm.id} on GRF result objects, which
#' \emph{does} hold cut expressions. See
#' \code{\link{subgroup.consistency}} and \code{\link{grf.subg.harm.glm}}
#' for the full discussion of this naming collision. Code that must
#' handle both object types should prefer the top-level \code{sg.harm}
#' accessor on forestsearch results.
#'
#' @section Vocabulary FB MR and harm confirmation:
#' Four different things in this package used to share the word "gate". They
#' are distinct, they happen at different stages, and only the last one is a
#' pass/fail decision:
#'
#' \describe{
#' \item{Admissibility criteria}{Which candidate subgroups are even eligible
#' to be considered: \code{hr.threshold}, \code{pconsistency.threshold},
#' \code{n.min}, \code{d0.min}, \code{d1.min}, \code{maxk}. Applied during
#' the search.}
#' \item{Selection rule}{Which admissible candidate is chosen as the
#' estimated subgroup: \code{sg_focus}. Applied during the search.}
#' \item{Post-selection inference}{Correcting the chosen subgroup's treatment
#' effect for the optimism of having chosen it, and putting an interval
#' around the corrected value. This is FB and MR below. Applied
#' \emph{after} the search.}
#' \item{Harm confirmation}{The one pass/fail: does the corrected estimate
#' still indicate harm? This is \code{confirm_rule} against
#' \code{t_confirm}, reported as \code{mr_harm_confirmed}.}
#' }
#'
#' \strong{Full bootstrap (FB)} --- \code{\link{forestsearch_bootstrap_dofuture}}.
#' Resamples \emph{subjects}, and re-runs the entire subgroup search inside
#' every replicate, so the replicate may select a different subgroup than the
#' original analysis did. That is what lets it correct the selection-induced
#' bias in the reported treatment effect, and supply an
#' infinitesimal-jackknife interval. It is the reference method, and it is
#' expensive: cost scales with \code{nb_boots} times the cost of one search.
#'
#' \strong{Multiplier resampling (MR)} --- \code{\link{fs_mr_inference}}, turned
#' on by \code{mr_inference = TRUE}. Resamples nothing; it perturbs the
#' per-subject influence contributions (\code{dfbeta}) of a \emph{single} set of
#' fits with random mean-zero multipliers, and re-applies the selection rule on
#' each perturbed draw. It corrects the same selection bias FB corrects and
#' produces the same kind of interval, to leading order, at a small fraction of
#' the cost --- no refits. MR is \strong{post-selection inference on a
#' completed analysis}: it runs after the subgroup has been chosen and
#' \strong{cannot change which subgroup is identified}. Running with
#' \code{mr_inference = TRUE} and \code{FALSE} gives identical
#' \code{sg.harm}, \code{df.est} and \code{max_sg_est}. MR approximates FB;
#' it does not replace it.
#'
#' \strong{Harm confirmation.} Once MR has produced a de-biased estimate,
#' \code{mr_inference_args$confirm_rule} decides whether that estimate still
#' indicates harm:
#' \describe{
#' \item{\code{"point"} (default)}{Compares the de-biased \emph{point
#' estimate} to \code{t_confirm}.}
#' \item{\code{"ci"}}{Compares the one-sided 95% selection-adjusted
#' \emph{lower bound} to \code{t_confirm}. Strictly the stronger
#' requirement, so anything it confirms \code{"point"} also confirms.}
#' }
#'
#' \strong{\code{t_confirm}} is the threshold those rules compare against, on
#' the \strong{effect} scale (HR, OR, RR, IRR; or RD, MD for differences) ---
#' not the working log scale used internally. Left \code{NULL} it resolves to
#' the null effect: \code{1} for ratio measures, \code{0} for differences. It
#' is deliberately set near the null rather than at \code{hr.threshold},
#' because the de-biasing correction over-shrinks genuine effects, so
#' re-applying the screening threshold to a corrected estimate would discard
#' true findings.
#'
#' \strong{\code{mr_harm_confirmed}} carries the answer, and is three-valued:
#' \code{TRUE} = MR ran and harm is confirmed; \code{FALSE} = MR ran and harm
#' is not confirmed; \code{NA} = MR did not run, or could not be computed.
#' \strong{\code{NA} is not evidence against harm.} It arises when
#' \code{mr_inference = FALSE} (the default), when no subgroup was identified,
#' or when the MR step was skipped or failed for the outcome/consistency
#' combination in use. Because \code{isTRUE(NA)} is \code{FALSE}, code that
#' reads this field with \code{isTRUE()} alone silently reports "harm not
#' confirmed" for an analysis that was never performed; branch on
#' \code{is.na()} first.
#'
#' @details
#' \strong{Algorithm Overview:}
#' \enumerate{
#' \item \strong{Variable Selection}: GRF identifies variables with treatment
#' effect heterogeneity; LASSO selects most predictive
#' \item \strong{Subgroup Discovery}: Exhaustive search over factor combinations
#' up to \code{maxk}
#' \item \strong{Consistency Validation}: Split-sample validation ensures
#' reproducibility
#' \item \strong{Selection}: Choose subgroup based on \code{sg_focus} criterion
#' }
#'
#' \strong{Two-Stage Consistency Algorithm:}
#' When \code{use_twostage = TRUE}, the consistency evaluation uses an optimized
#' algorithm that can provide 3-10x speedup:
#' \itemize{
#' \item \strong{Stage 1}: Quick screening with \code{n.splits.screen} splits
#' eliminates clearly non-viable candidates
#' \item \strong{Stage 2}: Sequential batched evaluation with early stopping
#' for candidates passing Stage 1
#' }
#'
#' The two-stage algorithm is recommended for:
#' \itemize{
#' \item Exploratory analyses with many candidate subgroups
#' \item Large \code{fs.splits} values (>200)
#' \item Iterative model development
#' }
#'
#' For final regulatory submissions, \code{use_twostage = FALSE} may be preferred
#' for exact reproducibility.
#'
#' @section Options not tested against the manuscript analyses:
#' The arguments \code{adjust_covariates}, \code{ps_method},
#' \code{ps_adjust_method} and \code{ps_hat} are implemented, but the
#' published analyses and simulation studies of León and Anderson (2026a,
#' 2026b) use the unadjusted treatment-only fits, and no coverage or bias
#' results exist for these paths. They are untested, not known to be wrong.
#' Users who need them should check them on their own data, for example
#' against a direct \code{coxph()} or \code{glm()} fit of the selected
#' subgroup.
#'
#' @examples
#' \dontrun{
#' ## Example 1 -- Survival (GBSG, hormone therapy): the analysis of
#' ## León and Anderson (2026a, Sec. 6) and of the survival-post-selection
#' ## article on the package website. Forest search over the cut grid (no
#' ## model-based front ends), effMaxSG selection in a 10% effect
#' ## neighbourhood, multiplier-resampling inference for the reported
#' ## subgroup computed inside the fit.
#' library(survival)
#' df_gbsg <- within(gbsg, {
#' id <- seq_len(nrow(gbsg))
#' time_months <- rfstime / 30.4375
#' grade3 <- ifelse(grade == "3", 1, 0)
#' })
#' fs_surv <- forestsearch(
#' df.analysis = df_gbsg,
#' outcome.name = "time_months",
#' event.name = "status",
#' treat.name = "hormon",
#' id.name = "id",
#' confounders.name = c("age", "meno", "size", "grade3", "nodes",
#' "pgr", "er"),
#' is.RCT = TRUE,
#' use_lasso = FALSE, use_grf = FALSE, use_dina = FALSE,
#' conf.cont_jcuts = list(er = 10, pgr = 10),
#' conf_force = c("er <= 0", "pgr <= 0"),
#' subgroup_method = "consistency",
#' sg_focus = "effMaxSG",
#' selection_rule = "neighborhood",
#' effect_neighborhood = 0.10,
#' hr.threshold = 1.0,
#' hr.consistency = 1.0,
#' pconsistency.threshold = 0.90,
#' consistency_method = "resample",
#' fs.splits = 1000,
#' n.min = 60, d0.min = 10, d1.min = 10, maxk = 2,
#' mr_inference = TRUE,
#' mr_inference_args = list(draws = 5000L),
#' parallel_args = list(plan = "multisession", workers = 4),
#' seedit = 8316951
#' )
#' print(fs_surv)
#'
#' ## mr_estimates_table() lays the multiplier-resampling estimates out in the
#' ## format of the bootstrap tables. A bootstrap template is optional:
#' ## mr_estimates_table(fs_surv) builds the table from fs_surv alone. With a
#' ## template, the descriptive columns come from the bootstrap result (a few
#' ## replicates are enough for the layout; the survival-post-selection
#' ## article compares the two at full size).
#' fs_boot <- forestsearch_bootstrap_dofuture(
#' fs.est = fs_surv,
#' nb_boots = 20,
#' parallel_args = list(plan = "multisession", workers = 4)
#' )
#' mr_estimates_table(fs_surv, boot_results = fs_boot, est.scale = "hr")
#'
#' ## Example 2 -- Binary outcome, odds ratio (ACTG175, ZDV+ddI vs ddI):
#' ## the forest-search analysis of León and Anderson (2026a, Table S3); the
#' ## binary analysis of León and Anderson (2026b) selects the same region
#' ## with effect_neighborhood = 0.20. Adverse-scale outcome (1 = no CD4
#' ## improvement at week 20), OR thresholds at the null, same selection rule
#' ## and multiplier-resampling gate as Example 1.
#' if (requireNamespace("speff2trial", quietly = TRUE)) {
#' actg <- subset(speff2trial::ACTG175, arms %in% c(1L, 3L))
#' actg <- actg[!is.na(actg$cd420), ]
#' actg$id <- seq_len(nrow(actg))
#' actg$treat <- as.integer(actg$arms == 1L)
#' actg$y_binary_neg <- as.integer(!(actg$cd420 > actg$cd40))
#' bin_vars <- c("hemo", "homo", "drugs", "race", "gender", "symptom")
#' for (v in bin_vars) actg[[v]] <- as.numeric(actg[[v]])
#' fs_bin <- forestsearch(
#' df.analysis = actg,
#' outcome.name = "y_binary_neg",
#' event.name = "y_binary_neg",
#' treat.name = "treat",
#' id.name = "id",
#' confounders.name = c("age", "preanti", "wtkg", "karnof", "cd40",
#' "cd80", bin_vars),
#' outcome_type = "binary",
#' effect_measure = "OR",
#' adverse_outcome = TRUE,
#' use_lasso = FALSE, use_grf = FALSE, use_dina = FALSE,
#' conf.cont_jcuts = list(cd40 = 10, wtkg = 10),
#' subgroup_method = "consistency",
#' sg_focus = "effMaxSG",
#' selection_rule = "neighborhood",
#' effect_neighborhood = 0.10,
#' effect.threshold = 1.0,
#' consistency.threshold = 1.0,
#' pconsistency.threshold = 0.90,
#' consistency_method = "resample",
#' fs.splits = 500,
#' n.min = 60, d0.min = 10, d1.min = 10, maxk = 2,
#' mr_inference = TRUE,
#' mr_inference_args = list(draws = 5000L),
#' parallel_args = list(plan = "multisession", workers = 4),
#' seedit = 8316951
#' )
#' print(fs_bin)
#' }
#'
#' ## Example 3 -- Continuous outcome, mean difference (ACTG175): the
#' ## continuous application of León and Anderson (2026b), with the field
#' ## (calibrated one-sided) bounds for the selected subgroup and its
#' ## complement. Outcome is CD4 decline from baseline to week 20 (adverse
#' ## scale); thresholds are on the mean-difference scale.
#' if (requireNamespace("speff2trial", quietly = TRUE)) {
#' actg <- subset(speff2trial::ACTG175, arms %in% c(1L, 3L))
#' actg <- actg[!is.na(actg$cd420), ]
#' actg$id <- seq_len(nrow(actg))
#' actg$treat <- as.integer(actg$arms == 1L)
#' actg$y_decline <- actg$cd40 - actg$cd420
#' bin_vars <- c("hemo", "homo", "drugs", "race", "gender", "symptom")
#' for (v in bin_vars) actg[[v]] <- as.factor(actg[[v]])
#' fs_cont <- forestsearch(
#' df.analysis = actg,
#' outcome.name = "y_decline",
#' treat.name = "treat",
#' id.name = "id",
#' confounders.name = c("age", "preanti", "wtkg", "karnof", "cd40",
#' "cd80", bin_vars),
#' outcome_type = "continuous",
#' effect_measure = "MD",
#' adverse_outcome = TRUE,
#' use_lasso = FALSE, use_grf = FALSE, use_dina = FALSE,
#' conf.cont_jcuts = list(age = 10, preanti = 10, wtkg = 10,
#' karnof = 10, cd40 = 10, cd80 = 10),
#' sg_focus = "effMaxSG",
#' selection_rule = "neighborhood",
#' effect_neighborhood = 0.20,
#' effect.threshold = 10,
#' consistency.threshold = 5,
#' pconsistency.threshold = 0.90,
#' consistency_method = "resample",
#' fs.splits = 500,
#' n.min = 60, d0.min = 10, d1.min = 10, maxk = 2,
#' mr_inference = TRUE,
#' mr_inference_args = list(ci_method = "field", draws = 5000L,
#' include_complement = TRUE,
#' field_complement = TRUE,
#' field_scale_complement = "selected",
#' return_reselection = TRUE),
#' parallel_args = list(plan = "sequential"),
#' seedit = 8316951
#' )
#' print(fs_cont)
#' }
#' }
#'
#' @references
#' \itemize{
#' \item León, L. F. and Anderson, K. M. (2026a). Inference for standard
#' trial estimands after data-driven subgroup discovery.
#' arXiv:2609.38361. \doi{10.48550/arXiv.2609.38361}
#' \item León, L. F. and Anderson, K. M. (2026b). Interpretable subgroup
#' identification across survival and generalized-linear outcomes.
#' arXiv:2610.28379. \doi{10.48550/arXiv.2610.28379}
#' \item FDA Guidance for Industry: Enrichment Strategies for Clinical Trials
#' \item Athey & Imbens (2016). Recursive partitioning for heterogeneous
#' causal effects. PNAS.
#' \item Wager & Athey (2018). Estimation and inference of heterogeneous
#' treatment effects using random forests. JASA.
#' \item León et al. (2024). \doi{10.1002/sim.10163}
#' }
#'
#' @seealso
#' \code{\link{subgroup.consistency}} for consistency evaluation details
#' \code{\link{forestsearch_bootstrap_dofuture}} for the full bootstrap (FB)
#' \code{\link{fs_mr_inference}} for multiplier resampling (MR), the
#' \code{mr_inference = TRUE} step
#' \code{\link{mr_estimates_table}} to render the MR estimates
#' \code{\link{fs_fdr_report}} to sweep harm-confirmation thresholds
#' (\code{c_confirm}) and measure what confirmation buys
#' \code{\link{forestsearch_Kfold}} for cross-validation
#'
#' Package website: \url{https://larry-leon.github.io/forestsearch/}
#'
#' Source code: \url{https://github.com/larry-leon/forestsearch}
#'
#' @importFrom survival coxph Surv
#' @importFrom grf causal_survival_forest variable_importance
#' @importFrom glmnet cv.glmnet
#' @importFrom data.table data.table setorder
#' @importFrom stats quantile sd median
#' @importFrom stats complete.cases
#' @importFrom future.apply future_lapply
#' @importFrom randomForest randomForest
#' @importFrom weightedsurv df_counting
#' @export
forestsearch <- function(df.analysis,
outcome.name = "tte",
event.name = "event",
treat.name = "treat",
id.name = "id",
potentialOutcome.name = NULL,
flag_harm.name = NULL,
confounders.name = NULL,
parallel_args = list(plan = "multisession",
workers = .default_parallel_workers(),
show_message = TRUE),
df.predict = NULL,
df.test = NULL,
is.RCT = TRUE,
seedit = 8316951,
est.scale = "hr",
use_lasso = FALSE,
use_grf = FALSE,
grf_res = NULL,
grf_cuts = NULL,
use_dina = FALSE,
dina_res = NULL,
dina_cuts = NULL,
dina_args = list(),
dina_select_statistic = c("effect", "dina"),
subgroup_method = c("consistency", "dina", "grf"),
max_n_confounders = 1000,
grf_depth = 2,
grf_selection = c("frontier", "tree"),
grf_select_statistic = c("effect", "dr"),
dmin.grf = 0.0,
frac.tau = 0.8,
return_selected_cuts_only = TRUE,
conf_force = NULL,
defaultcut_names = NULL,
cut_type = "default",
exclude_cuts = NULL,
replace_med_grf = FALSE,
cont.cutoff = 4,
conf.cont_medians = NULL,
conf.cont_medians_force = NULL,
conf.cont_jcuts = NULL,
collapse_cuts = TRUE,
collapse_cuts_args = list(),
n.min = 60,
n.min.frac = 0.10,
effect.threshold = NULL,
consistency.threshold = NULL,
hr.threshold = 1.25,
hr.consistency = 1.0,
sg_focus = "hr",
selection_rule = "neighborhood",
effect_neighborhood = 0.10,
fs.splits = 1000,
m1.threshold = Inf,
pconsistency.threshold = 0.90,
# Lazily coupled: a candidate in
# [pconsistency.threshold, stop_threshold) qualifies
# but does not halt the scan, so the two must not
# drift apart. Written as a promise, not a literal,
# so it tracks a user-supplied floor.
stop_threshold = pconsistency.threshold,
pconsistency.digits = 2,
show_candidate_summary = FALSE,
max_print = 10,
d0.min = 10,
d1.min = 10,
max.minutes = 3,
minp = 0.025,
details = FALSE,
quiet = FALSE,
maxk = 2,
by.risk = 12,
plot.sg = FALSE,
plot.grf = FALSE,
max_subgroups_search = Inf,
vi.grf.min = NULL,
# NEW: Two-stage consistency parameters
use_twostage = TRUE,
twostage_args = list(),
consistency_method = c("resample", "split"),
# NEW: GLM outcome support
outcome_type = c("survival", "binary", "continuous",
"count"),
effect_measure = NULL,
offset.name = NULL,
adverse_outcome = NULL,
overdispersion = c("none", "quasi", "negbin"),
grf_count_transform = c("log", "identity"),
tune_grf = FALSE,
# Covariate adjustment for subgroup evaluation (Cox)
adjust_covariates = NULL,
# Propensity score adjustment
ps_method = NULL,
ps_adjust_method = c("none", "iptw", "dr_gcomp"),
ps_hat = NULL,
# Multiplier resampling (optional; GLM resample path)
mr_inference = FALSE,
mr_inference_args = list()) {
.fs_preserve_rng()
# ===========================================================================
# SECTION 1A: RESOLVE FORMAL DEFAULTS BEFORE ARGUMENT CAPTURE
# ===========================================================================
# Resolve match.arg / default-NULL formals up front so the captured
# args_call_all (Section 1B) holds the values that downstream do.call
# sites need. This eliminates the historical pattern of scattered
# args_call_all$X <- X mirror lines for these parameters.
outcome_type <- match.arg(outcome_type)
overdispersion <- match.arg(overdispersion)
grf_count_transform <- match.arg(grf_count_transform)
subgroup_method <- match.arg(subgroup_method)
consistency_method <- match.arg(consistency_method)
# Deprecated arguments (0.4.0.9000): vi.grf.min, max_n_confounders and
# max.minutes are accepted so existing calls do not break, warned about
# once per call, and ignored. GRF variable-importance screening/ordering
# of the candidate cut columns no longer exists: the candidate family is
# the cut grid alone unless use_lasso, use_grf or use_dina asks for a
# model-based front end. max.minutes was never enforced. All three
# formals are removed in a later release. The values are deliberately NOT
# reset, so that args_call_all records what the caller passed.
if (!is.null(vi.grf.min)) {
warning("forestsearch(): 'vi.grf.min' is deprecated and ignored. GRF ",
"variable-importance screening of the candidate cut columns was ",
"removed; the candidate family is the cut grid alone unless ",
"use_lasso, use_grf or use_dina is TRUE. The argument will be ",
"removed in a future release -- drop it from the call.",
call. = FALSE)
}
if (!missing(max_n_confounders) &&
!identical(as.numeric(max_n_confounders), 1000)) {
warning("forestsearch(): 'max_n_confounders' is deprecated and ignored ",
"(it capped the variable-importance-ordered column list, which ",
"no longer exists). It will be removed in a future release -- ",
"drop it from the call.", call. = FALSE)
}
# Value trigger (not bare !missing()): args_call_all always carries
# max.minutes, and bootstrap/CV replay it via do.call(forestsearch, ...).
if (!missing(max.minutes) &&
!identical(as.numeric(max.minutes), 3)) {
warning("forestsearch(): 'max.minutes' is deprecated and ignored. The ",
"wall-clock budget was never enforced in the parallel search; ",
"scope is governed by maxk and the candidate-factor controls. ",
"The argument will be removed in a future release -- drop it ",
"from the call.", call. = FALSE)
}
# DINA's selector statistic is a first-class argument, mirroring
# `grf_select_statistic`. It is normalized here and injected as the canonical
# value into `dina_args`, which `.resolve_dina_args()` reads, so every
# downstream DINA site sees a single source of truth. A value supplied the
# old way (inside `dina_args$select_statistic`) is deprecated: it is honoured
# for one cycle but overridden by the top-level argument, with a warning.
dina_select_statistic <- match.arg(dina_select_statistic)
if (is.null(dina_args)) dina_args <- list()
if (!is.list(dina_args)) {
stop("`dina_args` must be a list.", call. = FALSE)
}
if (!is.null(dina_args[["select_statistic"]]) &&
!identical(dina_args[["select_statistic"]], dina_select_statistic)) {
warning("`dina_args$select_statistic` is deprecated; use the top-level ",
"`dina_select_statistic` argument (mirrors `grf_select_statistic`)",
". The top-level value is used.", call. = FALSE)
}
dina_args[["select_statistic"]] <- dina_select_statistic
if (outcome_type != "survival" && is.null(effect_measure)) {
effect_measure <- switch(outcome_type,
binary = "OR",
continuous = "MD",
count = "IRR"
)
}
if (is.null(adverse_outcome)) {
adverse_outcome <- (outcome_type %in% c("binary", "count"))
}
# Threshold aliases: effect.threshold / consistency.threshold are the
# preferred names; hr.threshold / hr.consistency are retained for
# backward compatibility. New names take precedence when both are
# provided.
user_set_threshold <- !is.null(effect.threshold) || !missing(hr.threshold)
user_set_consistency <- !is.null(consistency.threshold) || !missing(hr.consistency)
# Captured BEFORE the merge overwrites them, so SECTION 1A3 can tell a
# caller who wrote both spellings of one quantity from one who wrote either.
.fs_c1_legacy <- if (missing(hr.threshold)) NULL else hr.threshold
.fs_c2_legacy <- if (missing(hr.consistency)) NULL else hr.consistency
if (!is.null(effect.threshold)) hr.threshold <- effect.threshold
if (!is.null(consistency.threshold)) hr.consistency <- consistency.threshold
# ===========================================================================
# SECTION 1A3: THE THRESHOLD PAIR -- c2 <= c1 ON THE CONSISTENCY PATH
# ===========================================================================
# c1 admits a candidate to the family; c2 is the per-split floor it must then
# clear. c2 > c1 is degenerate -- the consistency-stage entry condition
# (SECTION 8) re-filters the screened family on c2, so candidates the screen
# admitted are dropped at the stage boundary. Rejected here, ahead of every
# fit, for the consistency path on a ratio estimand (survival HR, binary OR).
# dina and grf return from their own sections without ever consulting c2, and
# RD / IRD / MD / IRR are untouched: see .fs_resolve_threshold_pair().
#
# Placed before the Section 1B capture so the resolved value is captured with
# the rest, and re-synced at SECTION 2B-ii on the spelling a replay detects.
hr.consistency <- .fs_resolve_threshold_pair(
outcome_type = outcome_type, effect_measure = effect_measure,
subgroup_method = subgroup_method, c1 = hr.threshold, c2 = hr.consistency,
c1_new = effect.threshold, c2_new = consistency.threshold,
c1_legacy = .fs_c1_legacy, c2_legacy = .fs_c2_legacy,
user_set_threshold = user_set_threshold,
user_set_consistency = user_set_consistency, quiet = quiet)
# ===========================================================================
# SECTION 1A2: RESOLVE ADAPTIVE n.min (opt-in via n.min = NULL)
# ===========================================================================
# Backward compatible: the default n.min = 60 is unchanged when supplied or
# omitted. Passing n.min = NULL opts into a sample-size-adaptive floor
# n.min <- max(60, ceiling(n.min.frac * N))
# i.e. at least 60, and at least n.min.frac of the analysis sample size N.
# This grows the minimum subgroup size with N to curb false discovery from
# tiny subgroups in large samples. Resolved here (before the args_call_all
# capture below) so the integer value propagates to screening, DINA, GRF,
# the consistency search, and the per-resample bootstrap, and is reported
# in their n.min logging. Guarded on a valid, non-empty df.analysis so the
# zero-row early-exit path is unaffected.
if (is.null(n.min)) {
if (!is.data.frame(df.analysis) || nrow(df.analysis) == 0L) {
n.min <- 60L # degenerate input; zero-row guard below handles the exit
} else {
if (!is.numeric(n.min.frac) || length(n.min.frac) != 1L ||
is.na(n.min.frac) || n.min.frac <= 0 || n.min.frac >= 1) {
stop("n.min.frac must be a single number in (0, 1).", call. = FALSE)
}
N_analysis <- nrow(df.analysis)
n.min <- max(60L, as.integer(ceiling(n.min.frac * N_analysis)))
if (n.min >= N_analysis) {
stop(sprintf(paste0("Adaptive n.min (%d) is >= the analysis sample ",
"size (%d); lower n.min.frac or set n.min ",
"explicitly."), n.min, N_analysis), call. = FALSE)
}
if (!quiet) {
message(sprintf(
"n.min = NULL -> resolved to %d (max(60, ceiling(%.3g * %d))).",
n.min, n.min.frac, N_analysis))
}
}
}
# ===========================================================================
# SECTION 1B: CAPTURE ALL ARGUMENTS FOR REPRODUCIBILITY
# ===========================================================================
# Capture formals only (NOT as.list(environment())): Section 1A binds
# non-formal locals (user_set_threshold, user_set_consistency) before
# this point. args_call_all flows back to bootstrap / CV consumers
# that may reconstruct the call via do.call(forestsearch, args_call_all);
# extra entries would error as 'unused argument'.
args_names <- names(formals())
args_call_all <- mget(args_names, envir = environment())
# ===========================================================================
# SECTION 1B2: MR ALIGNMENT GUARD
# ===========================================================================
# Multiplier resampling linearizes the selection event, which is valid only
# when selection ranks on the inferential coefficient and the candidate
# family is fixed. Checked here, immediately after the capture, so an
# unusable configuration fails before any fitting rather than producing an
# MR correction that silently does not correspond to the reported effect.
# `grf_selection` / `grf_select_statistic` are still unresolved match.arg
# vectors at this point; the validator takes their first element, which is
# what match.arg() would return at :2067-2068.
if (isTRUE(mr_inference)) {
.validate_mr_configuration(args_call_all,
context = "forestsearch(mr_inference = TRUE)")
}
# Descriptive companion to the guard above: record whether the candidate
# family is fixed, so a sweep can tabulate it without parsing text. Never
# raises a condition; carried on the returned object as $family_status.
family_status <- .fs_family_status(args_call_all)
# ===========================================================================
# SECTION 1C: DEFENSIVE EARLY EXITS (shape guards)
# ===========================================================================
# Reject degenerate inputs before any heavy computation. These cases
# produce phantom output (or segfault inside compiled dependencies such
# as glmnet's coxnet_exp on zero-row matrices) if allowed to proceed.
#
# Shape mirrors the get_FSdata-failure early return below (line ~1437):
# list(sg.harm = NULL, args_call_all = ..., error_log = list(...)).
# Downstream consumers (CV, bootstrap) inspect $sg.harm == NULL plus
# $args_call_all to reconstruct calls, so the same shape works here.
# Zero-row input. glmnet::cv.glmnet -> coxnet_exp() segfaults on a
# zero-row design matrix on Linux (the Fortran routine dereferences a
# null pointer); macOS happens to mask this via different allocator
# behaviour but the bug is present on both. Catch it here.
if (!is.data.frame(df.analysis) || nrow(df.analysis) == 0L) {
if (!quiet) {
warning("df.analysis has zero rows; returning early without ",
"running the subgroup search.", call. = FALSE)
}
return(list(
sg.harm = NULL,
args_call_all = args_call_all,
error_log = list(
stage = "input_validation",
message = "df.analysis has zero rows; no subgroup search performed."
)
))
}
# ===========================================================================
# SECTION 2: VALIDATE INPUTS
# ===========================================================================
# Validate selection-related arguments up front, so parameter conflicts
# (e.g., selection_rule = "pareto" with sg_focus = "hr", an unknown
# sg_focus value, or effect_neighborhood out of range) are reported
# immediately rather than after data preparation, factor selection, and
# consistency evaluation have run. The same validators are also called
# inside sort_subgroups() / sort_subgroups_preview() / subgroup.consistency()
# as defense-in-depth (those functions are exported and may be invoked
# directly).
# 1. sg_focus must be one of the known values. Hoisted here so that
# .validate_selection_rule() below sees an already-validated sg_focus.
#
# First normalize the GLM-natural vocabulary (effMaxSG/effMinSG/eff) to
# the canonical internal form (hrMaxSG/hrMinSG/hr). The two
# vocabularies are interchangeable at the user-facing API; internals
# are keyed on the canonical names so all downstream code is unchanged.
# Unrecognized values pass through and are reported by the whitelist
# check below.
sg_focus_user <- sg_focus # save for error message
sg_focus <- .normalize_sg_focus(sg_focus)
# Single source of truth, shared with dina_subgroup()'s whitelist and
# checked against every focus dispatch site by
# .assert_sg_focus_dispatch_complete(). Do not re-inline this vector: the
# duplicate literal here and in dina_subgroup() is exactly how `maxeff` and
# `maxeffCons` came to be whitelisted without dispatch branches.
valid_sg_focus <- .FS_SG_FOCUS_CANONICAL
valid_sg_focus_user <- c(valid_sg_focus,
"eff", "effMaxSG", "effMinSG", "maxcons")
if (!is.character(sg_focus) || length(sg_focus) != 1L ||
!sg_focus %in% valid_sg_focus) {
stop(sprintf(
"'sg_focus' must be one of: %s. Got: %s.",
paste(shQuote(valid_sg_focus_user), collapse = ", "),
if (is.character(sg_focus_user) && length(sg_focus_user) == 1L)
shQuote(sg_focus_user) else "<invalid>"),
call. = FALSE)
}
# Sync the normalized sg_focus back into args_call_all (captured at
# line 714 from the raw formals, BEFORE normalization). Downstream
# consumers -- plot_pareto_combined() in particular reads
# fs$args_call_all$sg_focus to decide whether to draw the
# effect-neighborhood band -- expect the canonical "hr*" form here.
# Without this line, passing sg_focus = "effMaxSG" would store
# "effMaxSG" in args_call_all and downstream feature checks against
# c("hrMaxSG", "hrMinSG") would silently fall through to "no band".
args_call_all$sg_focus <- sg_focus
# Announce the substitution. Both the alias collapse and the DINA/GRF
# effect-argmax collapse were previously silent, so a run requested as
# sg_focus = "eff" ranked under a rule the caller never named and the
# transcript recorded no trace of it. subgroup_method is already resolved
# (match.arg, Section 1A above) and quiet is in scope, so this is the one
# site where both messages can be emitted from a single call.
.announce_sg_focus(sg_focus_user, sg_focus, subgroup_method, quiet)
# 2. selection_rule / sg_focus / effect_neighborhood compatibility.
.validate_selection_rule(selection_rule, sg_focus, effect_neighborhood)
# 3. effect_neighborhood range -- only meaningful for hrMaxSG / hrMinSG
# (matches the existing conditional pattern in sort_subgroups()).
if (sg_focus %in% c("hrMaxSG", "hrMinSG")) {
.validate_effect_neighborhood(effect_neighborhood)
}
# sg_focus = "maxeff" implements Guo & He's argmax primitive: the effect
# maximiser over the enumerated family, subject to NO auxiliary selection
# condition. Consistency screening, effect thresholding, early stopping,
# two-stage pruning and candidate-pool truncation would each change which
# candidate wins (or stop the family being fully evaluated), so all are
# disabled BY CONSTRUCTION rather than left to the caller. Size/event minima
# (n.min, d0.min, d1.min) are retained: they define which candidates are
# estimable, not which one wins. Prevalence (minp) and redundancy (rmin) are
# relaxed to their most permissive setting -- minp -> 0 and rmin -> 0 -- so
# only degenerate candidates (empty cuts, exact duplicates) are pruned: these
# share a retained twin's effect, leaving the argmax invariant, whereas
# dropping distinct near-duplicates would force the (-hr, K) order to break
# genuine ties on cut count, an arbitrary tie-break in a rule meant to have
# none. rmin is applied via search_overrides (not a forestsearch formal).
if (identical(sg_focus, "maxeff")) {
.ov <- character(0)
if (!isTRUE(all.equal(pconsistency.threshold, 0)))
.ov <- c(.ov, "pconsistency.threshold -> 0")
if (!is.null(stop_threshold)) .ov <- c(.ov, "stop_threshold -> NULL")
if (isTRUE(use_twostage)) .ov <- c(.ov, "use_twostage -> FALSE")
if (is.finite(max_subgroups_search))
.ov <- c(.ov, sprintf("max_subgroups_search %g -> Inf", max_subgroups_search))
if (!isTRUE(all.equal(minp, 0))) .ov <- c(.ov, "minp -> 0")
pconsistency.threshold <- 0
stop_threshold <- NULL
use_twostage <- FALSE
max_subgroups_search <- Inf
minp <- 0
if (length(.ov)) {
warning("sg_focus = 'maxeff' selects the effect maximiser with no ",
"auxiliary conditions; overriding: ",
paste(.ov, collapse = ", "),
". The subgroup-search effect floor (hr.threshold) is disabled, ",
"redundancy pruning is relaxed to exact-duplicate removal ",
"(rmin -> 0), and consistency-stage duplicate removal collapses ",
"identical-membership candidates to their fewest-cut ",
"representative -- so the argmax ranges over the full estimable ",
"family with no arbitrary tie-break.",
call. = FALSE)
}
if (identical(consistency_method, "split")) {
warning("sg_focus = 'maxeff' evaluates consistency for EVERY candidate ",
"(no screening, no early stopping, no truncation). With ",
"consistency_method = 'split' that is fs.splits x 2 refits per ",
"candidate and is usually impractical; 'resample' is a single fit ",
"plus a closed form.", call. = FALSE)
}
}
# Which admission floors this (focus, method) applies -- the SAME decision
# MR's admission set is built from (.fs_resolve_admission()). The identifier
# sites below read it rather than re-testing sg_focus, so the identifier and
# MR cannot disagree about which floors are in force.
.admit_applies <- .fs_admission_applies(sg_focus, subgroup_method)
# Validate parallel arguments
if (length(parallel_args) > 0) {
allowed_plans <- c("multisession", "multicore", "callr", "sequential")
plan_type <- parallel_args$plan
n_workers <- parallel_args$workers
max_cores <- parallel::detectCores()
if (is.null(plan_type)) {
stop("parallel_args$plan must be specified.")
}
if (!plan_type %in% allowed_plans) {
stop("plan_type must be one of: ", paste(allowed_plans, collapse = ", "))
}
if (is.null(n_workers) || !is.numeric(n_workers) || n_workers < 1) {
n_workers <- 1
} else {
n_workers <- min(n_workers, max_cores)
}
# Hoisted from subgroup.consistency() so an invalid batch_size errors
# before any data preparation runs. NULL means "use default downstream";
# the original validator (still in place as defense-in-depth) is invoked
# only when the value is actually consumed.
if (!is.null(parallel_args$batch_size) &&
(!is.numeric(parallel_args$batch_size) ||
length(parallel_args$batch_size) != 1L ||
is.na(parallel_args$batch_size) ||
parallel_args$batch_size < 1 ||
parallel_args$batch_size != as.integer(parallel_args$batch_size))) {
stop("parallel_args$batch_size must be a positive integer.",
call. = FALSE)
}
}
# Early stopping halts the candidate scan at the first candidate reaching
# stop_threshold, then applies the focus's own key to that PREFIX. For the
# prefix winner to be the global winner, the key must be fully determined by
# quantities the enumeration order already fixes. Pcons is not: it is only
# known after a candidate is evaluated. So early stopping is sound only for a
# focus whose selection key contains NO Pcons term at all -- and among the
# consistency-engine foci that is maxeffCons alone (key (-hr, K), enumerated
# (-HR, K): the same ordering, ties included).
#
# A key with Pcons merely SECONDARY is still unsound, because ties in the
# primary term expose it. For minSG (key (N, -Pcons, K), enumerated (n, K)):
#
# A: N = 50, K = 1, Pcons = 0.96 <- reaches stop_threshold, loop halts
# B: N = 50, K = 2, Pcons = 0.99 <- never evaluated
#
# The prefix is {A}, so A is returned; the true minSG winner is B, on the
# Pcons tiebreak. No enumeration order can repair this, since Pcons cannot be
# sorted on before it is computed. hr is unsound for the same reason with
# Pcons primary rather than secondary; hrMaxSG / hrMinSG additionally need the
# whole pool to compute the effect band.
#
# Consequence: stop_threshold is meaningful for maxeffCons only.
if (!is.null(stop_threshold) &&
sg_focus %in% c("hrMaxSG", "hrMinSG", "hr", "maxSG", "minSG")) {
# Detect whether user explicitly set stop_threshold (vs. inheriting default)
user_explicit <- !missing(stop_threshold)
if (user_explicit) {
# The reason differs by focus, so state the applicable one rather than
# the band explanation (which only fits hrMaxSG / hrMinSG).
why <- if (sg_focus %in% c("hrMaxSG", "hrMinSG")) {
paste0("Neighborhood-based selection requires evaluating all ",
"candidates to determine the effect-size neighborhood.")
} else if (identical(sg_focus, "hr")) {
paste0("This focus selects on consistency rate (Pcons), which is only ",
"known after a candidate is evaluated, so the highest-Pcons ",
"candidate cannot be found from a truncated scan.")
} else {
paste0("This focus uses Pcons to break ties in subgroup size, and a ",
"truncated scan can halt before a tied candidate with higher ",
"Pcons has been evaluated.")
}
warning(
"stop_threshold = ", stop_threshold,
" reset to NULL for sg_focus = '", sg_focus, "'.\n",
why, "\n",
"Early stopping is available for sg_focus = 'maxeffCons', whose ",
"selection key contains no Pcons term.\n",
"To suppress this warning, pass stop_threshold = NULL explicitly.",
call. = FALSE
)
}
stop_threshold <- NULL
args_call_all <- .sync_args_call_all(args_call_all, environment(),
"stop_threshold")
}
# Validate two-stage parameters
if (!is.logical(use_twostage) || length(use_twostage) != 1) {
stop("'use_twostage' must be a single logical value (TRUE or FALSE)")
}
if (use_twostage && length(twostage_args) > 0) {
valid_ts_args <- c("n.splits.screen", "screen.threshold", "batch.size",
"conf.level", "min.valid.screen")
invalid_args <- setdiff(names(twostage_args), valid_ts_args)
if (length(invalid_args) > 0) {
warning("Unknown twostage_args parameters ignored: ",
paste(invalid_args, collapse = ", "))
}
}
# ===========================================================================
# SECTION 2B: GLM OUTCOME TYPE SETUP
# ===========================================================================
outcome_type <- match.arg(outcome_type)
overdispersion <- match.arg(overdispersion)
grf_count_transform <- match.arg(grf_count_transform)
# ===========================================================================
# SECTION 2B-i: VALIDATE OUTCOME / THRESHOLD CONSISTENCY
# ===========================================================================
# Catch common misconfigurations before they produce silent nonsense.
.validate_outcome_threshold_config(
df.analysis = df.analysis,
outcome.name = outcome.name,
event.name = event.name,
outcome_type = outcome_type,
effect_measure = if (exists("effect_measure")) effect_measure else NULL,
hr.threshold = hr.threshold,
hr.consistency = hr.consistency,
user_set_threshold = user_set_threshold,
user_set_consistency = user_set_consistency
)
# Resolve adverse_outcome default:
# Binary outcomes: TRUE (event = adverse, the clinical trial convention)
# Count outcomes: TRUE (higher count = more events = worse)
# Continuous outcomes: FALSE (user must set TRUE if higher Y = worse)
# Survival: not used (causal_survival_forest handles sign correctly)
if (is.null(adverse_outcome)) {
adverse_outcome <- (outcome_type %in% c("binary", "count"))
}
# Build effect estimator closure for non-survival outcomes
estimator_fn <- NULL
consistency_threshold <- NULL
effect_threshold <- NULL
if (outcome_type != "survival") {
# Validate offset requirement for rate-based measures
if (effect_measure %in% c("IRR", "IRD") && is.null(offset.name)) {
stop(
"effect_measure = '", effect_measure,
"' requires `offset.name` (follow-up time column).",
call. = FALSE
)
}
# Build the estimator closure
estimator_fn <- make_effect_estimator(
outcome_type = outcome_type,
treat.name = treat.name,
outcome.name = outcome.name,
event.name = if (outcome_type == "survival") event.name else NULL,
offset.name = offset.name,
effect_measure = effect_measure,
adverse_outcome = adverse_outcome,
adjust_covariates = adjust_covariates
)
# Unadjusted fast path (0.3.3): for the continuous/MD and binary/OR cases with no
# regression adjustment and no propensity adjustment, swap in the
# bit-identical fast closure (.make_lm_estimator_fast: lm.fit + the
# summary.lm/vcov.lm extraction ops). ps_adjust_method is still the
# unresolved formal here (possibly the length-3 default vector, whose
# first element is "none"); if PS adjustment later resolves active, the
# rebuild below (ps_adjust_resolved branch) replaces the closure with an
# untagged slow one, so the tag cannot leak onto a weighted path. The
# attribute is the only signal that travels: the search loop routes its
# per-candidate fit to the vector path on it.
if (identical(ps_adjust_method[[1L]], "none") &&
length(.fs_adjust_terms(adjust_covariates)) == 0L) {
if (outcome_type == "continuous") {
estimator_fn <- .make_lm_estimator_fast(
treat.name = treat.name,
outcome.name = outcome.name,
adverse_outcome = adverse_outcome
)
attr(estimator_fn, "fs_fast_unadjusted") <- TRUE
} else if (outcome_type == "binary" && identical(effect_measure, "OR")) {
# Binary OR twin (0.4.0.9000): same predicate, same tag, bit-identical
# glm.fit closure (.make_glm_or_estimator_fast). RD and RR keep the
# slow closure (their fallback tiers are untouched).
estimator_fn <- .make_glm_or_estimator_fast(
treat.name = treat.name,
outcome.name = outcome.name,
adverse_outcome = adverse_outcome
)
attr(estimator_fn, "fs_fast_unadjusted") <- TRUE
}
}
# Resolve screening and consistency thresholds from effect_measure.
#
# The parameters hr.threshold and hr.consistency are named for the
# survival (hazard ratio) case. For GLM outcomes they serve as
# generic threshold parameters:
# - Ratio-scale measures (OR, RR, IRR): thresholds are on the
# ratio scale (e.g., 1.5 means OR >= 1.5). Converted to log
# internally.
# - Identity-scale measures (RD, IRD, MD): thresholds are on the
# identity scale (e.g., 0.07 means RD >= 7 pct points).
# Values > 1 are nonsensical and trigger a warning.
effect_threshold <- hr.threshold
consistency_threshold <- hr.consistency
if (effect_measure %in% c("RD", "IRD")) {
# Remap survival defaults silently for RD/IRD
if (!user_set_threshold && hr.threshold == 1.25) {
effect_threshold <- switch(effect_measure, RD = 0.05, IRD = 0.01)
}
if (!user_set_consistency && hr.consistency == 1.0) {
consistency_threshold <- 0.0
}
# Detect ratio-scale values passed to identity-scale measure
# NOTE: RD/IRD are probability/rate differences bounded in [-1, 1].
# MD (mean difference) has no natural bounds and is NOT checked here.
if (user_set_threshold && effect_threshold > 1.0) {
# The measure's ratio-scale counterpart, its default and an example:
# RD -> OR, 0.05; IRD -> IRR, 0.01 (?forestsearch, "Resolved defaults,
# per estimand"). The message prints the value the remap assigns.
.fs_remap_ratio <- switch(effect_measure, RD = "OR", IRD = "IRR")
.fs_remap_default <- switch(effect_measure, RD = 0.05, IRD = 0.01)
.fs_remap_example <- switch(effect_measure,
RD = "effect.threshold = 0.07 for a 7 pct-point threshold",
IRD = "effect.threshold = 0.02 for a rate difference of 0.02")
warning(
sprintf(
paste0(
"effect.threshold = %.2f appears to be on a ratio scale, ",
"but effect_measure = '%s' uses the identity scale ",
"(range [-1, 1]).\n",
" Did you mean effect.threshold = %.2f on the %s scale?\n",
" Remapping to default: %.2f.\n",
" To use a custom %s threshold, pass a value in [-1, 1] ",
"(e.g., %s)."),
effect_threshold, effect_measure,
effect_threshold, .fs_remap_ratio, .fs_remap_default,
effect_measure, .fs_remap_example),
call. = FALSE)
effect_threshold <- .fs_remap_default
}
if (consistency_threshold >= 1.0 && !user_set_consistency) {
# Default 1.0 maps to 0.0 ("any harm direction")
consistency_threshold <- 0.0
} else if (consistency_threshold > 1.0) {
warning(
sprintf(
paste0(
"consistency.threshold = %.2f appears to be on a ratio scale, ",
"but effect_measure = '%s' uses the identity scale.\n",
" Remapping to default: 0.0.\n",
" To use a custom %s consistency threshold, pass a value ",
"in [-1, 1]."),
consistency_threshold, effect_measure, effect_measure),
call. = FALSE)
consistency_threshold <- 0.0
}
} else if (effect_measure == "MD") {
# MD (mean difference) is on the natural outcome scale with no
# fixed bounds. Thresholds of 30, 50, etc. are legitimate for
# outcomes like CD4 counts. Only remap survival defaults if
# user didn't explicitly set thresholds.
if (!user_set_threshold && hr.threshold == 1.25) {
# Survival default 1.25 is meaningless for MD; use 0.0
effect_threshold <- 0.0
}
if (!user_set_consistency && hr.consistency == 1.0) {
consistency_threshold <- 0.0
}
} else {
# Log-scale measures (OR, RR, IRR): convert to log scale.
# Ratio measures are positive by definition; non-positive thresholds
# would either fail log() (yielding NaN/-Inf via log(<=0)) or, under
# the prior > 0 guard, pass through unchanged and be silently
# interpreted downstream as already-log-scale values. Either path
# is a silent wrong-answer, so reject explicitly.
if (effect_threshold <= 0) {
stop(
"effect.threshold = ", effect_threshold,
" is invalid for effect_measure = '", effect_measure,
"' (ratio scale). Pass a positive value on the natural ",
"ratio scale (e.g., effect.threshold = 1.25 for ",
effect_measure, " >= 1.25).",
call. = FALSE
)
}
if (consistency_threshold <= 0) {
stop(
"consistency.threshold = ", consistency_threshold,
" is invalid for effect_measure = '", effect_measure,
"' (ratio scale). Pass a positive value on the natural ",
"ratio scale (e.g., consistency.threshold = 1.0 for ",
effect_measure, " >= 1.0 per split).",
call. = FALSE
)
}
effect_threshold <- log(effect_threshold)
consistency_threshold <- log(consistency_threshold)
}
# -----------------------------------------------------------------
# Configuration summary (always printed via message)
# -----------------------------------------------------------------
is_identity <- effect_measure %in% c("RD", "IRD", "MD")
measure_labels <- c(
RD = "Risk Difference", OR = "Odds Ratio", RR = "Risk Ratio",
IRR = "Incidence Rate Ratio", IRD = "Incidence Rate Difference",
MD = "Mean Difference"
)
measure_label <- measure_labels[[effect_measure]]
if (is_identity) {
screen_desc <- sprintf("%.4f", effect_threshold)
consist_desc <- sprintf("%.4f", consistency_threshold)
if (effect_measure == "RD") {
screen_interp <- sprintf(
"treatment increases event probability by >= %.1f pct points",
100 * effect_threshold)
consist_interp <- if (consistency_threshold == 0)
"each split shows any harm direction (RD > 0)"
else sprintf("each split shows RD >= %.1f pct points",
100 * consistency_threshold)
} else {
screen_interp <- sprintf("%s >= %s", effect_measure, screen_desc)
consist_interp <- sprintf("%s >= %s per split",
effect_measure, consist_desc)
}
} else {
# Ratio scale: show on natural scale
screen_nat <- exp(effect_threshold)
consist_nat <- exp(consistency_threshold)
screen_desc <- sprintf("%.2f (log: %.4f)", screen_nat, effect_threshold)
consist_desc <- sprintf("%.2f (log: %.4f)", consist_nat, consistency_threshold)
screen_interp <- sprintf("subgroup %s >= %.2f",
effect_measure, screen_nat)
consist_interp <- sprintf("each split %s >= %.2f",
effect_measure, consist_nat)
}
if (!quiet && subgroup_method != "dina") {
# c2 and p* are echoed here on every path; annotate them where the path
# never reads them (display only -- no value changes).
.c2_note <- .fs_c2_inert_note(subgroup_method)
message(sprintf(paste0(
"\n[forestsearch] Subgroup Identification Configuration\n",
" Outcome type: %s\n",
" Effect measure: %s (%s)\n",
" Scale: %s\n",
"\n",
" Screening: %s >= %s\n",
" Consistency: %s >= %s%s\n",
" Consistency rate threshold: %.0f%%%s\n",
"\n",
" Interpretation:\n",
" Candidates: %s\n",
" Splits: %s%s\n"),
outcome_type, effect_measure, measure_label,
if (is_identity) "identity" else "log (ratio)",
effect_measure, screen_desc,
effect_measure, consist_desc, .c2_note,
100 * pconsistency.threshold, .c2_note,
screen_interp, consist_interp, .c2_note))
}
# Store resolved config for the return object
threshold_config <- list(
outcome_type = outcome_type,
effect_measure = effect_measure,
screening = effect_threshold,
consistency = consistency_threshold,
screening_natural = if (is_identity) effect_threshold
else exp(effect_threshold),
consistency_natural = if (is_identity) consistency_threshold
else exp(consistency_threshold),
scale = if (is_identity) "identity" else "log",
pconsistency = pconsistency.threshold,
screening_description = screen_interp,
consistency_description = consist_interp
)
# Resolve dmin.grf for GLM outcomes.
# dmin.grf is a harm threshold on GRF's doubly robust (DR) scale, not a
# number of events: a subgroup's DR harm effect (mean control DR score
# minus mean treated DR score) must reach it (>= dmin.grf). For survival
# that effect is a difference in restricted mean survival time up to the
# GRF horizon; for GLM outcomes it is a difference on the scale of the
# outcome given to GRF (a probability for binary, outcome units for
# continuous, log(Y + 0.5) or raw counts for count, per
# grf_count_transform), so a value chosen on the RMST scale does not
# carry over. When the user has not supplied a value, use 0.0 (the
# formal default: any non-negative DR harm effect qualifies); a supplied
# value is used as given.
if (missing(dmin.grf)) {
dmin.grf <- 0.0
}
args_call_all <- .sync_args_call_all(args_call_all, environment(),
"dmin.grf")
} else {
# Survival path: print configuration summary
if (!quiet && subgroup_method != "dina") {
.c2_note <- .fs_c2_inert_note(subgroup_method)
message(sprintf(paste0(
"\n[forestsearch] Subgroup Identification Configuration\n",
" Outcome type: survival (Cox PH)\n",
" Effect measure: HR (hazard ratio)\n",
" Scale: log (ratio)\n",
"\n",
" Screening: HR >= %.2f (log: %.4f)\n",
" Consistency: HR >= %.2f (log: %.4f)%s\n",
" Consistency rate threshold: %.0f%%%s\n",
"\n",
" Interpretation:\n",
" Candidates: subgroup hazard ratio >= %.2f\n",
" Splits: each split HR >= %.2f%s\n"),
hr.threshold, log(hr.threshold),
hr.consistency, log(max(hr.consistency, 0.001)), .c2_note,
100 * pconsistency.threshold, .c2_note,
hr.threshold, hr.consistency, .c2_note))
}
# Store resolved config for the return object
threshold_config <- list(
outcome_type = "survival",
effect_measure = "HR",
screening = log(hr.threshold),
consistency = log(max(hr.consistency, 0.001)),
screening_natural = hr.threshold,
consistency_natural = hr.consistency,
scale = "log",
pconsistency = pconsistency.threshold,
screening_description = sprintf(
"subgroup hazard ratio >= %.2f", hr.threshold),
consistency_description = sprintf(
"each split HR >= %.2f", hr.consistency)
)
}
# ===========================================================================
# SECTION 2B-ii: THRESHOLD SYNC -- WHAT A REPLAY MUST RESOLVE
# ===========================================================================
# The two effect thresholds resolve into LOCALS (effect_threshold /
# consistency_threshold) through branches guarded by user_set_threshold /
# user_set_consistency, and those flags are detected with missing() on the
# legacy spellings (:1462-1463). args_call_all captures the FORMALS
# (:1512-1513), and the bootstrap (bootstrap_analysis_dofuture.R:406, 558,
# 614) and the cross-validation (forestsearch_cross_validation.R:345, 479
# and :859, 1001) replay that list with EVERY formal supplied -- so
# missing() is FALSE inside a replicate and user_set_* is TRUE there even
# when this call set neither threshold. On the identity-scale measures that
# made a replicate resolve thresholds its parent never used: RD / IRD / MD
# consistency 1.0 where the fit used 0.0, and MD screening 1.25 where the
# fit used 0.0.
#
# Writing the RESOLVED values, on the natural scale, into the two
# NULL-defaulted spellings fixes it at the source: effect.threshold and
# consistency.threshold are is.null()-detected, so they survive any wrapper,
# and the alias merge at :1464-1465 makes the replay adopt them. This runs
# AFTER resolution and writes only to args_call_all, so THIS fit's resolved
# thresholds are untouched; only a replay sees the difference.
#
# The naturals are taken pre-log (hr.threshold / hr.consistency, which the
# ratio branch at :1986-1987 leaves alone) rather than as
# exp(threshold_config$screening): a replay applies log() again, and an
# exp(log(x)) round-trip is not guaranteed to return x bit-for-bit.
.fs_identity_scale <- outcome_type != "survival" &&
effect_measure %in% c("RD", "IRD", "MD")
effect.threshold <- if (.fs_identity_scale) effect_threshold else hr.threshold
consistency.threshold <- if (.fs_identity_scale) consistency_threshold
else hr.consistency
args_call_all <- .sync_args_call_all(args_call_all, environment(),
c("effect.threshold",
"consistency.threshold"))
# ===========================================================================
# ADMISSION SET -- RESOLVED ONCE
# ===========================================================================
# threshold_config$screening / $consistency are already on the comparison
# scale (log for ratio measures), which is the scale MR's admission set is
# expressed on. Resolving here, once, and carrying the result to every MR
# call site is the point of this object: MR must not rebuild the domain from
# raw parameters, because that is how its admission set drifted from the
# identifier's.
admission_resolved <- .fs_resolve_admission(
sg_focus, subgroup_method,
hr.threshold = threshold_config$screening,
hr.consistency = threshold_config$consistency,
pconsistency.threshold = threshold_config$pconsistency)
# -- Search alignment diagnostic --------------------------------------
# Only print when details = TRUE (single-data exploratory analysis).
# Suppressed during bootstrap, cross-validation, and simulation loops
# where quiet = TRUE or details = FALSE.
search_diag <- interpret_search_config(
outcome_type = if (outcome_type == "survival") "survival"
else outcome_type,
effect_measure = if (outcome_type == "survival") "HR"
else effect_measure,
adverse_outcome = adverse_outcome,
effect_threshold = if (outcome_type == "survival") log(hr.threshold)
else effect_threshold,
consistency_threshold = if (outcome_type == "survival")
log(max(hr.consistency, 0.001))
else consistency_threshold,
use_lasso = use_lasso,
use_grf = use_grf,
outcome.name = outcome.name,
event.name = event.name,
treat.name = treat.name,
offset.name = offset.name,
subgroup_method = subgroup_method,
quiet = !details || quiet || subgroup_method == "dina"
)
# ===========================================================================
# SECTION 2C: PROPENSITY SCORE ESTIMATION (optional)
# ===========================================================================
is_glm <- outcome_type != "survival"
#
# When ps_method != "none", estimate P(W=1|X) and use either:
# - IPTW: stabilized weights in glm (coefficient IS the effect)
# - DR G-comp: Bang & Robins (2005) IPS covariate + G-computation
#
# Defaults:
# RCT = TRUE -> ps_method = "none" (randomization ensures balance)
# RCT = FALSE -> ps_method = "grf" (non-parametric, cross-fitted)
# ps_adjust_method = "none" (default; "iptw" or "dr_gcomp" on request)
# ===========================================================================
# Resolve ps_method default
ps_method_supplied <- !is.null(ps_method)
if (is.null(ps_method)) {
ps_method <- if (is.RCT) "none" else "grf"
}
# PROPENSITY ADJUSTMENT IS NOT IMPLEMENTED FOR SURVIVAL OUTCOMES.
#
# The estimator-closure rebuild below is gated on `if (is_glm)`, and no Cox
# path reads `sw`, `ps_hat` or `ips_covar` -- those three names do not appear
# in any Cox estimation file. So on a survival outcome the score is
# estimated, the columns are attached, and nothing consumes them: the
# estimates are bit-identical to ps_method = "none" at every
# ps_adjust_method, while the returned object still reports the method that
# was asked for.
#
# This errors rather than warning, on the same grounds as F2's silently
# ignored dmin.grf: an adjustment argument that cannot change any result is a
# defect, not a documentation matter, and a warning invites the reader to
# believe there is a setting here worth tuning. There is no configuration in
# which it does something, so there is nothing to tune.
if (!is_glm && !identical(ps_method, "none")) {
stop("ps_method = \"", ps_method, "\" was requested for outcome_type = ",
"\"survival\", but propensity-score adjustment is NOT IMPLEMENTED for ",
"survival outcomes: the score would be estimated and attached to the ",
"data, and no Cox estimation path reads it, so every estimate would be ",
"identical to ps_method = \"none\".\n",
if (!ps_method_supplied)
paste0(" This value was not supplied -- ps_method defaults to ",
"\"grf\" when is.RCT = FALSE. Pass ps_method = \"none\" ",
"explicitly for an observational survival analysis.\n")
else
" Pass ps_method = \"none\", or use a GLM outcome_type.\n",
" For confounding control on a survival outcome, use ",
"adjust_covariates (regression/strata adjustment), which the Cox path ",
"does consume.", call. = FALSE)
}
args_call_all <- .sync_args_call_all(args_call_all, environment(),
"ps_method")
# Resolve ps_adjust_method. NB: the resolved value lives in
# ps_adjust_resolved (used downstream alongside the un-overridden
# ps_adjust_method), so this mirror remains an explicit override
# rather than a .sync_args_call_all() call.
ps_adjust_method <- match.arg(ps_adjust_method)
ps_adjust_resolved <- if (ps_method == "none") "none" else ps_adjust_method
args_call_all$ps_adjust_method <- ps_adjust_resolved
# Regression/strata covariate adjustment (adjust_covariates) and
# propensity-score adjustment are mutually exclusive for now: the PS branch
# below rebuilds the GLM estimator closure around ps_adjust_method only and
# does not also fold in regression covariates. Guard rather than silently
# drop the user's adjust_covariates. (Do NOT reset adjust_covariates here;
# it is a user-facing formal that must flow to df.fs re-attachment and the
# consistency engine.)
if (!is.null(adjust_covariates) && ps_method != "none") {
stop("adjust_covariates cannot be combined with ps_method != 'none'. ",
"Regression/strata adjustment and propensity-score adjustment are ",
"mutually exclusive; choose one.", call. = FALSE)
}
if (ps_method != "none") {
if (!is.null(ps_hat)) {
# User-supplied propensity scores
if (length(ps_hat) != nrow(df.analysis)) {
stop("ps_hat must have length equal to nrow(df.analysis)", call. = FALSE)
}
# Reject values that would produce Inf / NaN IPTW weights downstream.
# The internal estimate_propensity_scores() path trims; the user-
# supplied path bypasses that protection, so guard explicitly.
if (anyNA(ps_hat)) {
stop("ps_hat contains NA values; remove or impute before passing.",
call. = FALSE)
}
if (any(ps_hat <= 0 | ps_hat >= 1)) {
n_bad <- sum(ps_hat <= 0 | ps_hat >= 1)
stop("ps_hat must lie strictly in (0, 1); ", n_bad,
" value(s) outside this range would produce Inf/NaN weights. ",
"Trim or clip ps_hat (e.g., pmin(pmax(ps_hat, 0.01), 0.99)) ",
"before passing.",
call. = FALSE)
}
df.analysis$ps_hat <- ps_hat
W_vec <- df.analysis[[treat.name]]
p_treat <- mean(W_vec, na.rm = TRUE)
df.analysis$sw <- ifelse(W_vec == 1,
p_treat / ps_hat,
(1 - p_treat) / (1 - ps_hat))
df.analysis$ips_covar <- ifelse(W_vec == 1,
1 / ps_hat,
1 / (1 - ps_hat))
} else {
# Estimate PS using the requested method
ps_result <- estimate_propensity_scores(
data = df.analysis,
treat.name = treat.name,
confounders.name = confounders.name,
method = ps_method,
seed = seedit
)
df.analysis <- ps_result$data
if (details) {
cat(" PS estimation: method =", ps_result$method,
", adjust =", ps_adjust_resolved,
", trimmed =", ps_result$trimmed, "\n")
}
}
# Rebuild estimator closure with PS adjustment (GLM outcomes only)
if (is_glm) {
estimator_fn <- make_effect_estimator(
outcome_type = outcome_type,
treat.name = treat.name,
outcome.name = outcome.name,
offset.name = offset.name,
effect_measure = effect_measure,
adverse_outcome = adverse_outcome,
ps_adjust_method = ps_adjust_resolved
)
}
}
args_call_all <- .sync_args_call_all(args_call_all, environment(),
"adjust_covariates")
# ===========================================================================
# SECTION 3: INITIALIZE TIMING AND DATA
# ===========================================================================
t.start_all <- proc.time()[3]
df <- df.analysis
grf_plot <- NULL
if (details && !is.null(conf_force)) {
cat("Forced confounders:", paste(conf_force, collapse = ", "), "\n")
}
# Advisory note: for the effect-band foci, the criterion-optimal subgroup
# can rank below a small candidate cap, so a broad pool is recommended.
if (details &&
.normalize_sg_focus(sg_focus) %in% c("hrMaxSG", "hrMinSG") &&
max_subgroups_search < 30) {
cat("Note: sg_focus = '", sg_focus, "' with max_subgroups_search = ",
max_subgroups_search,
". For effMaxSG/effMinSG the optimal subgroup may rank below the cap; ",
"increasing max_subgroups_search to >= 30 may be necessary.\n",
sep = "")
}
if (details && length(conf.cont_jcuts) > 0L) {
cat("J-quantile cuts:",
paste0(names(conf.cont_jcuts),
" (J=", unlist(conf.cont_jcuts), ")",
collapse = ", "),
"\n")
}
# ===========================================================================
# SECTION 3-DINA: DINA-SELECTION MODE (subgroup_method = "dina")
# ===========================================================================
# Delegate subgroup *selection* to dina_subgroup(), bypassing GRF, LASSO and
# the consistency search. The selected subgroup is returned as sg.harm and
# consumed by the existing (label / treat.recommend-based) estimation and
# bootstrap machinery. Selection criteria are inherited from this call's
# sg_focus / selection_rule / effect_neighborhood / n.min / hr.threshold;
# dina_args supplies only the DINA fit tuning.
if (subgroup_method == "dina") {
dsel <- .forestsearch_dina_select(
df = df, df.predict = df.predict, df.test = df.test,
confounders.name = confounders.name, outcome.name = outcome.name,
event.name = event.name, treat.name = treat.name, id.name = id.name,
outcome_type = outcome_type, hr.threshold = hr.threshold, n.min = n.min,
sg_focus = sg_focus, selection_rule = selection_rule,
effect_neighborhood = effect_neighborhood, dina_args = dina_args,
dina_res = dina_res, seedit = seedit, details = details,
effect_measure = effect_measure, offset.name = offset.name,
adjust_covariates = adjust_covariates,
adverse_outcome = if (identical(outcome_type, "survival")) TRUE
else adverse_outcome,
# The SAME resolved admission set MR re-selects over, so the identifier
# and MR cannot disagree about which candidates were in contention.
admission = admission_resolved,
# Gaussian floor: the resolved threshold (A-001), supplied or not, so
# the fit, the recorded value and a bootstrap / CV replay agree.
effect.threshold = effect.threshold)
t.min_all <- (proc.time()[3] - t.start_all) / 60
if (details) {
if (isTRUE(dsel$found)) {
cat("DINA-selected subgroup:",
paste(dsel$sg.harm, collapse = " & "), "\n")
} else {
cat("DINA selection: no subgroup met the criteria\n")
}
}
out <- list(
grp.consistency = dsel$grp.consistency,
find.grps = NULL,
confounders.candidate = confounders.name,
confounders.evaluated = confounders.name,
df.est = dsel$df.est,
df.predict = dsel$df.predict,
df.test = dsel$df.test,
minutes_all = t.min_all,
grf_res = NULL,
sg_focus = sg_focus,
sg.harm = dsel$sg.harm,
grf_cuts = NULL,
dina_res = dsel$dina_res,
dina_cuts = NULL,
prop_maxk = NA_real_,
max_sg_est = NA_real_,
grf_plot = NULL,
args_call_all = args_call_all,
consistency_algorithm = "dina",
outcome_type = outcome_type,
effect_measure = effect_measure,
threshold_config = if (exists("threshold_config")) threshold_config
else NULL,
subgroup_method = "dina",
family_status = family_status,
admission = admission_resolved
)
# SECTION 9B (DINA): multiplier resampling over DINA's OWN candidate family
# (approach (i)). Re-selection matches the DINA focus rule via sg_focus.
# Defensive: any failure leaves out$mr_inference NULL; DINA output unaffected.
out$mr_inference <- NULL
.mr_dina_ok <- isTRUE(mr_inference) && isTRUE(dsel$found) &&
!is.null(dsel$grp.consistency) &&
!is.null(dsel$grp.consistency$sg.harm.id)
# C.2 -- DINA-selection route.
if (isTRUE(mr_inference) && !.mr_dina_ok)
.mr_skip(quiet,
if (!isTRUE(dsel$found))
"DINA selection identified no subgroup, so there is nothing to de-bias."
else paste0("the DINA selection returned no subgroup membership ",
"(grp.consistency$sg.harm.id is absent)."))
if (.mr_dina_ok) {
# C.1
.mr_announce(quiet,
if (is.null(mr_inference_args$draws)) 2000L
else mr_inference_args$draws)
.mr_df <- dsel$df.est
# Mirror SECTION 9B: survival -> effect_measure "HR" on log scale;
# GLM -> resolved effect_measure (effect_measure is NULL for survival, so
# do NOT test it). The comparison-scale threshold is not rebuilt here:
# it comes from admission_resolved, which .fs_resolve_admission() builds
# once.
.mr_em <- if (identical(outcome_type, "survival")) "HR" else effect_measure
.mr_spec <- .fs_mr_spec(
outcome_type, .mr_em, treat.name, outcome.name, event.name,
offset.name, adjust_covariates,
adverse_outcome = if (identical(outcome_type, "survival")) TRUE
else adverse_outcome,
df = .mr_df)
# MR's family is DINA's qualifying candidates -- the whole of it. This
# is what Algorithm Step 2 specifies, and what the consistency engine
# already does. A former native-statistic band (.fs_mr_restrict_native)
# narrowed it so MR's re-selection neighbourhood would mirror the one
# the full bootstrap explores; MR is not required to mimic FB, and the
# band's premise -- DINA ranking on tau-hat while MR ranks on perturbed
# beta-hat -- no longer holds now that select_statistic = "effect" is
# the default.
.mr_fam <- .fs_mr_family_from_table(.mr_df, dsel$candidates,
op_right = ">=", n_min = n.min)
out$mr_inference <- .fs_apply_mr(
df = .mr_df, candidates = .mr_fam,
selected_members = which(dsel$grp.consistency$sg.harm.id == 1L),
spec = .mr_spec,
# Admission resolved once, not rebuilt here. DINA and GRF have no
# consistency screen, so no consistency term may enter their admission
# set -- previously `c_consistency = 0` with `p_star` still set meant
# t_g carried a z * sigma_D term these engines never applied.
admission = admission_resolved,
effect_neighborhood = effect_neighborhood,
reselection_default = .fs_mr_reselection_from_focus(sg_focus, engine = "effect"),
selection_rule_default = selection_rule,
mr_inference_args = mr_inference_args, seedit = seedit)
}
out$mr_harm_confirmed <- if (!is.null(out$mr_inference))
isTRUE(out$mr_inference$harm_flag) else NA
class(out) <- c("forestsearch", "list")
return(out)
}
# ===========================================================================
# SECTION 3-GRF: GRF-SELECTION MODE (subgroup_method = "grf")
# ===========================================================================
# Delegate subgroup *selection* to the GRF subgroup-identification routine
# (grf.subg.harm.survival / grf.subg.harm.glm), bypassing LASSO/DINA
# screening and the consistency search. The GRF policy-tree harm leaf is
# returned as sg.harm and consumed by the existing (label / treat.recommend-
# based) estimation and bootstrap machinery. The GRF run reuses this call's
# existing GRF arguments (frac.tau, dmin.grf, grf_depth, is.RCT, seedit, and
# the GLM extras); there is no separate grf_args list, mirroring how GRF
# screening is configured.
if (subgroup_method == "grf") {
grf_selection <- match.arg(grf_selection)
grf_select_statistic <- match.arg(grf_select_statistic)
# In frontier mode the selection rule comes from sg_focus (which the tree
# path ignores). An unrecognized value falls back to the robust default
# (effMaxSG). All seven canonical foci have an explicit branch below;
# .assert_sg_focus_dispatch_complete() enforces that they continue to.
#
# `maxeff` and `maxeffCons` are DELIBERATE SYNONYMS on this path, mapping
# to the same plain effect-argmax frontier rule as `hr`. This was a
# decision, not a definitional consequence, so it is recorded here.
#
# "Cons" names the CONSISTENCY floor. For subgroup_method = "consistency",
# maxeffCons keeps both the consistency floor and the effect floor while
# maxeff disables both, so the two are genuinely distinct there and the FS
# path is untouched by this mapping. GRF has no consistency floor -- it
# computes no Pcons and no GRF sort key contains one -- so the "Cons"
# qualifier has nothing to bind to. The two foci could still in principle
# have been separated by the EFFECT floor alone; the decision is that they
# are not. Both range over the identifier's qualifiers with the harm
# floor active.
#
# Basis: manuscript Section 1.1 keeps the harm threshold in the common
# form for all three identifiers, and FS's `maxeff` exists specifically as
# a comparison against Guo & He's argmax primitive -- a purpose with no GRF
# counterpart. The alternative considered and rejected was to let
# `maxeff` disable the effect floor on GRF too, mirroring FS; that would
# have put GRF outside Section 1.1's common harm threshold for the sake of
# a comparison GRF does not participate in.
#
# NO FLOOR IS DISABLED BY THIS MAPPING. .grf_frontier_select()
# (grf_subgroup_labels.R:340) keeps its unconditional
# `elig <- cand[cand$effect >= dmin, ]` filter regardless of rule. The
# collapse raises no condition: it is intended behaviour, and a warning
# would fire on every GRF frontier run under either focus.
# Exhaustive over .FS_SG_FOCUS_CANONICAL, with no default arm. `sg_focus`
# is already normalized AND whitelisted by Section 1A above, so every
# reachable value has a branch and the stop() is unreachable from
# forestsearch() -- it exists so that a focus added to the canonical set
# without a branch here fails loudly instead of silently ranking by
# "effMaxSG", which is what the old default arm did. The previous
# tryCatch(.normalize_sg_focus(...)) is gone with it: re-normalizing a
# value that is canonical by construction only served to swallow errors.
frontier_rule <- switch(sg_focus,
hr = "eff", hrMaxSG = "effMaxSG", hrMinSG = "effMinSG",
maxSG = "maxSG", minSG = "minSG",
maxeff = "eff", maxeffCons = "eff",
stop(sprintf(
paste0("GRF frontier rule: no branch for ",
"sg_focus = '%s'. Every value in ",
".FS_SG_FOCUS_CANONICAL must have one; ",
"see .assert_sg_focus_dispatch_complete()."),
as.character(sg_focus)), call. = FALSE))
gsel <- .forestsearch_grf_select(
df = df, df.predict = df.predict, df.test = df.test,
confounders.name = confounders.name, outcome.name = outcome.name,
event.name = event.name, treat.name = treat.name, id.name = id.name,
outcome_type = outcome_type, n.min = n.min,
frac.tau = frac.tau, dmin.grf = dmin.grf, grf_depth = grf_depth,
is.RCT = is.RCT, adverse_outcome = adverse_outcome,
offset.name = offset.name, overdispersion = overdispersion,
grf_count_transform = grf_count_transform,
grf_res = grf_res, seedit = seedit,
grf_selection = grf_selection, frontier_rule = frontier_rule,
effect_neighborhood = effect_neighborhood, details = details,
# Previously not passed: GRF banded by the multiplicative neighborhood
# regardless of what the caller asked for, while MR's re-selection
# honoured selection_rule -- so identifier and MR could band differently.
selection_rule = selection_rule,
grf_select_statistic = grf_select_statistic,
effect_measure = effect_measure, adjust_covariates = adjust_covariates,
# The SAME resolved admission set MR re-selects over. This replaces the
# hard-coded dmin = 1 inside .grf_reselect_on_effect().
admission = admission_resolved)
t.min_all <- (proc.time()[3] - t.start_all) / 60
if (details) {
if (isTRUE(gsel$found)) {
cat("GRF-selected subgroup:",
paste(gsel$sg.harm, collapse = " & "), "\n")
} else {
cat("GRF selection: no subgroup met the criteria\n")
}
}
out <- list(
grp.consistency = gsel$grp.consistency,
find.grps = NULL,
confounders.candidate = confounders.name,
confounders.evaluated = confounders.name,
df.est = gsel$df.est,
df.predict = gsel$df.predict,
df.test = gsel$df.test,
minutes_all = t.min_all,
grf_res = gsel$grf_res,
sg_focus = sg_focus,
sg.harm = gsel$sg.harm,
grf_cuts = gsel$sg.harm,
dina_res = NULL,
dina_cuts = NULL,
prop_maxk = NA_real_,
max_sg_est = NA_real_,
grf_plot = NULL,
args_call_all = args_call_all,
consistency_algorithm = "grf",
outcome_type = outcome_type,
effect_measure = effect_measure,
threshold_config = if (exists("threshold_config")) threshold_config
else NULL,
subgroup_method = "grf",
family_status = family_status,
admission = admission_resolved
)
# SECTION 9B (GRF): multiplier resampling over GRF's OWN DR-candidate family
# (approach (i)). Frontier ranks this family directly; the policy tree uses
# it as the cut-defined universe. Re-selection matches sg_focus. GRF cut
# operator for non-"left" is ">" (matches .grf_sg_def_from_candidate).
# Defensive: any failure leaves out$mr_inference NULL; GRF output unaffected.
out$mr_inference <- NULL
.mr_grf_ok <- isTRUE(mr_inference) && !is.null(gsel$grp.consistency) &&
!is.null(gsel$grp.consistency$sg.harm.id)
# C.2 -- GRF-selection route (survey finding F4).
if (isTRUE(mr_inference) && !.mr_grf_ok)
.mr_skip(quiet,
paste0("GRF selection produced no subgroup membership ",
"(grp.consistency$sg.harm.id is absent), so there is ",
"nothing to de-bias."))
if (.mr_grf_ok) {
# C.1
.mr_announce(quiet,
if (is.null(mr_inference_args$draws)) 2000L
else mr_inference_args$draws)
.mr_df <- gsel$df.est
# Mirror SECTION 9B (see DINA branch): survival uses "HR", GLM uses
# effect_measure. effect_measure is NULL for survival, so never test it
# directly. The comparison-scale threshold comes from
# admission_resolved, not from a second reconstruction here.
.mr_em <- if (identical(outcome_type, "survival")) "HR" else effect_measure
.mr_spec <- .fs_mr_spec(
outcome_type, .mr_em, treat.name, outcome.name, event.name,
offset.name, adjust_covariates,
adverse_outcome = if (identical(outcome_type, "survival")) TRUE
else adverse_outcome,
df = .mr_df)
# MR's family is GRF's qualifying candidates -- the whole of it. See the
# DINA branch above: the former native-statistic band existed to make
# MR's re-selection mirror the bootstrap's, which MR is not required to
# do, and its premise no longer holds under grf_select_statistic =
# "effect".
.mr_fam <- .fs_mr_family_from_table(.mr_df, gsel$candidates,
op_right = ">", n_min = n.min)
out$mr_inference <- .fs_apply_mr(
df = .mr_df, candidates = .mr_fam,
selected_members = which(gsel$grp.consistency$sg.harm.id == 1L),
spec = .mr_spec,
# Admission resolved once, not rebuilt here. DINA and GRF have no
# consistency screen, so no consistency term may enter their admission
# set -- previously `c_consistency = 0` with `p_star` still set meant
# t_g carried a z * sigma_D term these engines never applied.
admission = admission_resolved,
effect_neighborhood = effect_neighborhood,
reselection_default = .fs_mr_reselection_from_focus(sg_focus, engine = "effect"),
selection_rule_default = selection_rule,
mr_inference_args = mr_inference_args, seedit = seedit)
}
out$mr_harm_confirmed <- if (!is.null(out$mr_inference))
isTRUE(out$mr_inference$harm_flag) else NA
class(out) <- c("forestsearch", "list")
return(out)
}
# ===========================================================================
# SECTION 3A: GRF CUT GENERATION (if use_grf = TRUE)
# ===========================================================================
# If using grf and cuts not already populated, run GRF subgroup identification
if (use_grf && (is.null(grf_res) || is.null(grf_res$tree.cuts))) {
grf_res <- tryCatch({
# Argument-list construction is delegated to the internal builders
# in R/grf_args.R so the public extract_grf_args() and the call
# site here cannot drift.
if (outcome_type == "survival") {
surv_args <- .build_grf_survival_args(
data = df.analysis,
confounders.name = confounders.name,
outcome.name = outcome.name,
event.name = event.name,
id.name = id.name,
treat.name = treat.name,
frac.tau = frac.tau,
n.min = n.min,
dmin.grf = dmin.grf,
is.RCT = is.RCT,
grf_depth = grf_depth,
seedit = seedit,
return_selected_cuts_only = return_selected_cuts_only
)
do.call(grf.subg.harm.survival, surv_args)
} else {
glm_args <- .build_grf_glm_args(
data = df.analysis,
confounders.name = confounders.name,
outcome.name = outcome.name,
treat.name = treat.name,
id.name = id.name,
outcome_type = outcome_type,
n.min = n.min,
dmin.grf = dmin.grf,
is.RCT = is.RCT,
grf_depth = grf_depth,
seedit = seedit,
return_selected_cuts_only = return_selected_cuts_only,
adverse_outcome = adverse_outcome,
offset.name = offset.name,
overdispersion = overdispersion,
grf_count_transform = grf_count_transform
)
do.call(grf.subg.harm.glm, glm_args)
}
},
error = function(e) {
warning("GRF analysis failed: ", e$message)
return(NULL)
}
)
# Extract GRF cuts if successful
if (!is.null(grf_res) && !inherits(grf_res, "try-error")) {
grf_cuts <- grf_res$tree.cuts
# GLM GRF returns tree.cuts as a named list of numeric values
# (e.g., list(bm1 = 1, age = c(70, 35))), but get_FSdata expects
# a character vector of cut expressions ("bm1 <= 1", "age <= 70").
# Convert list format to character expression format.
if (is.list(grf_cuts) && !is.null(names(grf_cuts))) {
grf_cuts <- unlist(lapply(names(grf_cuts), function(nm) {
paste0(nm, " <= ", grf_cuts[[nm]])
}))
}
if (details) {
# Concise GRF summary: subgroup found + cuts. tidy_cut_display() is
# display-only (collapses padding, rounds thresholds to integer to match
# collapse_cuts); the underlying grf_cuts / sg.harm.id are unchanged.
grf_sg <- grf_res$sg.harm.id
if (!is.null(grf_sg) && length(grf_sg) > 0 &&
!all(is.na(grf_sg)) && !all(grf_sg == "")) {
cat("GRF subgroup:",
tidy_cut_display(paste(grf_sg, collapse = " & ")), "\n")
} else {
cat("GRF: no subgroup identified\n")
}
cat("GRF cuts identified:", length(grf_cuts), "\n")
if (length(grf_cuts) > 0) {
cat(" Cuts:", paste(tidy_cut_display(grf_cuts), collapse = ", "), "\n")
}
}
# Generate GRF plot if requested
if (plot.grf && !is.null(grf_res$tree)) {
grf_plot <- tryCatch({
plot(grf_res$tree)
}, error = function(e) {
warning("GRF plot failed: ", e$message)
NULL
})
}
} else {
grf_cuts <- NULL
if (details) {
cat("GRF analysis did not produce cuts\n")
}
}
}
# ===========================================================================
# SECTION 3B: DINA CUT GENERATION (if use_dina = TRUE)
# ===========================================================================
# Mirrors SECTION 3A: fit a DINA model on the analysis data and extract a
# per-covariate Pareto frontier as additional screening-stage candidate
# cuts ("x1 <= 0.5"), merged into the candidate pool by get_FSdata()
# exactly as the GRF cuts are. These are candidates, not forced
# selections; the consistency stage remains the gatekeeper.
if (use_dina && is.null(dina_cuts)) {
dina_cuts <- tryCatch({
da <- .resolve_dina_args(dina_args, outcome_type,
n_min_default = n.min,
seed_default = seedit)
# DINA requires numeric covariates. Coerce all-numeric-level factor /
# character candidates to numeric via the shared helper, scoped to a
# local frame so the surrounding consistency search is untouched. This
# is optional screening (the consistency search is the gatekeeper), so a
# genuinely categorical covariate raises inside this tryCatch and is
# reported below as "DINA analysis failed" -- contributing no DINA cuts
# rather than aborting the run (unlike subgroup_method = "dina", where
# DINA is mandatory and the same helper hard-stops).
df.dina <- .coerce_covariates_numeric(df.analysis, confounders.name)
if (is.null(dina_res)) {
# Cox requires a status column; GLM families do not.
status_arg <- if (identical(da$fit$family, "cox")) event.name else NULL
fit_call <- c(
list(df = df.dina, outcome = outcome.name,
treatment = treat.name, covariates = confounders.name,
status = status_arg),
da$fit
)
dina_res <- do.call(dina, fit_call)
}
# .resolve_dina_args() supplies the finite screening caps (3L / 10L)
# explicitly, so this pool is unchanged by dina_frontier()'s Inf
# defaults. Under selected_only = TRUE the table below is discarded in
# favour of the selected cut, so a cap-trim warning would name a display
# nobody sees -- muffle exactly that condition class there, and nothing
# else. Under selected_only = FALSE the caps DO shape the screening
# pool, and the warning stands.
fr <- withCallingHandlers(
do.call(dina_frontier,
c(list(fit = dina_res, df = df.dina,
covariates = confounders.name),
da$frontier)),
dina_frontier_cap_trim = function(w) {
if (isTRUE(da$selected_only)) invokeRestart("muffleWarning")
})
if (isTRUE(da$selected_only)) {
# Selected-cut screening: contribute the SINGLE cut dina_subgroup()
# selects, using forestsearch's own selection criteria with DINA's
# native tau-hat as the effect statistic. That is the cut
# subgroup_method = "dina" would choose only under
# dina_select_statistic = "dina"; under the default "effect" that
# route re-ranks the qualifying family on the inferential effect
# (.dina_reselect_on_effect()), and this step does not. m_diff is the
# harm floor on the link scale: log(hr.threshold) for ratio families
# (cox/binomial/poisson), identity for gaussian. The same refusal the
# subgroup_method = "dina" derivation applies: there is no identity-
# scale number DINA could correctly use on a non-gaussian family.
# This route is optional screening, so the refusal surfaces through
# the enclosing tryCatch as "DINA analysis failed: ..." and the run
# continues with no DINA cuts.
# The gaussian floor is the resolved effect.threshold (SECTION
# 2B-ii), supplied or not: the value the returned object records and
# a replay re-uses (A-001).
.dina_assert_ratio_estimand(da$fit$family, effect_measure)
m_diff_sel <- if (identical(da$fit$family, "gaussian")) {
effect.threshold
} else log(hr.threshold)
sgsel <- dina_subgroup(
fit = dina_res,
df = df.dina,
covariates = confounders.name,
m_diff = m_diff_sel,
n_min = n.min,
max_depth = da$select$max_depth,
grid_probs = da$select$grid_probs,
sg_focus = sg_focus,
selection_rule = selection_rule,
effect_neighborhood = effect_neighborhood,
tau_sign = .dina_tau_sign(outcome_type, adverse_outcome)
)
if (isTRUE(sgsel$found)) {
# Vectorized over the 1-or-2 selected cuts: a depth-2 conjunction
# contributes both component cuts to the screening pool, which the
# consistency search composes as usual.
op_sel <- ifelse(sgsel$direction == "left", "<=", ">=")
paste0(sgsel$covariate, " ", op_sel,
" ", signif(sgsel$threshold, da$frontier$digits))
} else {
character(0)
}
} else {
fr$cut_expr
}
},
error = function(e) {
warning("DINA analysis failed: ", e$message)
return(NULL)
}
)
if (details) {
da_mode <- .resolve_dina_args(dina_args, outcome_type,
n_min_default = n.min, seed_default = seedit)
mode_lbl <- if (isTRUE(da_mode$selected_only))
"selected cut (dina_subgroup, forestsearch criteria)"
else "frontier candidates"
n_dc <- length(dina_cuts)
cat("DINA screening mode:", mode_lbl, "\n")
cat("DINA cuts identified:", n_dc, "\n")
if (n_dc > 0) {
cat(" Cuts:", paste(dina_cuts, collapse = ", "), "\n")
}
}
}
# ===========================================================================
# SECTION 4: DATA PREPARATION (get_FSdata)
# ===========================================================================
# For GLM outcomes, get_FSdata validates that event.name is numeric.
# Map it to something valid so the factor-construction machinery works.
if (outcome_type == "binary") {
# Binary outcome IS the event indicator
if (!event.name %in% names(df.analysis)) {
event.name <- outcome.name
}
} else if (outcome_type %in% c("continuous", "count")) {
# Continuous / count outcomes have no censoring event; create a placeholder
if (!event.name %in% names(df.analysis)) {
df.analysis[[".event_placeholder"]] <- 1L
event.name <- ".event_placeholder"
df <- df.analysis
}
}
# Update args_call_all with resolved event.name for downstream calls
args_call_all <- .sync_args_call_all(args_call_all, environment(),
"event.name")
FSdata <- tryCatch(
do.call(
get_FSdata,
filter_call_args(
args_call_all,
get_FSdata,
list(df.analysis = df.analysis, grf_cuts = grf_cuts,
dina_cuts = dina_cuts,
details = FALSE)
)
),
error = function(e) {
warning("Error in get_FSdata: ", e$message)
return(NULL)
}
)
if (inherits(FSdata, "try-error") || is.null(FSdata)) {
warning("FSdata failure - returning NULL result")
return(list(sg.harm = NULL,
args_call_all = args_call_all,
error_log = list(stage = "get_FSdata",
message = "FSdata returned NULL or error")))
}
# Extract FSdata components
lassoomit <- FSdata$lassoomit
lassokeep <- FSdata$lassokeep
df <- FSdata$df
# Concise LASSO summary
if (details && use_lasso) {
n_kept <- length(lassokeep)
n_total <- n_kept + length(lassoomit)
lasso_label <- switch(outcome_type,
binary = "Logistic-LASSO",
continuous = "Linear-LASSO",
count = "Poisson-LASSO",
"Cox-LASSO"
)
cat(paste0(lasso_label, " selected:"), n_kept, "of", n_total,
"candidate factors\n")
if (length(lassoomit) > 0) {
cat(" Omitted:", paste(lassoomit, collapse = ", "), "\n")
}
}
Y <- df[, outcome.name]
if (outcome_type == "survival") {
Event <- df[, event.name]
} else {
# For GLM outcomes, Event is not meaningful but some downstream
# code references it. Use a vector of 1s as placeholder.
Event <- rep(1L, nrow(df))
}
Treat <- df[, treat.name]
FSconfounders.name <- FSdata$confs_names
confs_labels <- FSdata$confs
if (details) {
cat("Candidate factors:", length(confs_labels), "\n")
print(confs_labels)
}
if (is.null(df.predict)) df.predict <- df
# Candidate cut columns are searched as get_FSdata() built them. The GRF
# variable-importance screening/ordering that stood here before
# 0.4.0.9000 is deprecated (see vi.grf.min): no forest is fitted in the
# forest-search path unless use_lasso, use_grf or use_dina is TRUE.
conf.screen <- FSconfounders.name
# ===========================================================================
# SECTION 6: SUBGROUP SEARCH
# ===========================================================================
# Prepare data for subgroup search
# NOTE: df[, conf.screen] columns are factors with levels {0, 1}.
# dummy() expands each 2-level factor into two indicator columns
# (e.g., q1 -> q1.0, q1.1), so the search explores BOTH directions
# of each cut (subgroup and complement).
df.confounders <- df[, conf.screen, drop = FALSE]
df.confounders <- dummy(df.confounders)
id <- df[, c(id.name)]
df.fs <- data.frame(Y, Event, Treat, id, df.confounders)
Z <- as.matrix(df.confounders)
colnames(Z) <- names(df.confounders)
# For GLM outcomes: the estimator closure expects columns with the original
# names (e.g., "treat", "response"), not the renamed Y/Event/Treat.
# Attach the original columns so the closure can find them.
if (!is.null(estimator_fn)) {
if (!outcome.name %in% names(df.fs) && outcome.name %in% names(df)) {
df.fs[[outcome.name]] <- df[[outcome.name]]
}
if (!treat.name %in% names(df.fs) && treat.name %in% names(df)) {
df.fs[[treat.name]] <- df[[treat.name]]
}
if (!is.null(offset.name) &&
!offset.name %in% names(df.fs) && offset.name %in% names(df)) {
df.fs[[offset.name]] <- df[[offset.name]]
}
}
# Covariate adjustment (Cox / survival path): carry the *raw* columns
# referenced by adjust_covariates onto df.fs so the adjusted scoring
# formula resolves inside the consistency engine. df.fs otherwise keeps
# only Y/Event/Treat/id plus dummied candidate factors, and strata()/
# pspline() terms need the original (un-dichotomised) column. The split
# frames built downstream are row subsets of df.fs and inherit these.
if (!is.null(adjust_covariates)) {
adj_vars <- .fs_adjust_vars(adjust_covariates)
reserved <- c("Y", "Event", "Treat", "id")
bad_reserved <- intersect(adj_vars, reserved)
if (length(bad_reserved) > 0L) {
stop("adjust_covariates may not reference reserved column name(s): ",
paste(bad_reserved, collapse = ", "),
call. = FALSE)
}
missing_adj <- setdiff(adj_vars, names(df))
if (length(missing_adj) > 0L) {
stop("adjust_covariates references column(s) not in the analysis data: ",
paste(missing_adj, collapse = ", "),
call. = FALSE)
}
for (.av in adj_vars) {
df.fs[[.av]] <- df[[.av]]
}
if (details) {
.adj_model <- if (identical(outcome_type, "survival")) "Cox" else "GLM"
cat(" Covariate adjustment (", .adj_model, "): ",
paste(.fs_adjust_terms(adjust_covariates), collapse = " + "), "\n",
sep = "")
}
}
search_overrides <- list(
Y = Y,
Event = Event,
Treat = Treat,
Z = Z,
d0.min = d0.min,
d1.min = d1.min,
n.min = n.min,
hr.threshold = if (!is.null(effect_threshold)) effect_threshold else hr.threshold,
minp = minp,
maxk = maxk,
parallel_workers = 1, # Ensure sequential execution if inside parallel context
details = details, # Optionally suppress details
# maxeff is the unconditional effect maximiser: disable the search
# effect floor so hr.threshold cannot prune the argmax (a threshold
# above the best subgroup effect would otherwise empty the family).
disable_effect_floor = !.admit_applies[["effect"]]
)
# maxeff: relax redundancy pruning to exact-duplicate only. rmin is not a
# forestsearch formal, so it is set here (not in the override block above).
# The default (subgroup.search rmin = 5) is preserved for every other focus.
if (!.admit_applies[["effect"]]) search_overrides$rmin <- 0
# Only pass GLM params when active (same rationale as consistency_overrides)
if (!is.null(estimator_fn)) {
search_overrides$estimator_fn <- estimator_fn
search_overrides$df_analysis <- df
search_overrides$effect_threshold <- effect_threshold
search_overrides$effect_measure <- effect_measure
search_overrides$outcome_type <- outcome_type
}
# Survival covariate adjustment: pass the adjustment terms and a frame that
# carries the raw covariate columns (df.fs, row-aligned with Y/Event/Treat/Z)
# so the candidate-search Cox scorer can adjust consistently with the
# consistency engine. NULL on the GLM path (handled above).
if (is.null(estimator_fn) && !is.null(adjust_covariates)) {
search_overrides$adjust_covariates <- adjust_covariates
search_overrides$df_analysis <- df.fs
}
# Merge and filter arguments
search_args <- modifyList(args_call_all, search_overrides)
# Optionally, filter only valid arguments for subgroup.search
valid_args <- names(formals(subgroup.search))
search_args <- search_args[names(search_args) %in% valid_args]
# max.minutes is deprecated and inert; args_call_all always carries it, so
# drop it here or subgroup.search() would warn on every call.
search_args$max.minutes <- NULL
find.grps <- tryCatch(
do.call(subgroup.search, search_args),
error = function(e) {
warning("Error in subgroup.search: ", e$message)
return(NULL)
}
)
if (is.null(find.grps) || inherits(find.grps, "try-error")) {
warning("Subgroup search failed")
return(list(sg.harm = NULL, args_call_all = args_call_all,
error_log = list(stage = "subgroup.search",
message = "Search returned NULL or error")))
}
# ===========================================================================
# SECTION 7: INITIALIZE OUTPUT VARIABLES
# ===========================================================================
sg.harm <- NULL
df.est_out <- NULL
df.predict_out <- NULL
df.test_out <- NULL
grp.consistency <- NULL
max_sg_est <- find.grps$max_sg_est
prop_maxk <- find.grps$prop_max_count
t.end_all <- proc.time()[3]
t.min_all <- (t.end_all - t.start_all) / 60
# ===========================================================================
# SECTION 8: CHECK FOR VALID SUBGROUPS
# ===========================================================================
has_subgroups <- FALSE
if (!is.null(find.grps) &&
!inherits(find.grps, "try-error") &&
!is.null(find.grps$out.found) &&
!is.null(find.grps$out.found$hr.subgroups)) {
hr_values <- find.grps$out.found$hr.subgroups$HR
# For survival, check HR > hr.consistency (natural scale)
# For GLM, check effect > consistency_threshold (already on correct scale)
check_threshold <- if (!is.null(consistency_threshold)) {
consistency_threshold
} else {
hr.consistency
}
has_subgroups <- any(hr_values > check_threshold, na.rm = TRUE)
}
# ===========================================================================
# SECTION 9: CONSISTENCY EVALUATION (WITH TWO-STAGE OPTION)
# ===========================================================================
if (has_subgroups) {
# Set plotting parameter if needed
if (plot.sg && is.null(by.risk)) {
by.risk <- round(max(Y) / 12, 0)
}
if (details) {
n_candidates <- nrow(find.grps$out.found$hr.subgroups)
cat("# of candidate subgroups (meeting all criteria) =", n_candidates, "\n")
}
# -------------------------------------------------------------------------
# Build arguments for subgroup.consistency
# -------------------------------------------------------------------------
# Base override arguments
consistency_overrides <- list(
df = df.fs,
hr.subgroups = find.grps$out.found$hr.subgroups,
Lsg = find.grps$L,
confs_labels = confs_labels,
n.splits = fs.splits,
stop_Kgroups = max_subgroups_search,
# Pass consistency-gating params from the LOCALS, not args_call_all, so
# sg_focus = "maxeff" overrides (pconsistency.threshold -> 0,
# stop_threshold -> NULL) actually reach the engine. args_call_all is
# not re-synced after the maxeff override block, and filter_call_args
# gives these overrides precedence -- so an omission here silently sends
# the stale user values (0.90 / 0.95) and re-enables filtering + early
# stopping the override promised to disable.
pconsistency.threshold = pconsistency.threshold,
stop_threshold = stop_threshold,
pconsistency.digits = pconsistency.digits,
max_print = max_print,
# NEW: Pass two-stage parameters
use_twostage = use_twostage,
twostage_args = twostage_args,
consistency_method = consistency_method,
# Covariate adjustment for Cox subgroup scoring (NULL on GLM path)
adjust_covariates = if (is.null(estimator_fn)) adjust_covariates else NULL
)
# Only pass GLM closure params when active (non-NULL).
# This ensures the survival path never sends unknown args to
# subgroup.consistency -- critical for compatibility with
# the CRAN-installed version.
if (!is.null(estimator_fn)) {
consistency_overrides$estimator_fn <- estimator_fn
consistency_overrides$consistency_threshold <- consistency_threshold
# The HR column in hr.subgroups contains log-scale values for GLM
# outcomes; hr.threshold must be on the same scale so the re-filtering
# inside subgroup.consistency (line: found.hrs$HR >= hr.threshold) works.
consistency_overrides$hr.threshold <- effect_threshold
# Display labels: use the resolved effect_measure name and flag
# log-scale so the candidate table exponentiates for display.
consistency_overrides$effect_label <- effect_measure
consistency_overrides$effect_log_scale <-
effect_measure %in% c("OR", "RR", "IRR")
# Resampling-approximation spec for consistency_method = "resample".
# consistency_threshold is already on the comparison scale (log for
# ratio measures, identity for identity measures), so it is passed as
# comparison_threshold to avoid a second log-transform. adjust_covariates
# is carried here because the GLM adjustment lives inside estimator_fn and
# is otherwise NULL on the consistency path.
consistency_overrides$glm_resample_spec <- list(
outcome_type = outcome_type,
effect_measure = effect_measure,
treat.name = treat.name,
outcome.name = outcome.name,
offset.name = offset.name,
adjust_covariates = adjust_covariates,
adverse_outcome = adverse_outcome,
comparison_threshold = consistency_threshold
)
}
# Run subgroup consistency analysis with error handling
sc_filtered_args <- filter_call_args(
args_call_all,
subgroup.consistency,
consistency_overrides
)
# Diagnostic: detect zero-length arguments that would cause
# "argument is of length zero" errors in if() statements
# Exclude twostage_args and parallel_args: empty list() is valid (use defaults)
sc_zero_len <- names(sc_filtered_args)[
vapply(sc_filtered_args, function(x) length(x) == 0 && !is.null(x), logical(1))
]
sc_zero_len <- setdiff(sc_zero_len, c("twostage_args", "parallel_args",
"estimator_fn", "consistency_threshold"))
if (length(sc_zero_len) > 0) {
warning("Zero-length arguments passed to subgroup.consistency: ",
paste(sc_zero_len, collapse = ", "))
if (details) {
cat("*** DIAGNOSTIC: Zero-length args for subgroup.consistency:\n")
for (zarg in sc_zero_len) {
cat(" ", zarg, " = ", deparse(sc_filtered_args[[zarg]]), "\n")
}
}
}
grp.consistency <- tryCatch({
do.call(subgroup.consistency, sc_filtered_args)
}, error = function(e) {
warning("Error in subgroup.consistency: ", e$message)
if (details) {
cat("*** subgroup.consistency error traceback:\n")
cat(" Message: ", e$message, "\n")
cat(" Arg names: ", paste(names(sc_filtered_args), collapse = ", "), "\n")
# Report lengths of key arguments
sc_key_args <- c("df", "hr.subgroups", "Lsg", "confs_labels",
"sg_focus", "stop_Kgroups", "parallel_args")
for (ka in intersect(sc_key_args, names(sc_filtered_args))) {
val <- sc_filtered_args[[ka]]
if (is.data.frame(val)) {
cat(" ", ka, ": data.frame [", nrow(val), " x ", ncol(val), "]\n")
} else {
cat(" ", ka, ": length=", length(val), " class=", class(val)[1], "\n")
}
}
}
return(NULL)
})
# Handle errors gracefully
if (is.null(grp.consistency) || inherits(grp.consistency, "try-error")) {
if (details) {
cat("Consistency analysis failed - proceeding without results\n")
}
grp.consistency <- NULL
}
# Update timing
t.end_all <- proc.time()[3]
t.min_all <- (t.end_all - t.start_all) / 60
if (details) {
cat("Seconds and minutes forestsearch overall =", round(c(t.min_all*60,t.min_all), 4), "\n")
if (!is.null(grp.consistency$algorithm)) {
cat("Consistency algorithm used:", grp.consistency$algorithm, "\n")
}
}
# -------------------------------------------------------------------------
# Process results if consistency analysis succeeded
# -------------------------------------------------------------------------
if (!is.null(grp.consistency) && !is.null(grp.consistency$sg.harm)) {
sg.harm <- grp.consistency$sg.harm
if (details) {
cat("Subgroup identified:", paste(sg.harm, collapse = " & "), "\n")
}
# Extract prediction datasets
temp <- grp.consistency$df_flag
# Merge to analysis data
# Guard: temp$id is the join key (built by extract_subgroup() with the
# literal column name "id" by convention). If id.name != "id" and df
# also carries an unrelated column named "id", the merge succeeds but
# df$id survives in the output and can confuse downstream consumers.
if (id.name != "id" && "id" %in% names(df)) {
stop("forestsearch(): `df.analysis` contains a column named 'id' ",
"that is distinct from `id.name = \"", id.name, "\"`. ",
"Rename or drop it before calling forestsearch() to avoid an ",
"ambiguous merge with internal subgroup-flag tables.",
call. = FALSE)
}
# Flags attach by row position (the flag table is built row-wise from df) and df.predict is
# evaluated by the rule: a bootstrap resample repeats ids, so a merge on id would compute
# Eq. 7's observed-data term on the resample.
df.est_out <- df
df.est_out$treat.recommend <- temp$treat.recommend
# Return df.predict
if (!is.null(df.predict)) {
if (id.name != "id" && "id" %in% names(df.predict)) {
stop("forestsearch(): `df.predict` contains a column named 'id' ",
"that is distinct from `id.name = \"", id.name, "\"`. ",
"Rename or drop it before calling forestsearch() to avoid an ",
"ambiguous merge with internal subgroup-flag tables.",
call. = FALSE)
}
df.predict_out <- get_dfpred(df.predict, sg.harm, version = 2)
}
# Return df.test
if (!is.null(df.test)) {
df.test_out <- get_dfpred(
df.predict = df.test,
sg.harm = grp.consistency$sg.harm,
version = 2
)
}
}
} # End has_subgroups
# ===========================================================================
# SECTION 9B: MULTIPLIER RESAMPLING (MR) -- POST-SELECTION INFERENCE (optional)
# ===========================================================================
# Fast multiplier-bootstrap approximation of the bootstrap bias-corrected
# effect for the selected subgroup, with a near-null "consistent with harm"
# flag. The selection-bias term must mirror the FULL search optimism, so the
# candidate family here is the SAME full enumerated space the search optimized
# over (all <= maxk cut combinations of Z), re-applying the screen on each
# multiplier draw -- NOT just the post-screening survivors in hr.subgroups
# (which would capture only selection-stage, not screening-stage, optimism).
# Per-candidate dfbeta is re-derived via the consistency engine's own pieces
# (~seconds; a future ledger from the search makes this zero-refit).
#
# Two paths are supported: the GLM resample-consistency path (estimator_fn
# non-NULL, consistency_method = "resample"), and the survival/Cox path
# (estimator_fn NULL, outcome_type = "survival"). On the Cox path MR is
# a fast standalone approximation -- it re-derives Cox dfbeta and re-selects
# over the family itself, so it does not require resample consistency and runs
# under the default split-consistency search. Default off.
mr_out <- NULL
.mr_glm_ok <- consistency_method == "resample" && !is.null(estimator_fn)
.mr_cox_ok <- outcome_type == "survival" && is.null(estimator_fn)
.mr_eligible <- isTRUE(mr_inference) && !is.null(sg.harm) &&
(.mr_glm_ok || .mr_cox_ok) &&
!is.null(grp.consistency) && !is.null(grp.consistency$sg.harm.id)
# C.2 -- make every "requested but skipped" route audible. Behaviour is
# unchanged: these conditions and the resulting mr_harm_confirmed = NA are
# exactly as before; only the silence is removed. Reasons are tested in
# precedence order, most specific first.
if (isTRUE(mr_inference) && !.mr_eligible) {
.mr_skip(quiet,
if (is.null(sg.harm))
"no subgroup was identified, so there is nothing to de-bias."
else if (!is.null(estimator_fn) && consistency_method != "resample")
paste0("MR on a GLM outcome requires consistency_method = ",
"\"resample\"; this analysis used consistency_method = \"",
consistency_method, "\". Re-run with ",
"consistency_method = \"resample\" to obtain MR.")
else if (!.mr_glm_ok && !.mr_cox_ok)
paste0("no MR path supports outcome_type = \"", outcome_type,
"\" with consistency_method = \"", consistency_method, "\".")
else
paste0("the consistency stage returned no subgroup membership ",
"(grp.consistency$sg.harm.id is absent)."))
}
if (.mr_eligible) {
.g_mr <- function(a, b) if (is.null(a)) b else a
# C.1 -- announce before the work starts.
.mr_announce(quiet, .g_mr(mr_inference_args$draws, 2000L))
mr_out <- tryCatch({
# Full candidate space: enumerate all <= maxk combinations of the cut
# matrix Z with the search's OWN helpers, so the family is identical to
# the space subgroup.search() ranked over -- with two known gaps: the
# per-arm event minima (d0.min/d1.min) and max_subgroups_search are NOT
# replayed here, so this family is a superset of the one the identifier
# actually chose among, which inflates the selection-bias term.
L_mr <- ncol(Z)
combo_mr <- generate_combination_indices(L_mr, maxk)
tot_mr <- calculate_max_combinations(L_mr, maxk)
fam <- list()
for (kk in seq_len(tot_mr)) {
covs.in <- get_covs_in(
kk, maxk, L_mr,
combo_mr$counts_1, combo_mr$indices_1,
combo_mr$counts_2, combo_mr$indices_2,
combo_mr$counts_3, combo_mr$indices_3)
k_sel <- sum(covs.in)
if (k_sel < 1L || k_sel > maxk) next
mem <- which(get_subgroup_membership(Z, covs.in))
if (length(mem) >= n.min)
fam[[paste(colnames(Z)[covs.in == 1], collapse = " & ")]] <- mem
}
# Spec + comparison-scale thresholds differ by path. Survival uses the
# internal df.fs column names (Y/Event/Treat) and log-HR thresholds; GLM
# uses the user-facing names and the already-log effect/consistency
# thresholds. Cox dispatch happens inside the engine via outcome_type.
if (.mr_cox_ok) {
adj_mr <- intersect(adjust_covariates, names(df.fs)) # only if present
gspec <- list(outcome_type = "survival", effect_measure = "HR",
treat.name = "Treat", outcome.name = "Y",
event.name = "Event", offset.name = NULL,
adjust_covariates = if (length(adj_mr)) adj_mr else NULL,
adverse_outcome = TRUE)
} else {
gspec <- list(outcome_type = outcome_type, effect_measure = effect_measure,
treat.name = treat.name, outcome.name = outcome.name,
event.name = event.name, offset.name = offset.name,
adjust_covariates = adjust_covariates,
adverse_outcome = adverse_outcome)
}
fs_mr_inference(
df = df.fs, candidates = fam, spec = gspec,
selected_members = which(grp.consistency$sg.harm.id == 1),
# Admission resolved once (see .fs_resolve_admission). Under
# sg_focus = "maxeff" the identifier applies no auxiliary selection
# condition, so this returns both floors NULL and MR re-selects over
# the whole family -- matching the selection event that occurred.
admission = admission_resolved,
t_confirm = mr_inference_args$t_confirm, # NULL -> near-null default
confirm_rule = .g_mr(mr_inference_args$confirm_rule, "point"),
reselection = .g_mr(mr_inference_args$reselection,
.fs_mr_reselection_from_focus(sg_focus,
engine = "consistency")),
effect_neighborhood = effect_neighborhood,
selection_rule = .g_mr(mr_inference_args$selection_rule, selection_rule),
draws = .g_mr(mr_inference_args$draws, 2000L),
multiplier = .g_mr(mr_inference_args$multiplier, "poisson"),
include_complement = .g_mr(mr_inference_args$include_complement, TRUE),
# ci_method defaults to "field" from TASK_cimethod_note_2026-09-09
# Part D2 -- the field block's one-sided products are the certified
# ones, and Part D's field_complement / field_scale_complement /
# return_reselection flips are inert without it. Nothing is
# removed: the IJ SE and its intervals are computed before and
# independent of the field gate and are returned either way.
# ci_method = "ij" restores the previous default (field block
# omitted, and with it the per-fit Monte Carlo cost).
ci_method = .g_mr(mr_inference_args$ci_method, "field"),
# Add-only pass-through (TASK_mr_field_uniform_2026-09-05, Larry's
# classification: no behaviour change; FALSE is the gate's default).
field_uniform = .g_mr(mr_inference_args$field_uniform, FALSE),
# Pass-throughs (TASK_gbsg_frozen_intervals_2026-09-05 Gate 0
# resolution). return_reselection defaults to TRUE from
# TASK_cert20_2026-09-08 Part D -- the re-selection diagnostics are
# part of the recommended output; nothing in the arithmetic depends
# on it, and FALSE restores the smaller return object.
return_reselection = .g_mr(mr_inference_args$return_reselection, TRUE),
field_M_cap = .g_mr(mr_inference_args$field_M_cap, NULL),
# Pass-through (TASK_mr_field_complement_2026-09-06): the complement's
# field block. TRUE is the gate's default from
# TASK_cert20_2026-09-08 Part D -- the recommended construction;
# FALSE restores the prior behaviour.
field_complement = .g_mr(mr_inference_args$field_complement, TRUE),
# Add-only pass-through (TASK_field_studentize_stage1_e0_2026-09-08):
# the complement field's scale diagnostics; FALSE is the gate's default.
field_decompose = .g_mr(mr_inference_args$field_decompose, FALSE),
# Pass-through (TASK_field_studentize_e1_2026-09-08): the studentized
# complement field (field-s). "selected" is the gate's default from
# TASK_cert20_2026-09-08 Part D -- the recommended construction;
# "none" restores the prior behaviour.
field_scale_complement = .g_mr(mr_inference_args$field_scale_complement, "selected"),
# Add-only pass-through (TASK_field_recovery_2026-09-09): the field's
# membership-agreement diagnostics; FALSE is the default and the block
# is default-inert (nothing reads it, and it draws nothing).
field_recovery = .g_mr(mr_inference_args$field_recovery, FALSE),
# Add-only pass-through (TASK_complement_refinements_2026-09-06):
# which IJ residual populates the reported SE; "two_term" is the
# gate's default and reproduces prior output exactly.
ij_residual = .g_mr(mr_inference_args$ij_residual, "two_term"),
# Add-only pass-throughs (TASK_declaration_calibration_2026-09-22_v2):
# retain the standardized field fs_declaration_calibration() reads.
# FALSE computes and stores nothing.
keep_declaration_field = .g_mr(mr_inference_args$keep_declaration_field, FALSE),
keep_field_matrix = .g_mr(mr_inference_args$keep_field_matrix, FALSE),
# Add-only pass-through (TASK_declcal_c0_rchange_2026-09-22): protected
# null levels c0 whose shifted maxima the capture stores. NULL stores
# nothing.
declaration_c0 = .g_mr(mr_inference_args$declaration_c0, NULL),
pconsistency.digits = pconsistency.digits,
seed = .g_mr(mr_inference_args$seed, seedit))
}, error = function(e) {
warning("mr_inference failed: ", conditionMessage(e)); NULL
})
# C.2 -- the tryCatch route. The warning above carries the cause; this
# states the consequence in the same vocabulary as the other skip routes.
if (is.null(mr_out))
.mr_skip(quiet, "the MR computation failed (see the warning above).")
# C.3 -- the confirmation result. Routed through .mr_msg() like every
# other MR report: cat() writes to stdout, which suppressMessages() cannot
# silence and which floods parallel sim renders (116 blocks at
# n_sims = 20). The MESSAGING (Part C) contract in
# fs_mr_inference_methods.R is message()-only for exactly this reason.
if (!is.null(mr_out) && !is.na(mr_out$harm_flag)) {
.mr_msg(quiet, sprintf(
"MR harm confirmation: %s = %.3f (%s rule vs %.2f) -> %s",
.g_mr(mr_out$measure, "effect"),
mr_out$debiased$est, mr_out$settings$confirm_rule,
mr_out$settings$t_confirm,
if (mr_out$harm_flag) "consistent with harm"
else "not confirmed"))
}
}
# ===========================================================================
# SECTION 10: COMPILE AND RETURN OUTPUT
# ===========================================================================
out <- list(
grp.consistency = grp.consistency,
find.grps = find.grps,
confounders.candidate = FSconfounders.name,
confounders.evaluated = confs_labels,
df.est = df.est_out,
df.predict = df.predict_out,
df.test = df.test_out,
minutes_all = t.min_all,
grf_res = grf_res,
sg_focus = sg_focus,
sg.harm = sg.harm,
# Multiplier-resampling result (NULL unless mr_inference = TRUE)
mr_inference = mr_out,
mr_harm_confirmed = if (!is.null(mr_out)) mr_out$harm_flag
else NA,
grf_cuts = grf_cuts,
dina_res = dina_res,
dina_cuts = dina_cuts,
prop_maxk = prop_maxk,
max_sg_est = max_sg_est,
grf_plot = grf_plot,
args_call_all = args_call_all,
# NEW: Include algorithm information
consistency_algorithm = if (!is.null(grp.consistency)) grp.consistency$algorithm else NA,
# NEW: GLM outcome information
outcome_type = outcome_type,
effect_measure = effect_measure,
# NEW: Resolved threshold configuration
threshold_config = if (exists("threshold_config")) threshold_config
else NULL,
# Candidate-family status: "no-front-end", "conditional-removable" or
# "conditional-inherent". Descriptive only; see .fs_family_status().
family_status = family_status,
# The admission set MR re-selected over, recorded so a run's domain is
# auditable rather than inferable from sg_focus and subgroup_method.
admission = admission_resolved
)
class(out) <- c("forestsearch", "list")
return(out)
}
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.