Nothing
# =============================================================================
# run_simulation_analysis() — General simulation wrapper
# =============================================================================
#
# Replaces oc_analyses_gbsg.R::run_simulation_analysis(), which was coupled
# to the legacy GBSG simulator (since removed) and hardcoded column names
# (y.sim, event.sim, flag.harm, treat).
#
# Design:
# - Calls simulate_from_dgm() (the general simulator).
# - Column names are explicit parameters; no GBSG-specific names anywhere.
# - Helpers (extract_fs_estimates_gen, extract_grf_estimates_gen,
# run_forestsearch_analysis_gen, run_grf_analysis_gen) are contained here
# and receive column names from the top-level call.
# - default_sim_params() / default_grf_params_gen() use general names.
# - GBSG usage is just: run_simulation_analysis(dgm, ...) with defaults.
# =============================================================================
# =============================================================================
# Default parameter lists
# =============================================================================
# Null-coalescing helper (local to this file).
# Defined here rather than importing rlang::%||% because this file
# runs inside parallel workers where rlang may not be loaded.
if (!exists("%||%", inherits = FALSE))
`%||%` <- function(a, b) if (!is.null(a)) a else b
#' Default ForestSearch parameters (general)
#'
#' Returns the default \code{fs_params} list used by
#' \code{run_simulation_analysis()}. The \code{parallel_args} entry
#' defaults to \code{list(plan = "sequential")} because
#' \code{run_simulation_analysis()} is designed to be called inside a
#' \code{foreach() \%dofuture\%} loop (one replicate per worker). Running
#' the inner \code{forestsearch()} multisession in that context produces
#' nested parallelism: each outer worker tries to spawn its own pool of
#' inner workers, which \code{parallelly} rejects with a 300\%-load hard
#' limit error. Users who call \code{run_simulation_analysis()} once at
#' the top level (i.e., not inside \code{\%dofuture\%}) can opt back into
#' multisession by passing
#' \code{fs_params = list(parallel_args = list(plan = "multisession", workers = N))}.
#'
#' @keywords internal
default_sim_params <- function() {
list(
outcome.name = "y_sim",
event.name = "event_sim",
treat.name = "treat_sim",
id.name = "id",
use_lasso = TRUE,
use_grf = FALSE,
hr.threshold = 1.25,
hr.consistency = 1.0,
pconsistency.threshold = 0.90,
fs.splits = 400,
n.min = 60,
d0.min = 12,
d1.min = 12,
maxk = 2,
by.risk = 12,
use_twostage = FALSE,
twostage_args = list(),
# Run inner forestsearch() sequentially by default. See function
# documentation above for rationale (nested-parallelism avoidance).
parallel_args = list(plan = "sequential")
)
}
#' Default GRF parameters (general)
#' @keywords internal
default_grf_params_gen <- function() {
list(
outcome.name = "y_sim",
event.name = "event_sim",
treat.name = "treat_sim",
id.name = "id",
n.min = 60,
dmin.grf = 12,
frac.tau = 0.60,
maxdepth = 2,
RCT = TRUE,
sg.criterion = "mDiff",
seedit = 8316951L
)
}
# =============================================================================
# Internal: generalized-method dispatch helpers
# =============================================================================
#' NULL-preserving list merge
#'
#' Like \code{utils::modifyList()}, but an entry in \code{over} whose value is
#' \code{NULL} \emph{sets} the corresponding element of \code{base} to an
#' explicit \code{NULL} (kept in the list) rather than deleting it. Required
#' so that an explicit \code{n.min = NULL} survives the parameter merges and
#' reaches \code{forestsearch()}, where it triggers the sample-size-adaptive
#' minimum-size rule; ordinary \code{modifyList()} would strip it and silently
#' fall back to the formal default.
#' @keywords internal
#' @noRd
.modify_keep_null <- function(base, over) {
for (nm in names(over)) base[nm] <- over[nm]
base
}
#' Expand a canonical method label into forestsearch() overrides
#'
#' Parses a \code{"<engine>-<focus>"} label (e.g. \code{"fs-effMaxSG"},
#' \code{"dina-eff"}, \code{"grf-tree"}) into a list of \code{forestsearch()}
#' argument overrides. The engine token names the \emph{selector}; every arm
#' is ultimately run through \code{forestsearch()}, which supplies the shared
#' post-selection inference, so no "FS" component appears in the label.
#' @keywords internal
#' @noRd
.expand_method_label <- function(label) {
parts <- strsplit(label, "-", fixed = TRUE)[[1L]]
if (length(parts) < 2L) {
stop(sprintf(
"Cannot parse method label '%s'; expected '<engine>-<focus>' (e.g. 'fs-effMaxSG').",
label), call. = FALSE)
}
engine <- parts[1L]
focus <- paste(parts[-1L], collapse = "-")
over <- list(selection_rule = "neighborhood")
if (identical(engine, "fs")) {
over$subgroup_method <- "consistency"
over$sg_focus <- focus
over$use_grf <- TRUE
over$use_dina <- TRUE
over$use_lasso <- FALSE
over["n.min"] <- list(NULL) # explicit NULL -> adaptive rule
} else if (identical(engine, "dina")) {
over$subgroup_method <- "dina"
over$sg_focus <- focus
} else if (identical(engine, "grf")) {
over$subgroup_method <- "grf"
if (identical(focus, "tree")) {
over$grf_selection <- "tree"
} else {
over$grf_selection <- "frontier"
over$sg_focus <- focus
}
} else {
stop(sprintf(
"Unknown engine '%s' in method label '%s'; expected 'fs', 'dina', or 'grf'.",
engine, label), call. = FALSE)
}
over
}
#' Normalize the `methods` argument to a named list of override lists
#'
#' Accepts either a character vector of canonical labels (expanded via
#' \code{.expand_method_label()}) or a pre-built named list of
#' \code{forestsearch()} override lists, returning a named list keyed by arm
#' label. Returns \code{NULL} unchanged.
#' @keywords internal
#' @noRd
.normalize_methods <- function(methods) {
if (is.null(methods)) return(NULL)
if (is.character(methods)) {
if (anyNA(methods) || any(!nzchar(methods))) {
stop("All entries of a character 'methods' vector must be non-empty labels.",
call. = FALSE)
}
specs <- lapply(methods, .expand_method_label)
names(specs) <- methods
return(specs)
}
if (is.list(methods)) {
nm <- names(methods)
if (is.null(nm) || any(!nzchar(nm))) {
stop("When 'methods' is a list, every element must be named with its arm label.",
call. = FALSE)
}
if (anyDuplicated(nm)) {
stop("Duplicate arm labels in 'methods': ",
paste(unique(nm[duplicated(nm)]), collapse = ", "), ".", call. = FALSE)
}
return(methods)
}
stop("'methods' must be NULL, a character vector of labels, or a named list of override lists.",
call. = FALSE)
}
# =============================================================================
# Main function
# =============================================================================
#' Run One Simulation Replicate
#'
#' General replacement for the legacy \code{run_simulation_analysis()} that
#' was coupled to the legacy GBSG simulator (since removed) and GBSG-specific
#' column names. This version calls \code{\link{simulate_from_dgm}} and accepts
#' explicit column-name parameters, making it applicable to any DGM built
#' with \code{\link{generate_aft_dgm_flex}}.
#'
#' @param sim_id Integer. Simulation replicate index (used as seed offset).
#' @param dgm An \code{"aft_dgm_flex"} object from
#' \code{\link{generate_aft_dgm_flex}} or \code{\link{setup_gbsg_dgm}},
#' or a \code{"glm_dgm"} object from \code{\link{generate_glm_dgm}}.
#' @param n_sample Integer. Per-replicate sample size.
#' @param analysis_time Numeric. Calendar time of analysis on the DGM time
#' scale. Use \code{Inf} (default) for no administrative censoring —
#' equivalent to the legacy \code{max_follow = Inf}.
#' @param cens_adjust Numeric. Log-scale shift to censoring times passed to
#' \code{simulate_from_dgm(cens_adjust = ...)}. Replaces legacy
#' \code{muC_adj}. Default \code{0}.
#' @param max_follow \strong{Deprecated.} Use \code{analysis_time} instead.
#' If supplied, its value is forwarded to \code{analysis_time} with a
#' warning. Retained for backward compatibility with legacy scripts.
#' @param muC_adj \strong{Deprecated.} Use \code{cens_adjust} instead.
#' If supplied, its value is forwarded to \code{cens_adjust} with a
#' warning. Retained for backward compatibility with legacy scripts.
#' @param confounders_base Character vector of base confounder names.
#' @param n_add_noise Integer. Number of independent N(0,1) noise variables
#' to append. Default \code{0L}.
#' @param outcome_name Name of the observed time column in simulated data.
#' Default \code{"y_sim"}.
#' @param event_name Name of the event indicator column. Default
#' \code{"event_sim"}.
#' @param treat_name Name of the treatment column. Default \code{"treat_sim"}.
#' @param harm_col Name of the true-subgroup indicator column. Default
#' \code{"flag_harm"}.
#' @param run_fs Logical. Run ForestSearch (LASSO). Default \code{TRUE}.
#' @param run_fs_grf Logical. Run ForestSearch (LASSO + GRF). Default
#' \code{TRUE}.
#' @param run_grf Logical. Run standalone GRF. Default \code{TRUE}.
#' @param methods Optional specification of analysis arms that generalizes the
#' \code{run_fs} / \code{run_fs_grf} / \code{run_grf} booleans. When
#' non-\code{NULL} the booleans are ignored and \strong{every} arm is run via
#' \code{forestsearch()} (through \code{.run_fs_analysis_gen()}), so all arms
#' --- including \code{dina-*} and \code{grf-*} --- inherit the bias-corrected
#' post-selection inference. Two forms are accepted:
#' \itemize{
#' \item A character vector of canonical \code{"<engine>-<focus>"} labels,
#' e.g. \code{c("fs-effMaxSG", "dina-effMaxSG", "grf-tree")}, expanded
#' internally to per-arm \code{forestsearch()} overrides. Engines are
#' \code{"fs"} (\code{subgroup_method = "consistency"}), \code{"dina"},
#' and \code{"grf"} (\code{grf_selection = "frontier"}, or \code{"tree"}
#' for the \code{grf-tree} label). Defaults applied during expansion:
#' \code{selection_rule = "neighborhood"}; for \code{fs-*} arms
#' \code{use_grf = TRUE}, \code{use_dina = TRUE}, \code{use_lasso = FALSE},
#' and \code{n.min = NULL} (the sample-size-adaptive rule).
#' \item A named list of explicit \code{forestsearch()} argument-override
#' lists, label = name, e.g.
#' \code{list("fs-effMaxSG" = list(subgroup_method = "consistency", sg_focus = "effMaxSG", use_grf = TRUE, use_dina = TRUE, use_lasso = FALSE), "grf-tree" = list(subgroup_method = "grf", grf_selection = "tree"))}.
#' }
#' Each arm's overrides are merged on top of \code{default_sim_params()}
#' overlaid with \code{fs_params}; per-arm overrides take precedence. The
#' merge preserves an explicit \code{n.min = NULL}. Default \code{NULL}
#' preserves the legacy boolean behavior.
#' @param fs_params Named list of ForestSearch parameter overrides. Any
#' element of \code{default_sim_params()} can be overridden, including
#' \code{parallel_args} (see \emph{Parallel Processing} section below).
#' Passing \code{NULL} or an empty list uses defaults throughout.
#' @param grf_params Named list of GRF parameter overrides.
#' @param cox_formula Optional Cox formula for unadjusted ITT.
#' @param cox_formula_adj Optional adjusted Cox formula.
#' @param n_sims_total Integer. Total simulations (for progress messages).
#' @param seed_base Integer. Base seed; replicate seed = \code{seed_base +
#' sim_id}. Default \code{8316951L}.
#' @param verbose Logical. Print progress messages. Default \code{FALSE}.
#' @param verbose_n Integer. If set, only print for \code{sim_id <=
#' verbose_n}. Default \code{NULL}.
#' @param debug Logical. Print detailed debug output. Default \code{FALSE}.
#' @param keep Character vector. Optional names of heavy diagnostic
#' objects to attach as a list in \code{attr(result, "diagnostics")}.
#' Allowed values (any combination):
#' \describe{
#' \item{\code{"fs_full"}}{The full \code{forestsearch()} result
#' object (minus the \code{df.est} analysis data frame, which is
#' stripped to control memory). Includes \code{sg.harm},
#' \code{grp.consistency}, \code{confounders.candidate},
#' \code{confounders.evaluated}, GRF cuts, and timing.}
#' \item{\code{"df.est"}}{The analysis data frame with
#' \code{treat.recommend} column attached. Heavy; use sparingly.}
#' \item{\code{"candidate_table"}}{The data table of candidate
#' subgroups evaluated
#' (\code{fs_full$grp.consistency$out_sg$result}). Medium-weight;
#' useful for diagnosing which candidates were near-threshold.}
#' \item{\code{"grf_full"}}{The full
#' \code{grf.subg.harm.*()} result object.}
#' }
#' Default \code{character(0)} (attach nothing; current behavior).
#' @param keep_first_n Integer. When \code{keep} is non-empty, attach
#' the requested diagnostics only if \code{sim_id <= keep_first_n}.
#' Default \code{Inf} (attach for all replicates). Use this to
#' capture full details for, e.g., the first 20 simulations without
#' bloating the result object for long production runs.
#'
#' @return A \code{data.table} with one row per analysis method.
#' Always-present scalar columns cover: true-subgroup size/effect
#' from the DGM, per-method detection flag (\code{any.H}), estimated
#' subgroup size (\code{size.H}, \code{size.Hc}), effect estimates
#' (\code{hr.H.hat}, \code{hr.Hc.hat}, \code{hr.itt}, and their true
#' counterparts), classification metrics against the DGM-stored
#' subgroup (\code{sens}, \code{spec}, \code{ppv}, \code{npv}), and
#' pairwise concordance between methods (\code{agree.*.*},
#' \code{kappa.*.*}). For a GLM outcome (\code{fs_params$outcome_type}
#' set and not \code{"survival"}) \code{hr.itt}, \code{hr.H.hat},
#' \code{hr.Hc.hat}, \code{hr.H.true} and \code{hr.Hc.true} come from a
#' two-arm \code{glm()} in each set and are on the scale
#' \code{fs_params$effect_measure} names, treatment against control: the
#' odds ratio (\code{"OR"}) and rate ratio (\code{"IRR"}) are the
#' exponentiated treatment coefficient and the mean difference
#' (\code{"MD"}) the coefficient; the risk difference (\code{"RD"}) and
#' risk ratio (\code{"RR"}) are the difference and ratio of the two fitted
#' arm proportions, and the rate difference (\code{"IRD"}) the difference
#' of the two fitted arm rates, per unit of exposure when the column named
#' by \code{fs_params$offset.name} is in the data (the convention under
#' which the \code{"IRR"} value is their ratio). The \code{ahr.*} truth
#' columns (\code{\link{compute_aor}}) use the same scales, with one
#' exception: with an offset (the DGM's \code{offset_var} in
#' \code{\link{generate_glm_dgm}}, and \code{fs_params$offset.name}),
#' the \code{"IRD"} truth is a difference in
#' expected counts per patient, over each patient's own exposure, not per
#' unit of exposure (for a constant rate difference it is the mean exposure
#' times the per-unit value). As of v0.2.0 the following ForestSearch
#' diagnostic columns are also always populated (\code{NA} for GRF
#' rows):
#' \describe{
#' \item{\code{sg.def}}{Character. Cut-expression string of the
#' identified subgroup, formed as
#' \code{paste(fs_full$sg.harm, collapse = " & ")}. Empty
#' string when no subgroup was identified. Read across all
#' replicates to diagnose which cuts the method is selecting
#' (e.g., \code{table(results$sg.def)}).}
#' \item{\code{sg.n_factors}}{Integer. Number of factors in the
#' identified subgroup definition.}
#' \item{\code{n_candidates_evaluated}}{Integer. Number of
#' candidate subgroups actually evaluated for consistency
#' (before or at the early-stop candidate).}
#' \item{\code{n_candidates_total}}{Integer. Total number of
#' candidate subgroups available.}
#' \item{\code{n_passed}}{Integer. Number of candidates meeting
#' the consistency threshold.}
#' \item{\code{consistency_algorithm}}{Character. \code{"fixed"}
#' or \code{"twostage"}.}
#' \item{\code{early_stop_triggered}}{Logical. Whether
#' evaluation stopped early due to \code{stop_threshold}.}
#' \item{\code{fs_minutes}}{Numeric. Wall time for the FS run
#' in minutes.}
#' }
#' The analogous GRF row carries \code{sg.def} (from
#' \code{grf_result$sg.harm.id}) and \code{grf_selected_depth}.
#' When \code{keep} is non-empty and \code{sim_id <= keep_first_n},
#' the heavy objects are attached as
#' \code{attr(result, "diagnostics")} — a named list with one
#' element per keeper (\code{fs_full}, \code{grf_full}, etc.).
#'
#' @seealso \code{\link{simulate_from_dgm}},
#' \code{\link{generate_aft_dgm_flex}}, \code{\link{setup_gbsg_dgm}}
#'
#' @section GLM Parameters:
#' GLM-specific parameters (\code{outcome_type}, \code{effect_measure},
#' \code{offset.name}) must be passed inside \code{fs_params}, not as
#' top-level arguments. They route only to the estimation step
#' (\code{.extract_fs_estimates_gen}, \code{.extract_grf_estimates_gen}),
#' not to \code{forestsearch()} itself, which uses Cox PH for subgroup
#' identification in v0.1.x. Passing these as top-level arguments will
#' result in them being silently ignored.
#'
#' @section Parallel Processing:
#' \code{run_simulation_analysis()} is designed to be called inside a
#' \code{foreach() \%dofuture\%} loop (one replicate per worker). In
#' that idiom, \emph{outer} parallelism is provided by \code{\%dofuture\%}
#' (one replicate per worker) and the \emph{inner} \code{forestsearch()}
#' call should run sequentially within each worker. Running both layers
#' multisession produces nested parallelism: each outer worker tries to
#' spawn its own pool of inner workers, which \code{parallelly} rejects
#' with a 300\%-load hard-limit error.
#'
#' To prevent this, \code{default_sim_params()} sets
#' \code{parallel_args = list(plan = "sequential")} as the default for
#' the inner \code{forestsearch()} call. Users who call
#' \code{run_simulation_analysis()} once at the top level (e.g., for
#' interactive debugging) and want the inner pipeline to run in parallel
#' can opt back in by passing
#' \code{fs_params = list(parallel_args = list(plan = "multisession", workers = N))}.
#'
#' @importFrom data.table data.table rbindlist
#' @importFrom survival coxph Surv
#' @importFrom stats rnorm
#' @examples
#' \dontrun{
#' dgm <- setup_gbsg_dgm(model = "null", verbose = FALSE)
#'
#' # Inner forestsearch() runs sequentially by default; safe for both
#' # interactive use and embedding inside foreach() %dofuture% loops.
#' result <- run_simulation_analysis(sim_id = 1, dgm = dgm, n_sample = 500)
#'
#' # Opt back into inner multisession for a one-off top-level call:
#' result <- run_simulation_analysis(
#' sim_id = 1,
#' dgm = dgm,
#' n_sample = 500,
#' fs_params = list(parallel_args = list(plan = "multisession",
#' workers = 4))
#' )
#' }
#' @export
run_simulation_analysis <- function(
sim_id,
dgm,
n_sample,
analysis_time = Inf,
cens_adjust = 0,
# Deprecated legacy parameter names — emit a warning if used
max_follow = NULL,
muC_adj = NULL,
confounders_base = c("v1", "v2", "v3", "v4", "v5", "v6", "v7"),
n_add_noise = 0L,
outcome_name = "y_sim",
event_name = "event_sim",
treat_name = "treat_sim",
harm_col = "flag_harm",
run_fs = TRUE,
run_fs_grf = TRUE,
run_grf = TRUE,
methods = NULL,
fs_params = list(),
grf_params = list(),
cox_formula = NULL,
cox_formula_adj = NULL,
n_sims_total = NULL,
seed_base = 8316951L,
verbose = FALSE,
verbose_n = NULL,
debug = FALSE,
keep = character(0),
keep_first_n = Inf
) {
.fs_preserve_rng()
show_verbose <- verbose && (is.null(verbose_n) || sim_id <= verbose_n)
# ── Validate keep / keep_first_n ─────────────────────────────────────────
valid_keep <- c("fs_full", "df.est", "candidate_table", "grf_full")
keep_invalid <- setdiff(keep, valid_keep)
if (length(keep_invalid) > 0L) {
stop(sprintf(
"Invalid 'keep' values: %s. Allowed: %s.",
paste(shQuote(keep_invalid), collapse = ", "),
paste(shQuote(valid_keep), collapse = ", ")
), call. = FALSE)
}
keep_this_sim <- length(keep) > 0L && sim_id <= keep_first_n
# ── Deprecated parameter shims ─────────────────────────────────────────────
if (!is.null(max_follow)) {
warning(
"'max_follow' is deprecated. Use 'analysis_time' instead.\n",
" Mapping: analysis_time = max_follow (", max_follow, ")",
call. = FALSE
)
analysis_time <- max_follow
}
if (!is.null(muC_adj)) {
warning(
"'muC_adj' is deprecated. Use 'cens_adjust' instead.\n",
" Mapping: cens_adjust = muC_adj (", muC_adj, ")",
call. = FALSE
)
cens_adjust <- muC_adj
}
if (show_verbose) {
message("\n", paste(rep("=", 60), collapse = ""))
message(sprintf("Simulation %d", sim_id))
if (!is.null(n_sims_total))
message(sprintf(" Progress: %d / %d (%.1f%%)",
sim_id, n_sims_total, 100 * sim_id / n_sims_total))
message(paste(rep("=", 60), collapse = ""))
}
# ── Simulate data ──────────────────────────────────────────────────────────
if (show_verbose)
message(sprintf("\n[1] Simulating data (n=%d, analysis_time=%s, cens_adjust=%g)...",
n_sample, analysis_time, cens_adjust))
# Class-based dispatch: glm_dgm uses simulate_from_glm_dgm(),
# aft_dgm_flex uses simulate_from_dgm().
is_glm_dgm <- inherits(dgm, "glm_dgm")
sim_data <- tryCatch(
if (is_glm_dgm) {
simulate_from_glm_dgm(
dgm = dgm,
n = n_sample,
seed = seed_base + sim_id
)
} else {
simulate_from_dgm(
dgm = dgm,
n = n_sample,
seed = seed_base + sim_id,
analysis_time = analysis_time,
cens_adjust = cens_adjust
)
},
error = function(e) stop("Simulation failed: ", e$message)
)
# GLM sims don't produce event_sim; create it for downstream compatibility.
# For binary: event_sim = y_sim (the outcome IS the event).
# For continuous/count: event_sim = 1 (all observed, no censoring).
if (is_glm_dgm && !event_name %in% names(sim_data)) {
if (!is.null(dgm$outcome_type) && dgm$outcome_type == "binary") {
sim_data[[event_name]] <- sim_data[[outcome_name]]
} else {
sim_data[[event_name]] <- 1L
}
}
if (show_verbose)
message(sprintf(" n=%d events=%d (%.1f%%)",
nrow(sim_data), sum(sim_data[[event_name]]),
100 * mean(sim_data[[event_name]])))
# ── Optional noise variables ───────────────────────────────────────────────
confounders_name <- confounders_base
if (n_add_noise > 0L) {
set.seed(seed_base + 1000L * sim_id)
noise_nms <- paste0("noise", seq_len(n_add_noise))
for (nm in noise_nms) sim_data[[nm]] <- stats::rnorm(nrow(sim_data))
confounders_name <- c(confounders_base, noise_nms)
if (show_verbose)
message(sprintf(" Added %d noise variable(s)", n_add_noise))
}
# ── True subgroup properties ───────────────────────────────────────────────
has_harm <- harm_col %in% names(sim_data)
size_H_true <- if (has_harm) sum(sim_data[[harm_col]]) else NA_integer_
prop_H_true <- if (has_harm) mean(sim_data[[harm_col]]) else NA_real_
size_Hc_true <- if (has_harm) nrow(sim_data) - size_H_true else NA_integer_
prop_Hc_true <- if (has_harm) 1 - prop_H_true else NA_real_
hr_H_dgm <- get_dgm_hr(dgm, "hr_H")
hr_Hc_dgm <- get_dgm_hr(dgm, "hr_Hc")
ahr_H_dgm <- get_dgm_hr(dgm, "ahr_H")
ahr_Hc_dgm <- get_dgm_hr(dgm, "ahr_Hc")
if (show_verbose) {
message(sprintf("\n[2] True subgroup: H n=%s (%.1f%%), Hc n=%s (%.1f%%)",
ifelse(is.na(size_H_true), "NA", size_H_true),
100 * prop_H_true,
ifelse(is.na(size_Hc_true), "NA", size_Hc_true),
100 * prop_Hc_true))
message(sprintf(" DGM HR_H=%.3f HR_Hc=%.3f AHR_H=%.3f AHR_Hc=%.3f",
hr_H_dgm, hr_Hc_dgm,
ifelse(is.na(ahr_H_dgm), NA, ahr_H_dgm),
ifelse(is.na(ahr_Hc_dgm), NA, ahr_Hc_dgm)))
}
df_pop <- data.table::data.table(
sim = sim_id,
sizeH_true = size_H_true,
propH_true = prop_H_true,
sizeHc_true = size_Hc_true,
propHc_true = prop_Hc_true
)
# ── Merge parameter defaults ───────────────────────────────────────────────
fs_defaults <- default_sim_params()
grf_defaults <- default_grf_params_gen()
grf_merged <- modifyList(grf_defaults, grf_params)
# Ensure outcome/event/treat names in FS defaults match what simulate produced
fs_defaults$outcome.name <- outcome_name
fs_defaults$event.name <- event_name
fs_defaults$treat.name <- treat_name
grf_merged$outcome.name <- outcome_name
grf_merged$event.name <- event_name
grf_merged$treat.name <- treat_name
# ── Run analyses ───────────────────────────────────────────────────────────
results_list <- list()
sg_hat_list <- list() # per-subject subgroup assignments for concordance
# Generalized method dispatch. When `methods` is supplied it takes over
# from the run_fs / run_fs_grf / run_grf booleans, and every arm -- fs-*,
# dina-*, grf-* -- is executed through forestsearch() so all share the
# bias-corrected post-selection inference.
method_specs <- .normalize_methods(methods)
if (show_verbose) {
to_run <- if (is.null(method_specs)) {
c(if (run_fs) "FS", if (run_fs_grf) "FSlg", if (run_grf) "GRF")
} else {
names(method_specs)
}
message(sprintf("\n[3] Running: %s", paste(to_run, collapse = ", ")))
}
# Accumulator for heavy diagnostic objects (populated only when
# keep_this_sim = TRUE). Each element is itself a named list carrying
# whichever keepers were requested for that method.
diagnostics_list <- list()
if (is.null(method_specs) && run_fs) {
fs_p <- modifyList(
modifyList(fs_defaults, list(use_lasso = TRUE, use_grf = FALSE)),
fs_params
)
fs_out <- .run_fs_analysis_gen(
data = sim_data, confounders_name = confounders_name,
params = fs_p, dgm = dgm,
cox_formula = cox_formula, cox_formula_adj = cox_formula_adj,
outcome_name = outcome_name, event_name = event_name,
treat_name = treat_name, harm_col = harm_col,
label = "FS", verbose = show_verbose,
keep = if (keep_this_sim) keep else character(0)
)
sg_hat_list[["FS"]] <- attr(fs_out, "sg_hat")
if (keep_this_sim) {
keepers <- attr(fs_out, "keepers")
if (!is.null(keepers)) diagnostics_list[["FS"]] <- keepers
}
# Strip attributes before cbind so data.table semantics stay clean
attr(fs_out, "sg_hat") <- NULL
attr(fs_out, "keepers") <- NULL
results_list[["FS"]] <- cbind(df_pop, fs_out)
}
if (is.null(method_specs) && run_fs_grf) {
fs_p <- modifyList(
modifyList(fs_defaults, list(use_lasso = TRUE, use_grf = TRUE)),
fs_params
)
fslg_out <- .run_fs_analysis_gen(
data = sim_data, confounders_name = confounders_name,
params = fs_p, dgm = dgm,
cox_formula = cox_formula, cox_formula_adj = cox_formula_adj,
outcome_name = outcome_name, event_name = event_name,
treat_name = treat_name, harm_col = harm_col,
label = "FSlg", verbose = show_verbose,
keep = if (keep_this_sim) keep else character(0)
)
sg_hat_list[["FSlg"]] <- attr(fslg_out, "sg_hat")
if (keep_this_sim) {
keepers <- attr(fslg_out, "keepers")
if (!is.null(keepers)) diagnostics_list[["FSlg"]] <- keepers
}
attr(fslg_out, "sg_hat") <- NULL
attr(fslg_out, "keepers") <- NULL
results_list[["FSlg"]] <- cbind(df_pop, fslg_out)
}
if (is.null(method_specs) && run_grf) {
# Resolve id_name from merged GRF params (falls back to "id")
id_name_resolved <- grf_merged$id.name %||% "id"
# Effective names for estimation (see FS sync comment above)
grf_est_outcome <- fs_params[["outcome.name"]] %||% outcome_name
grf_est_event <- fs_params[["event.name"]] %||% event_name
grf_out <- .run_grf_analysis_gen(
data = sim_data, confounders_name = confounders_name,
params = grf_merged, dgm = dgm,
cox_formula = cox_formula, cox_formula_adj = cox_formula_adj,
outcome_name = grf_est_outcome, event_name = grf_est_event,
treat_name = treat_name, harm_col = harm_col,
label = "GRF", verbose = show_verbose, debug = debug,
outcome_type = fs_params$outcome_type,
effect_measure = fs_params$effect_measure,
offset_name = fs_params$offset.name,
id_name = id_name_resolved,
keep = if (keep_this_sim) keep else character(0)
)
sg_hat_list[["GRF"]] <- attr(grf_out, "sg_hat")
if (keep_this_sim) {
keepers <- attr(grf_out, "keepers")
if (!is.null(keepers)) diagnostics_list[["GRF"]] <- keepers
}
attr(grf_out, "sg_hat") <- NULL
attr(grf_out, "keepers") <- NULL
results_list[["GRF"]] <- cbind(df_pop, grf_out)
}
# ── Generalized method dispatch (methods != NULL) ────────────────────────
# Each arm is run via forestsearch() through .run_fs_analysis_gen(), with
# subgroup_method / grf_selection / sg_focus / screening knobs set per arm.
# The arm label names the selector ("dina-effMaxSG", "grf-tree", ...);
# forestsearch() is the shared inference backbone and is absent from labels.
if (!is.null(method_specs)) {
for (arm_label in names(method_specs)) {
# Precedence: default_sim_params() -> fs_params -> per-arm overrides.
# .modify_keep_null() preserves an explicit n.min = NULL so the
# sample-size-adaptive rule reaches forestsearch().
fs_p <- .modify_keep_null(
.modify_keep_null(fs_defaults, fs_params),
method_specs[[arm_label]]
)
arm_out <- .run_fs_analysis_gen(
data = sim_data, confounders_name = confounders_name,
params = fs_p, dgm = dgm,
cox_formula = cox_formula, cox_formula_adj = cox_formula_adj,
outcome_name = outcome_name, event_name = event_name,
treat_name = treat_name, harm_col = harm_col,
label = arm_label, verbose = show_verbose,
keep = if (keep_this_sim) keep else character(0)
)
sg_hat_list[[arm_label]] <- attr(arm_out, "sg_hat")
if (keep_this_sim) {
keepers <- attr(arm_out, "keepers")
if (!is.null(keepers)) diagnostics_list[[arm_label]] <- keepers
}
attr(arm_out, "sg_hat") <- NULL
attr(arm_out, "keepers") <- NULL
results_list[[arm_label]] <- cbind(df_pop, arm_out)
}
}
if (length(results_list) == 0) {
warning(
"No analyses were run. ",
if (is.null(method_specs))
"Check run_fs / run_fs_grf / run_grf."
else
"Check the 'methods' specification."
)
return(NULL)
}
# ── Pairwise classification concordance ──────────────────────────────────
# When multiple methods run on the same sim_data, compute per-subject
# agreement between each pair. Stored as columns agree.M1.M2 and
# kappa.M1.M2 on every row (values are per-sim, identical across methods).
valid_sg <- names(sg_hat_list)[
vapply(sg_hat_list, function(x) !is.null(x) && length(x) > 0, logical(1))
]
if (length(valid_sg) >= 2) {
pairs <- utils::combn(valid_sg, 2, simplify = FALSE)
for (pair in pairs) {
sg1 <- sg_hat_list[[pair[1]]]
sg2 <- sg_hat_list[[pair[2]]]
if (length(sg1) == length(sg2)) {
agree <- mean(sg1 == sg2)
# Cohen's kappa
ct <- table(factor(sg1, levels = 0:1),
factor(sg2, levels = 0:1))
p_obs <- sum(diag(ct)) / sum(ct)
p_exp <- sum(rowSums(ct) * colSums(ct)) / sum(ct)^2
kappa <- if (abs(1 - p_exp) < 1e-10) 1.0 else
(p_obs - p_exp) / (1 - p_exp)
col_agree <- paste0("agree.", pair[1], ".", pair[2])
col_kappa <- paste0("kappa.", pair[1], ".", pair[2])
for (nm in names(results_list)) {
results_list[[nm]][[col_agree]] <- agree
results_list[[nm]][[col_kappa]] <- kappa
}
}
}
}
result <- data.table::rbindlist(results_list, fill = TRUE)
# Attach heavy diagnostics (only populated when keep_this_sim = TRUE).
# Consumers can retrieve via attr(result, "diagnostics"). Note:
# data.table::rbindlist() may drop this attribute in downstream
# collect_results() unless the caller preserves per-sim structure;
# see collect_results(..., keep_diagnostics = TRUE).
if (length(diagnostics_list) > 0L) {
# Tag with sim_id for provenance when collected across replicates
attr(diagnostics_list, "sim_id") <- sim_id
attr(result, "diagnostics") <- diagnostics_list
}
if (show_verbose)
message(sprintf("\n[4] Done: %d rows x %d cols\n%s",
nrow(result), ncol(result),
paste(rep("=", 60), collapse = "")))
result
}
# =============================================================================
# Internal: ForestSearch analysis
# =============================================================================
#' @keywords internal
.run_fs_analysis_gen <- function(
data, confounders_name, params, dgm,
cox_formula, cox_formula_adj,
outcome_name, event_name, treat_name, harm_col,
label, verbose,
keep = character(0)
) {
if (verbose) {
message(sprintf("\n [%s] ForestSearch: n=%d events=%d (%.1f%%)",
label, nrow(data),
sum(data[[event_name]]), 100 * mean(data[[event_name]])))
}
fs_args <- list(
df.analysis = data,
confounders.name = confounders_name,
details = verbose,
plot.sg = FALSE
)
# Parameters we ALWAYS manage internally — users cannot override
# these via fs_params even if they try. The rest flows from
# formals(forestsearch) via filter_valid_args(), so any new
# forestsearch() argument is automatically reachable.
fs_internal_args <- c(
"df.analysis", # we pass `data` explicitly
"confounders.name", # we pass `confounders_name` explicitly
"details", # driven by verbose argument above
"plot.sg", # always FALSE in simulation loops
"quiet" # set below to TRUE
)
user_fs_args <- filter_valid_args(
params = params,
target_fun = forestsearch,
exclude = fs_internal_args,
warn_unknown = FALSE # silent drop matches legacy behavior
)
# NULL-preserving merge (not modifyList): an explicit n.min = NULL in
# `params` must survive to forestsearch() so the sample-size-adaptive rule
# fires; modifyList() would strip it and silently revert to the formal
# default. Affects both the legacy boolean path and the methods path.
fs_args <- .modify_keep_null(fs_args, user_fs_args)
fs_args$quiet <- TRUE
fs_result <- tryCatch(
do.call(forestsearch, fs_args),
error = function(e) { warning(label, " failed: ", e$message); NULL }
)
has_result <- !is.null(fs_result) && (
(!is.null(fs_result$grp.consistency$out_sg$result) &&
nrow(fs_result$grp.consistency$out_sg$result) > 0) ||
# GRF / DINA modes carry the selected subgroup in sg.harm and the
# membership in df.est$treat.recommend; grp.consistency$out_sg$result is
# NULL for them, so recognize the sg.harm shape too.
(!is.null(fs_result$sg.harm) && length(fs_result$sg.harm) > 0L &&
!all(is.na(fs_result$sg.harm)))
)
# Effective names for estimation: honour fs_params overrides.
# Critical for Poisson+offset (IRR) where fs_params sets
# outcome.name = "event_sim" (binary count) but the function-level
# outcome_name still holds "y_sim" (survival time). Without this
# sync, the Poisson GLM receives continuous times as the response,
# producing dpois() non-integer warnings and biased estimates.
est_outcome <- params[["outcome.name"]] %||% outcome_name
est_event <- params[["event.name"]] %||% event_name
out <- .extract_fs_estimates_gen(
df = data,
fs_res = if (has_result) fs_result$grp.consistency$out_sg$result else NULL,
fs_full = if (has_result) fs_result else NULL,
dgm = dgm,
cox_formula = cox_formula,
cox_formula_adj = cox_formula_adj,
outcome_name = est_outcome,
event_name = est_event,
treat_name = treat_name,
harm_col = harm_col,
analysis = label,
verbose = verbose,
outcome_type = params$outcome_type,
effect_measure = params$effect_measure,
offset_name = params$offset.name
)
# ── Populate FS-specific scalar diagnostics ──────────────────────────────
# These are always attached; callers that don't care can ignore them.
# Read safely — any path may be NULL when fs_result is NULL or partial.
.sg_harm <- if (has_result) fs_result$sg.harm else NULL
.gc <- if (!is.null(fs_result)) fs_result$grp.consistency else NULL
out$sg.def <- if (!is.null(.sg_harm) && length(.sg_harm) > 0L &&
!all(is.na(.sg_harm))) {
paste(.sg_harm, collapse = " & ")
} else {
""
}
out$sg.n_factors <- if (!is.null(.sg_harm))
sum(!is.na(.sg_harm)) else 0L
out$n_candidates_evaluated <- if (!is.null(.gc$n_candidates_evaluated))
as.integer(.gc$n_candidates_evaluated) else NA_integer_
out$n_candidates_total <- if (!is.null(.gc$n_candidates_total))
as.integer(.gc$n_candidates_total) else NA_integer_
out$n_passed <- if (!is.null(.gc$n_passed))
as.integer(.gc$n_passed) else NA_integer_
out$consistency_algorithm <- if (!is.null(.gc$algorithm))
as.character(.gc$algorithm) else NA_character_
out$early_stop_triggered <- if (!is.null(.gc$early_stop_triggered))
as.logical(.gc$early_stop_triggered) else NA
out$fs_minutes <- if (!is.null(fs_result$minutes_all))
as.numeric(fs_result$minutes_all) else NA_real_
# ── Assemble keepers (heavy objects) when requested ─────────────────────
keepers <- NULL
if (length(keep) > 0L && !is.null(fs_result)) {
keepers <- list()
if ("fs_full" %in% keep) {
# Strip df.est (potentially large analysis data frame) to control
# memory; users can request it explicitly via keep = "df.est".
fs_keep <- fs_result
fs_keep$df.est <- NULL
fs_keep$df.predict <- NULL
fs_keep$df.test <- NULL
keepers$fs_full <- fs_keep
}
if ("df.est" %in% keep && !is.null(fs_result$df.est)) {
keepers$df.est <- fs_result$df.est
}
if ("candidate_table" %in% keep && has_result) {
keepers$candidate_table <- fs_result$grp.consistency$out_sg$result
}
}
# sg_hat is carried by the caller for concordance calculation;
# keepers is populated (possibly NULL) for the diagnostics accumulator.
attr(out, "keepers") <- keepers
out
}
# =============================================================================
# Internal: NA subgroup membership in the classification extractors
# =============================================================================
# A subject whose membership (sg_hat) is NA cannot be scored as in or out of
# the identified subgroup. In .extract_fs_estimates_gen() the confusion
# counts then become NA and `if ((tp + fn) > 0)` / `if ((tn + fp) > 0)`
# stopped with R's "missing value where TRUE/FALSE needed"; in
# .extract_grf_estimates_gen() size.H becomes NA and `if (out$size.H > 10)`
# stopped the same way. .stop_na_membership() is called at those two points
# only when membership has an NA, so exactly the same cases stop; it gives the
# reason instead. Membership is not dropped or recoded (no na.rm).
# `sg_def` is the subgroup definition at hand (cut labels, cut expressions or
# M.* factor names); the columns of `cols` it refers to are named, and the
# count is given alone when none is found.
.stop_na_membership <- function(sg_hat, sg_def = NULL, cols = character(0)) {
covs <- tryCatch(.sg_def_columns(sg_def, cols),
error = function(e) character(0))
stop(sprintf(paste0("%d of %d subjects have no subgroup assignment: a ",
"covariate that defines the identified subgroup%s has ",
"missing values."),
sum(is.na(sg_hat)), length(sg_hat),
if (length(covs)) sprintf(" (%s)", paste(covs, collapse = ", "))
else ""),
call. = FALSE)
}
# Columns of `cols` named in subgroup-definition strings, in order of first
# appearance. Each identifier-like token that is a column is kept; a token
# that is not (an M.* factor name "var.level", see create_subgroup_indicator())
# is cut at its first dot.
.sg_def_columns <- function(sg_def, cols) {
txt <- as.character(unlist(sg_def, use.names = FALSE))
txt <- txt[!is.na(txt)]
if (!length(txt) || !length(cols)) return(character(0))
toks <- unlist(regmatches(txt, gregexpr("[A-Za-z.][A-Za-z0-9._]*", txt)),
use.names = FALSE)
toks <- ifelse(toks %in% cols, toks, sub("\\..*$", "", toks))
as.character(intersect(toks, cols))
}
# Effect on the arms' own scale from a two-arm fit glm(y ~ treat) made by
# the estimate extractors below (treat coded 0/1: the intercept is the control
# arm, intercept + coefficient the treatment arm). "RD" = p1 - p0 and
# "RR" = p1 / p0, the fitted arm proportions of the binomial fit; "IRD" =
# r1 - r0, the fitted arm rates of the Poisson fit, per unit of exposure when
# the fit has the log-exposure offset, the convention under which the "IRR"
# value exp(coefficient) equals r1 / r0. Treatment minus (over) control, the
# direction compute_aor() uses for the truth columns. (With an offset on a
# binomial fit, which no measure documents, the values are those at
# log-exposure 0.) A value that is not finite is NA_real_, the extractors'
# failure value. An arm with no events has a fitted proportion near zero, so
# RR is extreme but finite (very large when the control arm has none, near
# zero when the treatment arm has none), as OR is.
.glm_arm_effect <- function(fit, effect_measure) {
cf <- stats::coef(fit)
v0 <- fit$family$linkinv(cf[[1]])
v1 <- fit$family$linkinv(cf[[1]] + cf[[2]])
val <- if (effect_measure == "RR") v1 / v0 else v1 - v0
if (is.finite(val)) val else NA_real_
}
# =============================================================================
# Internal: extract FS estimates (column-name-general)
# =============================================================================
#' @keywords internal
.extract_fs_estimates_gen <- function(
df, fs_res, fs_full, dgm,
cox_formula, cox_formula_adj,
outcome_name, event_name, treat_name, harm_col,
analysis, verbose,
outcome_type = NULL, effect_measure = NULL, offset_name = NULL
) {
# ── Detect GLM mode ──────────────────────────────────────────────────────
is_glm <- !is.null(outcome_type) && outcome_type != "survival"
out <- data.table::data.table(
analysis = analysis,
any.H = 0L,
size.H = NA_integer_,
size.Hc = nrow(df),
hr.H.true = NA_real_, hr.H.hat = NA_real_,
hr.Hc.true = NA_real_, hr.Hc.hat = NA_real_,
ahr.H.true = NA_real_, ahr.Hc.true = NA_real_,
ahr.H.hat = NA_real_, ahr.Hc.hat = NA_real_,
cde.H.true = NA_real_, cde.Hc.true = NA_real_,
cde.H.hat = NA_real_, cde.Hc.hat = NA_real_,
hr.itt = NA_real_,
hr.adj.itt = NA_real_,
ppv = NA_real_, npv = NA_real_, sens = NA_real_, spec = NA_real_,
p.cens = 1 - mean(df[[event_name]]),
taumax = max(df[[outcome_name]])
)
# ── Build estimation closures ─────────────────────────────────────────────
if (is_glm) {
# Resolve GLM family from effect_measure
glm_family <- switch(
effect_measure %||% "OR",
"OR" = , "RD" = stats::binomial(),
"IRR" = , "IRD" = stats::poisson(),
"MD" = stats::gaussian(),
stats::binomial()
)
# Whether the treatment coefficient is exponentiated (OR, IRR) or used as
# it is (MD). RD, RR and IRD are taken from the fitted arm values instead
# (arm_scale, tested first; see .glm_arm_effect()), so the "RR" entry of
# log_scale is not reached.
log_scale <- effect_measure %in% c("OR", "IRR", "RR")
arm_scale <- effect_measure %in% c("RD", "RR", "IRD")
.glm_effect <- function(sub_df) {
tryCatch({
# GLM response is outcome_name — the column that matches the GLM
# family. For native GLM sims this is "y_sim"; for Poisson+offset
# on survival data the caller passes "event_sim" (binary indicator)
# so the response is a 0/1 count with log(time) as offset.
if (!is.null(offset_name) && offset_name %in% names(sub_df)) {
off_vec <- log(pmax(sub_df[[offset_name]], 1e-6))
fit <- stats::glm(sub_df[[outcome_name]] ~ sub_df[[treat_name]],
family = glm_family, offset = off_vec)
} else {
fit <- stats::glm(sub_df[[outcome_name]] ~ sub_df[[treat_name]],
family = glm_family)
}
b <- coef(fit)[[2]] # treatment coefficient
if (arm_scale) .glm_arm_effect(fit, effect_measure)
else if (log_scale) exp(b) else b
}, error = function(e) NA_real_)
}
# ITT
out$hr.itt <- .glm_effect(df)
} else {
# ── Survival (Cox) ITT ─────────────────────────────────────────────────
out$hr.itt <- tryCatch(
exp(survival::coxph(
survival::Surv(df[[outcome_name]], df[[event_name]]) ~ df[[treat_name]]
)$coefficients),
error = function(e) NA_real_
)
}
# Adjusted ITT (Cox only; skip for GLM)
if (!is_glm && !is.null(cox_formula_adj)) {
out$hr.adj.itt <- tryCatch(
exp(survival::coxph(cox_formula_adj, data = df)$coefficients[treat_name]),
error = function(e) NA_real_
)
}
# A subgroup is "found" when the consistency result table has rows OR the
# engine returned a treat.recommend assignment with harm members (GRF / DINA
# modes, where fs_res is NULL but membership lives in fs_full$df.est).
# A treat.recommend assignment with no harm member is an empty identified
# set: a no-find, whatever the result table holds.
.has_treat_rec <- !is.null(fs_full) && !is.null(fs_full$df.est) &&
"treat.recommend" %in% names(fs_full$df.est) &&
any(fs_full$df.est$treat.recommend == 0L, na.rm = TRUE)
if ((is.null(fs_res) || nrow(fs_res) == 0 ||
"treat.recommend" %in% names(fs_full$df.est)) && !.has_treat_rec) {
out$hr.Hc.hat <- out$hr.itt
out$size.H <- 0L
out$size.Hc <- nrow(df)
# Classification when nothing found: everyone is predicted Hc.
# With nothing found the complement is everyone: sens(Hc) = 1 and
# ppv(Hc) = |Hc|/N, as defined in León et al. (2024), Section 3.
if (harm_col %in% names(df)) {
true_H <- df[[harm_col]] == 1L
n_true_H <- sum(true_H)
if (n_true_H > 0) {
# Alt: H exists but was not found.
# sens = 0 (none of H captured), ppv = 0 (no Ĥ predicted).
out$sens <- 0
out$ppv <- 0
out$spec <- 1 # sens(Hc): all of Hc is in the complement
out$npv <- sum(!true_H) / nrow(df) # ppv(Hc) = |Hc|/N
}
# Null (n_true_H == 0): sens/ppv remain NA (undefined).
# spec = 1, npv = 1 (everyone is Hc and predicted Hc).
if (n_true_H == 0) {
out$spec <- 1
out$npv <- 1
}
}
attr(out, "sg_hat") <- rep(0L, nrow(df))
return(out)
}
out$any.H <- 1L
# Build subgroup indicator
df_sg <- NULL
if (!is.null(fs_full) && !is.null(fs_full$df.est) &&
"treat.recommend" %in% names(fs_full$df.est)) {
df$sg_hat <- as.integer(fs_full$df.est$treat.recommend == 0)
sg_def_txt <- fs_full$sg.harm # definition at hand, for the NA message
} else {
sg_factors <- character(0)
for (i in seq_len(min(7, ncol(fs_res)))) {
cn <- paste0("M.", i)
if (cn %in% names(fs_res) && !is.na(fs_res[[cn]][1]))
sg_factors <- c(sg_factors, fs_res[[cn]][1])
}
sg_def_txt <- sg_factors # definition at hand, for the NA message
if (length(sg_factors) > 0)
df$sg_hat <- create_subgroup_indicator(df, sg_factors)
if (length(sg_factors) == 0 || !any(df$sg_hat == 1L, na.rm = TRUE)) {
# No factor recovered, or an indicator with no member: an empty
# identified set, scored as the no-find path above scores it.
out$any.H <- 0L
out$hr.Hc.hat <- out$hr.itt
out$size.H <- 0L
out$size.Hc <- nrow(df)
if (harm_col %in% names(df)) {
true_H <- df[[harm_col]] == 1L
n_true_H <- sum(true_H)
if (n_true_H > 0) {
out$sens <- 0; out$ppv <- 0
out$spec <- 1; out$npv <- sum(!true_H) / nrow(df)
} else {
out$spec <- 1; out$npv <- 1
}
}
attr(out, "sg_hat") <- rep(0L, nrow(df))
return(out)
}
}
out$size.H <- sum(df$sg_hat, na.rm = TRUE)
out$size.Hc <- sum(df$sg_hat == 0L, na.rm = TRUE)
# ── Subgroup effect estimates ────────────────────────────────────────────
if (is_glm) {
if (out$size.H > 10) out$hr.H.hat <- .glm_effect(df[df$sg_hat == 1, ])
if (out$size.Hc > 10) out$hr.Hc.hat <- .glm_effect(df[df$sg_hat == 0, ])
} else {
.cox_hr <- function(sub_df) tryCatch(
exp(survival::coxph(
survival::Surv(sub_df[[outcome_name]], sub_df[[event_name]]) ~
sub_df[[treat_name]]
)$coefficients),
error = function(e) NA_real_
)
if (out$size.H > 10) out$hr.H.hat <- .cox_hr(df[df$sg_hat == 1, ])
if (out$size.Hc > 10) out$hr.Hc.hat <- .cox_hr(df[df$sg_hat == 0, ])
}
# ── AHR and CDE (survival) / AOR (GLM) ───────────────────────────────────
if (!is_glm) {
if ("loghr_po" %in% names(df)) {
out$ahr.H.hat <- compute_ahr(df, df$sg_hat)
out$ahr.Hc.hat <- compute_ahr(df, 1L - df$sg_hat)
}
if (all(c("theta_0", "theta_1") %in% names(df))) {
out$cde.H.hat <- compute_cde(df, df$sg_hat)
out$cde.Hc.hat <- compute_cde(df, 1L - df$sg_hat)
}
} else {
# GLM: marginal causal effect from potential outcomes (p0/p1 or mu0/mu1)
em <- effect_measure %||% "OR"
if (any(c("p0", "mu0") %in% names(df))) {
out$ahr.H.hat <- compute_aor(df, df$sg_hat, em)
out$ahr.Hc.hat <- compute_aor(df, 1L - df$sg_hat, em)
# CDE analogue (binary OR only)
out$cde.H.hat <- compute_cde_glm(df, df$sg_hat, em)
out$cde.Hc.hat <- compute_cde_glm(df, 1L - df$sg_hat, em)
}
}
# ── True-subgroup classification metrics ─────────────────────────────────
if (harm_col %in% names(df)) {
true_H <- df[[harm_col]] == 1L
hat_H <- df$sg_hat == 1L
# NA membership: tp and fn, or tn and fp, below would be NA and the first
# `if` would stop. Stop here with the reason (same cases stop).
if (anyNA(hat_H)) .stop_na_membership(df$sg_hat, sg_def_txt, names(df))
tp <- sum(true_H & hat_H); fp <- sum(!true_H & hat_H)
tn <- sum(!true_H & !hat_H); fn <- sum(true_H & !hat_H)
out$sens <- if ((tp + fn) > 0) tp / (tp + fn) else NA_real_
out$spec <- if ((tn + fp) > 0) tn / (tn + fp) else NA_real_
out$ppv <- if ((tp + fp) > 0) tp / (tp + fp) else NA_real_
# Empty estimated complement (everyone identified): npv 0/0 = 0.
out$npv <- if ((tn + fn) > 0) tn / (tn + fn) else 0
# True-subgroup effect estimates
if (is_glm) {
if (sum(true_H) > 10) out$hr.H.true <- .glm_effect(df[true_H, ])
if (sum(!true_H) > 10) out$hr.Hc.true <- .glm_effect(df[!true_H, ])
# Marginal causal effect in true subgroup (GLM analogue of AHR)
em <- effect_measure %||% "OR"
if (any(c("p0", "mu0") %in% names(df))) {
out$ahr.H.true <- compute_aor(df, as.integer(true_H), em)
out$ahr.Hc.true <- compute_aor(df, as.integer(!true_H), em)
# CDE analogue (binary OR only)
out$cde.H.true <- compute_cde_glm(df, as.integer(true_H), em)
out$cde.Hc.true <- compute_cde_glm(df, as.integer(!true_H), em)
}
} else {
if (sum(true_H) > 10) out$hr.H.true <- .cox_hr(df[true_H, ])
if (sum(!true_H) > 10) out$hr.Hc.true <- .cox_hr(df[!true_H, ])
if ("loghr_po" %in% names(df)) {
out$ahr.H.true <- compute_ahr(df, df[[harm_col]])
out$ahr.Hc.true <- compute_ahr(df, 1L - df[[harm_col]])
}
if (all(c("theta_0", "theta_1") %in% names(df))) {
out$cde.H.true <- compute_cde(df, df[[harm_col]])
out$cde.Hc.true <- compute_cde(df, 1L - df[[harm_col]])
}
}
}
attr(out, "sg_hat") <- if ("sg_hat" %in% names(df)) df$sg_hat else
rep(0L, nrow(df))
out
}
# =============================================================================
# Internal: GRF analysis
# =============================================================================
#' @keywords internal
.run_grf_analysis_gen <- function(
data, confounders_name, params, dgm,
cox_formula, cox_formula_adj,
outcome_name, event_name, treat_name, harm_col,
label, verbose, debug,
outcome_type = NULL, effect_measure = NULL, offset_name = NULL,
id_name = "id",
keep = character(0)
) {
# ── GRF function dispatch ────────────────────────────────────────────────
# GLM outcomes route to grf.subg.harm.glm(); survival (or NULL) routes
# to the original grf.subg.harm.survival(). When outcome_type is NULL
# (survival scenarios that don't set it), the survival path runs exactly
# as before — no behavior change.
is_glm <- !is.null(outcome_type) && outcome_type != "survival"
grf_fn_name <- if (is_glm) "grf.subg.harm.glm" else "grf.subg.harm.survival"
grf_fun <- tryCatch(
get(grf_fn_name, mode = "function",
envir = asNamespace("forestsearch")),
error = function(e) NULL
)
if (is.null(grf_fun)) {
warning(grf_fn_name, " not found. Skipping GRF analysis.")
out <- .extract_grf_estimates_gen(
df = data, grf_est = NULL, dgm = dgm,
cox_formula = cox_formula, cox_formula_adj = cox_formula_adj,
outcome_name = outcome_name, event_name = event_name,
treat_name = treat_name, harm_col = harm_col,
analysis = label, verbose = verbose, debug = debug,
outcome_type = outcome_type, effect_measure = effect_measure,
offset_name = offset_name, id_name = id_name
)
out$sg.def <- ""
out$sg.n_factors <- 0L
out$grf_selected_depth <- NA_integer_
attr(out, "keepers") <- NULL
return(out)
}
grf_args <- list(data = data, confounders.name = confounders_name,
details = verbose)
# Parameters always managed internally — users cannot override these
# via grf_params. The rest flows from formals(grf_fun), so any new
# grf.subg.harm.*() argument is automatically reachable. grf_fun
# was dispatched above to either grf.subg.harm.survival (is_glm FALSE)
# or grf.subg.harm.glm (is_glm TRUE), so the allowlist tracks the
# correct target signature automatically.
grf_internal_args <- c(
"data",
"confounders.name",
"details"
)
user_grf_args <- filter_valid_args(
params = params,
target_fun = grf_fun,
exclude = grf_internal_args,
warn_unknown = FALSE
)
grf_args <- utils::modifyList(grf_args, user_grf_args)
# GLM-specific parameters (ignored by grf.subg.harm.survival)
if (is_glm) {
grf_args$outcome_type <- outcome_type
# Count outcome: pass "log_IRR" for the simulation's "IRR" or "IRD". The
# forest fit does not use effect_measure (grf.subg.harm.glm() accepts
# only "log_IRR" or "log_RR" for a count and stores it); the extractor
# below computes the reported effect on the simulation's own scale.
if (identical(outcome_type, "count")) {
grf_args$effect_measure <- "log_IRR"
} else if (!is.null(effect_measure)) {
grf_args$effect_measure <- effect_measure
}
if (!is.null(offset_name)) grf_args$offset.name <- offset_name
# grf.subg.harm.glm() does NOT accept event.name — remove it
# to prevent "unused argument" error from do.call()
grf_args$event.name <- NULL
# Match forestsearch()'s adverse_outcome default: TRUE for binary/count.
# This ensures standalone GRF uses the same Y-flip as FS's internal
# GRF pre-screening, producing consistent subgroup identification.
ao <- params$adverse_outcome
if (is.null(ao)) ao <- outcome_type %in% c("binary", "count")
grf_args$adverse_outcome <- ao
# Pass tune_grf if set (default FALSE preserves existing behavior)
tg <- params$tune_grf
if (!is.null(tg)) grf_args$tune_grf <- tg
}
grf_result <- tryCatch(
do.call(grf_fun, grf_args),
error = function(e) { warning(label, " failed: ", e$message); NULL }
)
out <- .extract_grf_estimates_gen(
df = data, grf_est = grf_result, dgm = dgm,
cox_formula = cox_formula, cox_formula_adj = cox_formula_adj,
outcome_name = outcome_name, event_name = event_name,
treat_name = treat_name, harm_col = harm_col,
analysis = label, verbose = verbose, debug = debug,
outcome_type = outcome_type, effect_measure = effect_measure,
offset_name = offset_name, id_name = id_name
)
# ── Populate GRF-specific scalar diagnostics ─────────────────────────────
# For GRF results, sg.harm.id carries the cut-expression vector
# (character). See docs in grf_subg_harm_glm.R / grf_main.R.
.sg_cuts <- if (!is.null(grf_result))
grf_result$sg.harm.id %||% grf_result$sg_harm_id else NULL
out$sg.def <- if (!is.null(.sg_cuts) && length(.sg_cuts) > 0L &&
!all(is.na(.sg_cuts)) && !all(.sg_cuts == "")) {
paste(.sg_cuts, collapse = " & ")
} else {
""
}
out$sg.n_factors <- if (!is.null(.sg_cuts))
sum(!is.na(.sg_cuts) & .sg_cuts != "") else 0L
out$grf_selected_depth <- if (!is.null(grf_result$selected_depth))
as.integer(grf_result$selected_depth) else NA_integer_
# ── Assemble GRF keepers when requested ─────────────────────────────────
keepers <- NULL
if (length(keep) > 0L && !is.null(grf_result) && "grf_full" %in% keep) {
keepers <- list(grf_full = grf_result)
}
attr(out, "keepers") <- keepers
out
}
# =============================================================================
# Internal: extract GRF estimates (column-name-general)
# =============================================================================
#' @keywords internal
.extract_grf_estimates_gen <- function(
df, grf_est, dgm,
cox_formula, cox_formula_adj,
outcome_name, event_name, treat_name, harm_col,
analysis, verbose, debug,
outcome_type = NULL, effect_measure = NULL, offset_name = NULL,
id_name = "id"
) {
# ── Detect GLM mode ──────────────────────────────────────────────────────
is_glm <- !is.null(outcome_type) && outcome_type != "survival"
out <- data.table::data.table(
analysis = analysis,
any.H = 0L,
size.H = NA_integer_,
size.Hc = nrow(df),
hr.H.true = NA_real_, hr.H.hat = NA_real_,
hr.Hc.true = NA_real_, hr.Hc.hat = NA_real_,
ahr.H.true = NA_real_, ahr.Hc.true = NA_real_,
ahr.H.hat = NA_real_, ahr.Hc.hat = NA_real_,
cde.H.true = NA_real_, cde.Hc.true = NA_real_,
cde.H.hat = NA_real_, cde.Hc.hat = NA_real_,
hr.itt = NA_real_,
hr.adj.itt = NA_real_,
ppv = NA_real_, npv = NA_real_, sens = NA_real_, spec = NA_real_,
p.cens = 1 - mean(df[[event_name]]),
taumax = max(df[[outcome_name]])
)
# ── Build estimation closures ─────────────────────────────────────────────
if (is_glm) {
glm_family <- switch(
effect_measure %||% "OR",
"OR" = , "RD" = stats::binomial(),
"IRR" = , "IRD" = stats::poisson(),
"MD" = stats::gaussian(),
stats::binomial()
)
# Whether the treatment coefficient is exponentiated (OR, IRR) or used as
# it is (MD). RD, RR and IRD are taken from the fitted arm values instead
# (arm_scale, tested first; see .glm_arm_effect()), so the "RR" entry of
# log_scale is not reached.
log_scale <- effect_measure %in% c("OR", "IRR", "RR")
arm_scale <- effect_measure %in% c("RD", "RR", "IRD")
.glm_effect_grf <- function(sub_df, oc, ec, tc) {
tryCatch({
# GLM response is oc (outcome_name). For Poisson+offset on
# survival data, the caller sets oc = "event_sim" (binary count)
# with offset = log(time); for native GLM sims, oc = "y_sim".
if (!is.null(offset_name) && offset_name %in% names(sub_df)) {
off_vec <- log(pmax(sub_df[[offset_name]], 1e-6))
fit <- stats::glm(sub_df[[oc]] ~ sub_df[[tc]],
family = glm_family, offset = off_vec)
} else {
fit <- stats::glm(sub_df[[oc]] ~ sub_df[[tc]],
family = glm_family)
}
b <- coef(fit)[[2]]
if (arm_scale) .glm_arm_effect(fit, effect_measure)
else if (log_scale) exp(b) else b
}, error = function(e) NA_real_)
}
out$hr.itt <- .glm_effect_grf(df, outcome_name, event_name, treat_name)
} else {
out$hr.itt <- tryCatch(
exp(survival::coxph(
survival::Surv(df[[outcome_name]], df[[event_name]]) ~ df[[treat_name]]
)$coefficients),
error = function(e) NA_real_
)
}
if (!is_glm && !is.null(cox_formula_adj)) {
out$hr.adj.itt <- tryCatch(
exp(survival::coxph(cox_formula_adj, data = df)$coefficients[treat_name]),
error = function(e) NA_real_
)
}
if (is.null(grf_est)) {
out$hr.Hc.hat <- out$hr.itt
out$size.H <- 0L
out$size.Hc <- nrow(df)
# Classification when GRF fails: everyone is predicted Hc.
if (harm_col %in% names(df)) {
true_H <- df[[harm_col]] == 1L
n_true_H <- sum(true_H)
if (n_true_H > 0) {
out$sens <- 0; out$ppv <- 0
out$spec <- 1; out$npv <- sum(!true_H) / nrow(df)
} else {
out$spec <- 1; out$npv <- 1
}
}
attr(out, "sg_hat") <- rep(0L, nrow(df))
return(out)
}
# GRF subgroup detection
sg_harm_id <- grf_est$sg.harm.id %||% grf_est$sg_harm_id
has_sg <- !is.null(sg_harm_id) && length(sg_harm_id) > 0 &&
!all(is.na(sg_harm_id))
has_tr <- !is.null(grf_est$data) &&
"treat.recommend" %in% names(grf_est$data)
# A treat.recommend assignment with no harm member is an empty identified
# set: a no-find, whatever sg.harm.id holds.
if (!has_sg || !has_tr ||
!any(grf_est$data$treat.recommend == 0L, na.rm = TRUE)) {
out$hr.Hc.hat <- out$hr.itt
out$size.H <- 0L
out$size.Hc <- nrow(df)
if (harm_col %in% names(df)) {
true_H <- df[[harm_col]] == 1L
n_true_H <- sum(true_H)
if (n_true_H > 0) {
out$sens <- 0; out$ppv <- 0
out$spec <- 1; out$npv <- sum(!true_H) / nrow(df)
} else {
out$spec <- 1; out$npv <- 1
}
}
attr(out, "sg_hat") <- rep(0L, nrow(df))
return(out)
}
out$any.H <- 1L
grf_data <- grf_est$data
harm_ind <- as.integer(grf_data$treat.recommend == 0)
grf_data$sg_hat <- harm_ind
# NA membership: size.H below would be NA and `if (out$size.H > 10)` would
# stop. Stop here with the reason (same cases stop).
if (anyNA(harm_ind))
.stop_na_membership(harm_ind, sg_harm_id, names(grf_data))
out$size.H <- sum(harm_ind)
out$size.Hc <- sum(harm_ind == 0L)
# Detect column names in grf_data (may differ from sim_data names)
o_col <- if (outcome_name %in% names(grf_data)) outcome_name else
if ("y.sim" %in% names(grf_data)) "y.sim" else outcome_name
e_col <- if (event_name %in% names(grf_data)) event_name else
if ("event.sim" %in% names(grf_data)) "event.sim" else event_name
t_col <- if (treat_name %in% names(grf_data)) treat_name else
if ("treat" %in% names(grf_data)) "treat" else treat_name
if (is_glm) {
if (out$size.H > 10) out$hr.H.hat <-
.glm_effect_grf(grf_data[grf_data$sg_hat == 1, ], o_col, e_col, t_col)
if (out$size.Hc > 10) out$hr.Hc.hat <-
.glm_effect_grf(grf_data[grf_data$sg_hat == 0, ], o_col, e_col, t_col)
} else {
.cox_hr <- function(sub_df, oc, ec, tc) tryCatch(
exp(survival::coxph(
survival::Surv(sub_df[[oc]], sub_df[[ec]]) ~ sub_df[[tc]]
)$coefficients),
error = function(e) NA_real_
)
if (out$size.H > 10) out$hr.H.hat <-
.cox_hr(grf_data[grf_data$sg_hat == 1, ], o_col, e_col, t_col)
if (out$size.Hc > 10) out$hr.Hc.hat <-
.cox_hr(grf_data[grf_data$sg_hat == 0, ], o_col, e_col, t_col)
}
# AHR / CDE (survival) / AOR (GLM)
if (!is_glm) {
.merge_sg <- function(base_df, sg_df, cols) {
if (id_name %in% names(base_df) && id_name %in% names(sg_df))
merge(base_df[, c(id_name, cols), drop = FALSE],
sg_df[, c(id_name, "sg_hat")], by = id_name, all.y = TRUE)
else if (nrow(base_df) == nrow(sg_df)) {
base_df$sg_hat <- sg_df$sg_hat; base_df
} else NULL
}
if ("loghr_po" %in% names(df)) {
m <- .merge_sg(df, grf_data, "loghr_po")
if (!is.null(m)) {
out$ahr.H.hat <- compute_ahr(m, m$sg_hat)
out$ahr.Hc.hat <- compute_ahr(m, 1L - m$sg_hat)
}
}
if (all(c("theta_0", "theta_1") %in% names(df))) {
m <- .merge_sg(df, grf_data, c("theta_0", "theta_1"))
if (!is.null(m)) {
out$cde.H.hat <- compute_cde(m, m$sg_hat)
out$cde.Hc.hat <- compute_cde(m, 1L - m$sg_hat)
}
}
} else {
# GLM: marginal causal effect from potential outcomes
po_cols <- intersect(c("p0", "p1", "mu0", "mu1"), names(df))
if (length(po_cols) >= 2) {
.merge_sg_po <- function(base_df, sg_df, cols) {
if (id_name %in% names(base_df) && id_name %in% names(sg_df))
merge(base_df[, c(id_name, cols), drop = FALSE],
sg_df[, c(id_name, "sg_hat")], by = id_name, all.y = TRUE)
else if (nrow(base_df) == nrow(sg_df)) {
base_df$sg_hat <- sg_df$sg_hat; base_df
} else NULL
}
m <- .merge_sg_po(df, grf_data, po_cols)
if (!is.null(m)) {
em <- effect_measure %||% "OR"
out$ahr.H.hat <- compute_aor(m, m$sg_hat, em)
out$ahr.Hc.hat <- compute_aor(m, 1L - m$sg_hat, em)
# CDE analogue (binary OR only)
out$cde.H.hat <- compute_cde_glm(m, m$sg_hat, em)
out$cde.Hc.hat <- compute_cde_glm(m, 1L - m$sg_hat, em)
}
}
}
# True-subgroup metrics
if (harm_col %in% names(df)) {
.merge_sg_class <- function(base_df, sg_df, hcol) {
if (id_name %in% names(base_df) && id_name %in% names(sg_df))
merge(base_df[, c(id_name, hcol), drop = FALSE],
sg_df[, c(id_name, "sg_hat")], by = id_name, all.y = TRUE)
else if (nrow(base_df) == nrow(sg_df)) {
base_df$sg_hat <- sg_df$sg_hat; base_df
} else NULL
}
m_class <- .merge_sg_class(df, grf_data, harm_col)
if (!is.null(m_class)) {
true_H <- m_class[[harm_col]] == 1L
hat_H <- m_class$sg_hat == 1L
tp <- sum(true_H & hat_H); fp <- sum(!true_H & hat_H)
tn <- sum(!true_H & !hat_H); fn <- sum(true_H & !hat_H)
out$sens <- if ((tp + fn) > 0) tp / (tp + fn) else NA_real_
out$spec <- if ((tn + fp) > 0) tn / (tn + fp) else NA_real_
out$ppv <- if ((tp + fp) > 0) tp / (tp + fp) else NA_real_
# Empty estimated complement (everyone identified): npv 0/0 = 0.
out$npv <- if ((tn + fn) > 0) tn / (tn + fn) else 0
}
true_H_df <- df[[harm_col]] == 1L
if (is_glm) {
if (sum(true_H_df) > 10) out$hr.H.true <-
.glm_effect_grf(df[true_H_df, ], outcome_name, event_name, treat_name)
if (sum(!true_H_df) > 10) out$hr.Hc.true <-
.glm_effect_grf(df[!true_H_df, ], outcome_name, event_name, treat_name)
# Marginal causal effect in true subgroup (GLM analogue of AHR)
em <- effect_measure %||% "OR"
if (any(c("p0", "mu0") %in% names(df))) {
out$ahr.H.true <- compute_aor(df, as.integer(true_H_df), em)
out$ahr.Hc.true <- compute_aor(df, as.integer(!true_H_df), em)
# CDE analogue (binary OR only)
out$cde.H.true <- compute_cde_glm(df, as.integer(true_H_df), em)
out$cde.Hc.true <- compute_cde_glm(df, as.integer(!true_H_df), em)
}
} else {
if (sum(true_H_df) > 10) out$hr.H.true <-
.cox_hr(df[true_H_df, ], outcome_name, event_name, treat_name)
if (sum(!true_H_df) > 10) out$hr.Hc.true <-
.cox_hr(df[!true_H_df, ], outcome_name, event_name, treat_name)
if ("loghr_po" %in% names(df)) {
out$ahr.H.true <- compute_ahr(df, df[[harm_col]])
out$ahr.Hc.true <- compute_ahr(df, 1L - df[[harm_col]])
}
if (all(c("theta_0", "theta_1") %in% names(df))) {
out$cde.H.true <- compute_cde(df, df[[harm_col]])
out$cde.Hc.true <- compute_cde(df, 1L - df[[harm_col]])
}
}
}
attr(out, "sg_hat") <- grf_data$sg_hat
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.