R/subgroup_search.R

Defines functions format_search_results create_result_row .fit_or_for_subgroup_vector fit_glm_for_subgroup_fast fit_glm_for_subgroup fit_cox_for_subgroup .fs_cox_lean_ok .fs_cox_two_group .fs_cox_lean_conventions meets_event_criteria calculate_event_counts meets_prevalence_threshold has_positive_variance evaluate_combination_with_status extract_idx_flagredundancy get_covs_in get_subgroup_membership get_combinations_info calculate_max_combinations generate_combination_indices prepare_search_data search_combinations_parallel subgroup.search

Documented in calculate_event_counts calculate_max_combinations create_result_row evaluate_combination_with_status extract_idx_flagredundancy fit_cox_for_subgroup fit_glm_for_subgroup format_search_results generate_combination_indices get_combinations_info get_covs_in get_subgroup_membership has_positive_variance meets_event_criteria meets_prevalence_threshold prepare_search_data subgroup.search

# =============================================================================
# SUBGROUP SEARCH FUNCTIONS (PARALLELIZED)
# =============================================================================

#' Subgroup Search for Treatment Effect Heterogeneity (Improved, Parallelized)
#'
#' Searches for subgroups with treatment effect heterogeneity using combinations
#' of candidate factors. Evaluates subgroups for minimum prevalence, event counts,
#' and hazard ratio threshold. Parallelizes the main search loop.
#'
#' @param Y Numeric vector of outcome (e.g., time-to-event).
#' @param Event Numeric vector of event indicators (0/1).
#' @param Treat Numeric vector of treatment group indicators (0/1).
#' @param ID Optional vector of subject IDs.
#' @param Z Matrix or data frame of candidate subgroup factors (binary indicators).
#' @param n.min Integer. Minimum subgroup size.
#' @param d0.min Integer. Minimum per-arm filter.  For survival and binary
#'   outcomes: minimum number of **events** in the control arm within the
#'   candidate subgroup.  Ignored for continuous outcomes (only
#'   \code{n.min} applies).
#' @param d1.min Integer. Same as \code{d0.min} for the treatment arm.
#' @param hr.threshold Numeric. `c1`, the \strong{screening threshold on a
#'   candidate subgroup's own effect}: a candidate is retained only if its
#'   fitted effect exceeds this value.
#'   The scale is the one the caller compares on, and it differs by path.
#'   On the survival path \code{effect_threshold} is \code{NULL}, so this
#'   value reaches the comparison unchanged and is compared against the
#'   fitted hazard ratio on the \strong{natural} scale
#'   (\code{fit_cox_for_subgroup()} returns \code{exp(coef)}): 1.25 means
#'   HR >= 1.25, not log(1.25).  On the GLM paths the value arrives already
#'   on the comparison scale that \code{forestsearch()} resolved from the
#'   effect measure -- link scale for the ratio measures (OR, RR, IRR),
#'   identity for RD, IRD and MD -- and is compared against the estimator's
#'   estimate on that same scale.  This is \code{forestsearch()}'s
#'   \code{effect.threshold} / \code{hr.threshold}.  It is not the per-split
#'   threshold (`c2`, \code{hr.consistency}) and not the consistency rate
#'   (`p*`, \code{pconsistency.threshold}); neither is applied here -- this
#'   function performs the screening stage only.
#' @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. Passing it emits one warning. Search scope is governed by
#'   \code{maxk} and the candidate-factor controls.
#'   The formal will be removed in a later release; drop it from calls.
#' @param minp Numeric. Minimum prevalence rate for each factor.
#' @param rmin Integer. Minimum required reduction in sample size when adding a factor.
#' @param details Logical. Print details during execution.
#' @param maxk Integer. Maximum number of factors in a subgroup.
#' @param parallel_workers Integer. Number of parallel workers (default: all available cores).
#' @param estimator_fn Closure or \code{NULL}. Effect-estimator closure from
#'   \code{\link{make_effect_estimator}} for GLM outcomes.  Default \code{NULL}
#'   (uses Cox model).
#' @param df_analysis Data frame or \code{NULL}. Full analysis dataset, passed
#'   to the GLM estimator for within-subgroup evaluation.
#' @param effect_threshold Numeric or \code{NULL}. GLM effect threshold for
#'   subgroup selection.  Default \code{NULL} (uses \code{hr.threshold}).
#' @param effect_measure Character or \code{NULL}. Effect measure name
#'   (e.g., \code{"OR"}, \code{"HR"}, \code{"RD"}).  Used for display labels
#'   in the filtering summary.  Default \code{NULL}.
#' @param outcome_type Character or \code{NULL}. One of \code{"survival"},
#'   \code{"binary"}, \code{"continuous"}, \code{"count"}.  Controls
#'   d0.min/d1.min interpretation: events per arm for binary/survival,
#'   ignored for continuous.  Default \code{NULL} (inferred from
#'   \code{estimator_fn} presence).
#' @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 Cox
#'   model terms (e.g. \code{"strata(x1)"} or \code{"x2"}) used to adjust the
#'   candidate-search Cox scorer on the survival path.  Referenced columns are
#'   sourced from \code{df_analysis}.  Ignored on the GLM path.  Default
#'   \code{NULL} (treatment-only).
#' @param disable_effect_floor Logical. When \code{TRUE}, the Status-6 effect
#'   threshold (\code{hr.threshold}) is not applied, so the full estimable
#'   candidate family is retained regardless of effect size.  Set by
#'   \code{\link{forestsearch}} when \code{sg_focus = "maxeff"} so the effect
#'   maximiser ranges over an unconditional family.  Default \code{FALSE}.
#'
#' @return List with found subgroups, maximum HR, search time, configuration info,
#'   and filtering statistics.
#'
#' @importFrom data.table data.table setorder
#' @importFrom survival coxph Surv survfit
#' @importFrom utils combn
#' @examples
#' \dontrun{
#' library(survival)
#' df <- survival::gbsg
#' df$grade3 <- as.integer(df$grade == "3")
#' Z <- df[, c("age", "meno", "size", "grade3", "nodes", "pgr", "er")]
#' res <- subgroup.search(Y = df$rfstime, Event = df$status,
#'                        Treat = df$hormon, Z = Z,
#'                        hr.threshold = 1.25)
#' }
#' @export

subgroup.search <- function(Y, Event, Treat, ID = NULL, Z,
                            n.min = 30, d0.min = 15, d1.min = 15,
                            hr.threshold = 1.0, max.minutes = 30,
                            minp = 0.05, rmin = 5,
                            details = FALSE, maxk = 2,
                            parallel_workers = parallel::detectCores(),
                            estimator_fn = NULL,
                            df_analysis = NULL,
                            effect_threshold = NULL,
                            effect_measure = NULL,
                            outcome_type = NULL,
                            adjust_covariates = NULL,
                            disable_effect_floor = FALSE) {

  if (!missing(max.minutes)) {
    warning("subgroup.search(): '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)
  }

  # =========================================================================
  # SECTION 1: DATA PREPARATION AND VALIDATION
  # =========================================================================

  # Clean and prepare data
  prepared_data <- prepare_search_data(Y, Event, Treat, Z)
  yy <- prepared_data$Y
  dd <- prepared_data$Event
  tt <- prepared_data$Treat
  zz <- prepared_data$Z

  n <- length(yy)
  L <- ncol(zz)

  # For GLM path: align df_analysis with the NA-cleaned vectors.  Also built
  # for the survival path when adjust_covariates is supplied, so the adjusted
  # Cox scorer can source the raw covariate columns.
  df_clean <- NULL
  if ((!is.null(estimator_fn) || !is.null(adjust_covariates)) &&
      !is.null(df_analysis)) {
    complete_rows <- stats::complete.cases(cbind(Y, Event, Treat, Z))
    df_clean <- df_analysis[complete_rows, , drop = FALSE]
    if (nrow(df_clean) != n) {
      warning("df_analysis row count mismatch after NA removal: ",
              nrow(df_clean), " vs ", n, ". Using vector-based path.")
      df_clean <- NULL
    }
  }

  # Resolve screening threshold for GLM outcomes
  screen_threshold <- if (!is.null(effect_threshold)) {
    effect_threshold
  } else {
    hr.threshold
  }

  # =========================================================================
  # SECTION 2: GENERATE COMBINATION INDICES
  # =========================================================================

  combo_info <- generate_combination_indices(L, maxk)

  if (details) {
    cat("Number of possible configurations (<= maxk): maxk =", maxk,
        ", # combinations =", combo_info$max_count, "\n")
  }

  # =========================================================================
  # SECTION 3: PARALLELIZED SEARCH THROUGH COMBINATIONS
  # =========================================================================

  t.start <- proc.time()[3]

  # Set up parallel plan
  old_plan <- future::plan()
  on.exit(future::plan(old_plan), add = TRUE)
  future::plan(future::multisession, workers = parallel_workers)

  search_result <- search_combinations_parallel(
    yy = yy, dd = dd, tt = tt, zz = zz,
    combo_info = combo_info,
    n.min = n.min, d0.min = d0.min, d1.min = d1.min,
    hr.threshold = screen_threshold, minp = minp, rmin = rmin,
    max.minutes = max.minutes, t.start = t.start,
    maxk = maxk, L = L,
    estimator_fn = estimator_fn,
    df_clean = df_clean,
    outcome_type = outcome_type,
    adjust_covariates = adjust_covariates,
    disable_effect_floor = disable_effect_floor
  )

  # Reset to sequential plan
  future::plan(future::sequential)

  results_list <- search_result$results
  filter_counts <- search_result$filter_counts

  # =========================================================================
  # SECTION 4: COMPILE AND FORMAT RESULTS
  # =========================================================================

  t.end <- proc.time()[3]
  t.min <- (t.end - t.start) / 60
  t.sofar <- t.min

  if (details) {
    is_glm <- !is.null(estimator_fn)
    is_ratio <- !is.null(effect_measure) &&
      effect_measure %in% c("OR", "RR", "IRR", "HR")
    is_binary <- !is.null(outcome_type) && outcome_type == "binary"

    # d0/d1 label: "events" for survival and binary; "subjects" for continuous
    d_label <- if (is_binary) "events" else if (is_glm) "subjects" else "events"
    cat(sprintf("Per-arm %s criteria: control >= %d, treatment >= %d\n",
        d_label, d0.min, d1.min))
    cat("Sample size criteria: n >=", n.min, "\n")
    cat("Subgroup search completed in", round(t.min, 2), "minutes\n")

    # Threshold display: natural scale for ratio measures, raw for identity
    if (is_ratio && hr.threshold > 0) {
      thresh_display <- sprintf("%s >= %.3f",
          if (!is.null(effect_measure)) effect_measure else "HR",
          exp(hr.threshold))
    } else {
      thresh_display <- sprintf("effect >= %.4f", hr.threshold)
    }

    # Model label
    model_label <- if (is_glm) "GLM" else "Cox"

    # Print filter counts
    cat("\n--- Filtering Summary ---\n")
    cat("  Combinations evaluated:", filter_counts$n_evaluated, "\n")
    cat("  Passed variance check:", filter_counts$n_passed_variance, "\n")
    cat("  Passed prevalence (>=", minp, "):", filter_counts$n_passed_prevalence, "\n")
    cat("  Passed redundancy check:", filter_counts$n_passed_redundancy, "\n")
    cat(sprintf("  Passed %s counts (d0>= %d, d1>= %d): %d\n",
        d_label, d0.min, d1.min, filter_counts$n_passed_events))
    cat("  Passed sample size (n>=", n.min, "):", filter_counts$n_passed_sample_size, "\n")
    if (isTRUE(filter_counts$n_nonestimable > 0L)) {
      tab <- sort(table(filter_counts$nonestimable_reasons), decreasing = TRUE)
      cat(sprintf("  Non-estimable (estimand does not exist): %d\n",
                  filter_counts$n_nonestimable))
      for (i in seq_along(tab)) {
        cat(sprintf("    %s: %d\n",
                    sub("^non-estimable: ", "", names(tab)[i]), tab[[i]]))
      }
    }
    cat(sprintf("  %s model fit successfully: %d\n",
        model_label, filter_counts$n_passed_cox))
    cat(sprintf("  Passed effect threshold (%s): %d\n",
        thresh_display, filter_counts$n_passed_hr))
    cat("-------------------------\n\n")
  }

  # Format results
  output <- format_search_results(
    results_list = results_list,
    Z = zz,
    details = details,
    t.sofar = t.sofar,
    L = L,
    max_count = combo_info$max_count,
    filter_counts = filter_counts
  )

  return(output)
}

# =========================================================================
# PARALLELIZED SEARCH FUNCTION
# =========================================================================

search_combinations_parallel <- function(yy, dd, tt, zz, combo_info,
                                         n.min, d0.min, d1.min, hr.threshold,
                                         minp, rmin, max.minutes, t.start,
                                         maxk, L,
                                         estimator_fn = NULL,
                                         df_clean = NULL,
                                         outcome_type = NULL,
                                         adjust_covariates = NULL,
                                         disable_effect_floor = FALSE) {

  tot_counts <- combo_info$max_count

  # Parallel evaluation
  results_status_list <- future.apply::future_lapply(seq_len(tot_counts), function(kk) {
    # Get factor selection for this combination
    covs.in <- get_covs_in(
      kk, maxk, L,
      combo_info$counts_1, combo_info$indices_1,
      combo_info$counts_2, combo_info$indices_2,
      combo_info$counts_3, combo_info$indices_3
    )
    if (sum(covs.in) > maxk) return(list(status = NA, result = NULL))
    evaluate_combination_with_status(
      covs.in = covs.in,
      yy = yy, dd = dd, tt = tt, zz = zz,
      n.min = n.min, d0.min = d0.min, d1.min = d1.min,
      hr.threshold = hr.threshold, minp = minp, rmin = rmin,
      kk = kk,
      estimator_fn = estimator_fn,
      df_clean = df_clean,
      outcome_type = outcome_type,
      adjust_covariates = adjust_covariates,
      disable_effect_floor = disable_effect_floor
    )
  })

  # Initialize filter counters
  filter_counts <- list(
    n_evaluated = 0L,
    n_passed_variance = 0L,
    n_passed_prevalence = 0L,
    n_passed_redundancy = 0L,
    n_passed_events = 0L,
    n_passed_sample_size = 0L,
    n_passed_cox = 0L,
    n_passed_hr = 0L,
    n_nonestimable = 0L,
    nonestimable_reasons = character(0)
  )

  results_list <- list()
  n_results <- 0

  for (res in results_status_list) {
    if (is.null(res$status) || is.na(res$status)) next
    filter_counts$n_evaluated <- filter_counts$n_evaluated + 1L
    if (res$status >= 1) filter_counts$n_passed_variance <- filter_counts$n_passed_variance + 1L
    if (res$status >= 2) filter_counts$n_passed_prevalence <- filter_counts$n_passed_prevalence + 1L
    if (res$status >= 3) filter_counts$n_passed_redundancy <- filter_counts$n_passed_redundancy + 1L
    if (res$status >= 4) filter_counts$n_passed_events <- filter_counts$n_passed_events + 1L
    if (res$status >= 5) filter_counts$n_passed_sample_size <- filter_counts$n_passed_sample_size + 1L
    if (res$status >= 6) filter_counts$n_passed_cox <- filter_counts$n_passed_cox + 1L
    if (res$status >= 7) filter_counts$n_passed_hr <- filter_counts$n_passed_hr + 1L
    if (!is.null(res$reason)) {
      filter_counts$n_nonestimable <- filter_counts$n_nonestimable + 1L
      filter_counts$nonestimable_reasons <-
        c(filter_counts$nonestimable_reasons, res$reason)
    }
    if (!is.null(res$result)) {
      n_results <- n_results + 1
      results_list[[n_results]] <- res$result
    }
  }

  # Return results and filter counts
  list(
    results = Filter(Negate(is.null), results_list[seq_len(max(1, n_results))]),
    filter_counts = filter_counts
  )
}

# =========================================================================
# HELPER FUNCTIONS
# =========================================================================

#' Prepare Data for Subgroup Search
#'
#' Cleans data by removing missing values and extracting components
#'
#' @keywords internal
prepare_search_data <- function(Y, Event, Treat, Z) {
  temp <- cbind(Y, Event, Treat, Z)
  temp <- na.exclude(temp)

  list(
    Y = temp[, 1],
    Event = temp[, 2],
    Treat = temp[, 3],
    Z = temp[, -c(1, 2, 3)]
  )
}

#' Generate Combination Indices
#'
#' Creates indices for all factor combinations up to maxk
#'
#' @keywords internal
generate_combination_indices <- function(L, maxk) {

  # Calculate maximum possible combinations
  max_count <- calculate_max_combinations(L, maxk)

  # Generate indices for each level
  indices <- list()
  counts <- numeric(maxk)

  for (k in 1:maxk) {
    indices[[k]] <- t(combn(L, k))
    counts[k] <- nrow(indices[[k]])
  }

  # Validate total count
  if (sum(counts) != max_count) {
    stop("Error: combination count mismatch for maxk = ", maxk)
  }

  list(
    max_count = max_count,
    indices_1 = indices[[1]],
    counts_1 = counts[1],
    indices_2 = if (maxk >= 2) indices[[2]] else NULL,
    counts_2 = if (maxk >= 2) counts[2] else 0,
    indices_3 = if (maxk >= 3) indices[[3]] else NULL,
    counts_3 = if (maxk >= 3) counts[3] else 0
  )
}

#' Calculate Maximum Combinations
#'
#' @keywords internal
calculate_max_combinations <- function(L, maxk) {
  if (maxk == 1) return(L)
  if (maxk == 2) return(L + (L * (L - 1) / 2))
  if (maxk == 3) return(L + (L * (L - 1) / 2) + (L * (L - 2) * (L - 1) / 6))
  stop("maxk must be 1, 2, or 3")
}

#' Get all combinations of subgroup factors up to maxk
#'
#' Generates all possible combinations of subgroup factors up to a specified maximum size.
#'
#' @param L Integer. Number of subgroup factors.
#' @param maxk Integer. Maximum number of factors in a combination.
#' @return List with \code{max_count} (total combinations) and \code{indices_list} (indices for each k).
#' @importFrom utils combn
#' @examples
#' # L=6 single-factor subgroups, combinations up to 2 factors
#' info <- get_combinations_info(L = 6, maxk = 2)
#' info$max_count   # total number of combinations
#' length(info$indices_list)
#' @export

get_combinations_info <- function(L, maxk) {
  # Calculate max_count
  max_count <- 0
  indices_list <- list()
  for (k in 1:maxk) {
    indices_k <- base::t(combn(L, k))
    indices_list[[paste0("k", k)]] <- indices_k
    max_count <- max_count + nrow(indices_k)
  }
  # Consistency check
  tot_counts <- sum(sapply(indices_list, nrow))
  if (tot_counts != max_count) stop("Error with maximum combinations for kmax = ", maxk)
  list(
    max_count = max_count,
    indices_list = indices_list
  )
}

#' Get subgroup membership vector
#'
#' Returns a vector indicating subgroup membership (1 if all selected factors are present, 0 otherwise).
#'
#' @param zz Matrix or data frame of subgroup factor indicators.
#' @param covs.in Numeric vector indicating which factors are selected (1 = included).
#' @return Numeric vector of subgroup membership (1/0).
#' @examples
#' zz <- matrix(c(1, 0, 1, 1, 0, 1), nrow = 3,
#'              dimnames = list(NULL, c("er_le0", "grade3")))
#' get_subgroup_membership(zz, covs.in = c(1, 1))  # both factors required
#' get_subgroup_membership(zz, covs.in = c(1, 0))  # first factor only
#' @export

get_subgroup_membership <- function(zz, covs.in) {
  selected_cols <- which(covs.in == 1)
  if (length(selected_cols) == 0) return(rep(1, nrow(zz)))
  x <- zz[, selected_cols, drop = FALSE]
  rowSums(x) == length(selected_cols)
}

#' Get indicator vector for selected subgroup factors
#'
#' Returns a vector indicating which factors are included in a subgroup combination.
#'
#' @param kk Integer. Index of the combination.
#' @param maxk Integer. Maximum number of factors in a combination.
#' @param L Integer. Number of subgroup factors.
#' @param counts_1factor Integer. Number of single-factor combinations.
#' @param index_1factor Matrix of indices for single-factor combinations.
#' @param counts_2factor Integer. Number of two-factor combinations.
#' @param index_2factor Matrix of indices for two-factor combinations.
#' @param counts_3factor Integer. Number of three-factor combinations.
#' @param index_3factor Matrix of indices for three-factor combinations.
#' @return Numeric vector indicating selected factors (1 = included, 0 = not included).
#' @examples
#' # Build index matrices directly (L=4, maxk=2)
#' L <- 4
#' idx1 <- matrix(seq_len(L), ncol = 1)          # single-factor indices
#' idx2 <- t(utils::combn(L, 2))                 # two-factor indices
#' # Combination 3 falls in the single-factor block (kk=3 -> factor 3)
#' get_covs_in(kk = 3, maxk = 2, L = L,
#'             counts_1factor = nrow(idx1),
#'             index_1factor  = idx1,
#'             counts_2factor = nrow(idx2),
#'             index_2factor  = idx2)
#' @export

get_covs_in <- function(kk, maxk, L,
                        counts_1factor, index_1factor,
                        counts_2factor = NULL, index_2factor = NULL,
                        counts_3factor = NULL, index_3factor = NULL) {
  covs.in <- rep(0, L)
  if (kk <= counts_1factor) {
    which1 <- index_1factor[kk]
    covs.in[which1] <- 1.0
  } else if (maxk == 2 && kk > counts_1factor) {
    kk_new <- kk - counts_1factor
    which1 <- index_2factor[kk_new, 1]
    which2 <- index_2factor[kk_new, 2]
    covs.in[c(which1, which2)] <- 1.0
  } else if (maxk == 3) {
    if (kk > counts_1factor && kk <= (counts_1factor + counts_2factor)) {
      kk_new <- kk - counts_1factor
      which1 <- index_2factor[kk_new, 1]
      which2 <- index_2factor[kk_new, 2]
      covs.in[c(which1, which2)] <- 1.0
    }
    if (kk > (counts_1factor + counts_2factor)) {
      kk_new <- kk - (counts_1factor + counts_2factor)
      which1 <- index_3factor[kk_new, 1]
      which2 <- index_3factor[kk_new, 2]
      which3 <- index_3factor[kk_new, 3]
      covs.in[c(which1, which2, which3)] <- 1.0
    }
  }
  covs.in
}

#' Extract redundancy flag for subgroup combinations
#'
#' Checks if adding each factor to a subgroup reduces the sample size by at least \code{rmin}.
#'
#' @param x Matrix of subgroup factor indicators.
#' @param rmin Integer. Minimum required reduction in sample size.
#' @return List with \code{id.x} (membership vector) and \code{flag.redundant} (logical).
#' @keywords internal

extract_idx_flagredundancy <- function(x, rmin) {
  n <- nrow(x)
  id.x <- rep(1, n)
  flag.redundant <- FALSE
  nx.last <- n
  for (m in seq_len(ncol(x))) {
    if (!flag.redundant) {
      id.x <- id.x * x[, m]
      nx.this <- sum(id.x)
      if (nx.last - nx.this <= rmin) flag.redundant <- TRUE
      nx.last <- nx.this
    }
  }
  list(id.x = id.x, flag.redundant = flag.redundant)
}

#' Evaluate a Single Factor Combination with Status Tracking
#'
#' Tests whether a specific combination meets all criteria and returns
#' a status code indicating how far the evaluation progressed.
#'
#' @param covs.in Numeric vector. Factor selection indicators.
#' @param yy Numeric vector. Outcome values.
#' @param dd Numeric vector. Event indicators.
#' @param tt Numeric vector. Treatment indicators.
#' @param zz Matrix. Factor indicators.
#' @param n.min Integer. Minimum sample size.
#' @param d0.min Integer. Minimum control events (binary/survival) or ignored
#'   (continuous).
#' @param d1.min Integer. Minimum treatment events (binary/survival) or ignored
#'   (continuous).
#' @param hr.threshold Numeric. Effect threshold, on the scale this function
#'   compares on: the natural hazard-ratio scale on the survival path, and
#'   the resolved comparison scale (link for OR/RR/IRR, identity for
#'   RD/IRD/MD) on the GLM paths.  See \code{\link{subgroup.search}}.
#' @param minp Numeric. Minimum prevalence.
#' @param rmin Integer. Minimum size reduction.
#' @param kk Integer. Combination index.
#' @param adjust_covariates Character vector or \code{NULL}. Cox adjustment
#'   terms passed to \code{fit_cox_for_subgroup} on the survival path.
#'
#' @return List with:
#'   \describe{
#'     \item{status}{Integer status code:
#'       0 = failed variance check,
#'       1 = passed variance, failed prevalence,
#'       2 = passed prevalence, failed redundancy,
#'       3 = passed redundancy, failed per-arm filter,
#'       4 = passed per-arm filter, failed sample size,
#'       5 = passed sample size, failed model fit,
#'       6 = passed model fit, failed effect threshold,
#'       7 = passed all criteria (success)}
#'     \item{result}{Result row if successful, NULL otherwise}
#'   }
#'
#' @keywords internal
evaluate_combination_with_status <- function(covs.in, yy, dd, tt, zz,
                                             n.min, d0.min, d1.min, hr.threshold,
                                             minp, rmin, kk,
                                             estimator_fn = NULL,
                                             df_clean = NULL,
                                             outcome_type = NULL,
                                             adjust_covariates = NULL,
                                             disable_effect_floor = FALSE) {

  # Extract selected factors
  selected_cols <- which(covs.in == 1)
  x <- zz[, selected_cols, drop = FALSE]

  # Status 0: Check variance
  if (!has_positive_variance(x)) {
    return(list(status = 0L, result = NULL))
  }

  # Status 1: Check prevalence
  if (!meets_prevalence_threshold(x, minp)) {
    return(list(status = 1L, result = NULL))
  }

  # Status 2: Check redundancy
  redundancy_check <- extract_idx_flagredundancy(x, rmin)
  if (redundancy_check$flag.redundant) {
    return(list(status = 2L, result = NULL))
  }

  id.x <- redundancy_check$id.x

  # ---------- GLM path ----------
  if (!is.null(estimator_fn) && !is.null(df_clean)) {

    is_binary <- !is.null(outcome_type) && outcome_type == "binary"
    is_continuous <- !is.null(outcome_type) &&
      outcome_type %in% c("continuous", "count")

    # Status 3: Per-arm filter
    #   Binary:     minimum EVENTS (Y=1) per arm — analogous to survival
    #   Continuous:  d0.min/d1.min not meaningful — skip, rely on n.min
    if (is_binary) {
      # Events per arm: sum of binary outcome within each arm of the subgroup
      d0_sg <- sum(yy[id.x == 1 & tt == 0])
      d1_sg <- sum(yy[id.x == 1 & tt == 1])
      if (d0_sg < d0.min || d1_sg < d1.min) {
        return(list(status = 3L, result = NULL))
      }
    } else if (!is_continuous) {
      # Unknown GLM type: fall back to per-arm sample size check
      n0_sg <- sum(tt[id.x == 1] == 0)
      n1_sg <- sum(tt[id.x == 1] == 1)
      if (n0_sg < d0.min || n1_sg < d1.min) {
        return(list(status = 3L, result = NULL))
      }
    }
    # Continuous: skip Status 3 entirely — d0.min/d1.min do not apply

    # Status 4: Check total subgroup size
    nx <- sum(id.x)
    if (nx <= n.min) {
      return(list(status = 4L, result = NULL))
    }

    # Status 5: Fit GLM via estimator closure.  When the construction-time
    # routing predicate tagged the closure (unadjusted continuous case), take
    # the vector path: no per-candidate data-frame slice -- the profiled
    # 58.7% of the fit bucket (REPORT_bootstrap_reprofile_2026-09-01.md,
    # section 4a).  Both paths return the identical contract.
    if (isTRUE(attr(estimator_fn, "fs_fast_unadjusted"))) {
      glm_result <- fit_glm_for_subgroup_fast(yy, tt, id.x, estimator_fn)
    } else {
      glm_result <- fit_glm_for_subgroup(df_clean, id.x, estimator_fn)
    }
    if (!is.null(glm_result) && isTRUE(glm_result$nonestimable)) {
      return(list(status = 5L, result = NULL, reason = glm_result$reason))
    }
    if (is.null(glm_result)) {
      return(list(status = 5L, result = NULL))
    }

    # Status 6: Check effect threshold.  Skipped when the effect floor is
    # disabled (sg_focus = "maxeff" retains the full estimable family so the
    # argmax is unconditional -- see forestsearch() search_overrides).
    if (!disable_effect_floor && glm_result$hr <= hr.threshold) {
      return(list(status = 6L, result = NULL))
    }

    # Status 7: Passed
    if (is_binary) {
      event_counts <- list(d0 = d0_sg, d1 = d1_sg, total = d0_sg + d1_sg)
    } else {
      n0_sg <- sum(tt[id.x == 1] == 0)
      n1_sg <- sum(tt[id.x == 1] == 1)
      event_counts <- list(d0 = n0_sg, d1 = n1_sg, total = n0_sg + n1_sg)
    }
    result_row <- create_result_row(kk, covs.in, nx, event_counts, glm_result)
    return(list(status = 7L, result = result_row))
  }

  # ---------- Survival path (existing, unchanged) ----------

  # Status 3: Check event counts
  event_counts <- calculate_event_counts(dd, tt, id.x)
  if (!meets_event_criteria(event_counts, d0.min, d1.min)) {
    return(list(status = 3L, result = NULL))
  }

  # Status 4: Check sample size
  nx <- sum(id.x)
  if (nx <= n.min) {
    return(list(status = 4L, result = NULL))
  }

  # Status 5: Fit Cox model.  The log-HR needs an event in each arm; with
  # d1.min = 0 (which several committed campaign templates pass) a zero-event
  # arm reaches coxph(), which returns a finite divergent coefficient rather
  # than an error.  No admission floor is added here -- the candidate simply
  # takes the existing fit-failure status, with its reason recorded.
  why <- .fs_existence_reason("HR",
    c(e0  = sum(dd[id.x == 1] == 1 & tt[id.x == 1] == 0, na.rm = TRUE),
      ne0 = NA_integer_,
      e1  = sum(dd[id.x == 1] == 1 & tt[id.x == 1] == 1, na.rm = TRUE),
      ne1 = NA_integer_))
  if (!is.null(why)) {
    return(list(status = 5L, result = NULL, reason = why))
  }

  cox_result <- fit_cox_for_subgroup(yy, dd, tt, id.x,
                                     df_clean = df_clean,
                                     adjust_covariates = adjust_covariates)
  if (is.null(cox_result)) {
    return(list(status = 5L, result = NULL))
  }

  # Status 6: Check HR threshold.  Skipped when the effect floor is disabled
  # (sg_focus = "maxeff" retains the full estimable family so the argmax is
  # unconditional -- see forestsearch() search_overrides).
  if (!disable_effect_floor && cox_result$hr <= hr.threshold) {
    return(list(status = 6L, result = NULL))
  }

  # Status 7: passed all criteria.  Compute median survival for this
  # effect-screen survivor before building the row (0.3.4): the survfit call
  # and extraction relocated from fit_cox_for_subgroup() operation for
  # operation, on a rebuilt frame with the same column names so the
  # "Treat=0"/"Treat=1" strata labels (and hence the extraction) are
  # identical.  Non-passers never produce a row, so no output surface
  # consumed their medians -- computing them only here elides ~11.7x
  # redundant survfit calls on the gbsg application without changing any
  # output value (REPORT_bootstrap_reprofile_2026-09-01.md, section 4b).
  idx <- id.x == 1
  med_df <- data.frame(Y = yy[idx], E = dd[idx], Treat = tt[idx])
  meds <- try(
    summary(survival::survfit(survival::Surv(Y, E) ~ Treat, data = med_df))$table[, "median"],
    silent = TRUE
  )
  # Pre-move contract, replicated: a survfit failure inside
  # fit_cox_for_subgroup() made it return NULL, i.e. status 5 (failed
  # model fit).
  if (inherits(meds, "try-error")) {
    return(list(status = 5L, result = NULL))
  }
  cox_result$med0 <- meds[1]
  cox_result$med1 <- meds[2]

  result_row <- create_result_row(kk, covs.in, nx, event_counts, cox_result)
  return(list(status = 7L, result = result_row))
}

#' Check if Matrix Has Positive Variance
#'
#' @keywords internal
has_positive_variance <- function(x) {
  if (is.null(x) || ncol(x) == 0) return(TRUE)
  xpx <- t(x) %*% x
  return(all(xpx > 0))
}

#' Check Prevalence Threshold
#'
#' @keywords internal
meets_prevalence_threshold <- function(x, minp) {
  if (is.null(x) || ncol(x) == 0) return(TRUE)
  return(all(colMeans(x) >= minp))
}

#' Calculate Event Counts by Treatment Arm
#'
#' @keywords internal
calculate_event_counts <- function(dd, tt, id.x) {
  list(
    d0 = sum(dd[id.x == 1 & tt == 0]),
    d1 = sum(dd[id.x == 1 & tt == 1]),
    total = sum(dd[id.x == 1])
  )
}

#' Check Event Count Criteria
#'
#' @keywords internal
meets_event_criteria <- function(event_counts, d0.min, d1.min) {
  return(event_counts$d0 >= d0.min && event_counts$d1 >= d1.min)
}

# ---------------------------------------------------------------------------
# Lean unadjusted Cox core (0.4.0.9000)
# ---------------------------------------------------------------------------

# Per-session state for the lean core: the probe verdict and the calling
# conventions read from coxph().  One environment per R process, so every
# worker probes once.
.fs_cox_lean_state <- new.env(parent = emptyenv())

#' Calling conventions of `coxph()` that the lean core reproduces
#'
#' `coxph()` passes `method = match.arg(ties)` and its own `nocenter` default
#' to `coxph.fit()`.  Both are read from `coxph()`'s formals once per session,
#' so the lean core follows survival if either default moves; the literal
#' values of survival 3.5-8 .. 3.8.x (`"efron"`, `c(-1, 0, 1)`) are the
#' fallback when the formals cannot be read.  Whatever is read here is
#' checked against `coxph()` by `.fs_cox_lean_ok()` before the lean core is
#' used.
#'
#' @return List with `ties` (character scalar) and `nocenter` (numeric).
#' @keywords internal
#' @noRd
.fs_cox_lean_conventions <- function() {
  cv <- .fs_cox_lean_state$conventions
  if (!is.null(cv)) return(cv)
  f <- formals(survival::coxph)
  ties <- tryCatch(eval(f$ties)[1L], error = function(e) NULL)
  if (!is.character(ties) || length(ties) != 1L || is.na(ties)) ties <- "efron"
  nocenter <- tryCatch(eval(f$nocenter), error = function(e) NULL)
  if (!is.numeric(nocenter) || length(nocenter) == 0L) nocenter <- c(-1, 0, 1)
  cv <- list(ties = ties, nocenter = nocenter)
  .fs_cox_lean_state$conventions <- cv
  cv
}

#' Two-group Cox fit through `survival::coxph.fit()`, bit-identical to `coxph()`
#'
#' The fitting-engine call `coxph()` makes for `Surv(Y, E) ~ Treat`
#' (survival 3.5-8 .. 3.8.x): the one-column model matrix without intercept,
#' the response through `aeqSurv()` when `control$timefix`, no strata, a zero
#' offset, `init = NULL`, the default control, no weights, `coxph()`'s ties
#' method and `nocenter` (so the 0/1 treatment column is not centred, exactly
#' as in the formula fit), the model-frame row names, residuals on.
#' `coxph()` additionally builds the model frame, the full `coxph` object and
#' the concordance, none of which the search reads; `coefficients` and `var`
#' are returned by `coxph.fit()` unchanged, and the same warnings are raised
#' (monotone likelihood, non-convergence) -- nothing is suppressed.  Verified
#' bit-identical on every candidate of the gbsg application
#' (`dev/reports/REPORT_bootstrap_stage0_2026-10-26.md`, 1410/1410) and in
#' `tests/testthat/test-lean-fits.R`.  Guarded by `.fs_cox_lean_ok()`.
#'
#' @param Y,E,Treat Numeric vectors: time, event indicator and 0/1 treatment,
#'   already restricted to the candidate subgroup.
#' @return The `coxph.fit()` result (a list with `coefficients`, `var`, ...).
#' @keywords internal
#' @noRd
.fs_cox_two_group <- function(Y, E, Treat) {
  n_sg <- length(Y)
  cv   <- .fs_cox_lean_conventions()
  ctl  <- survival::coxph.control()
  ys   <- survival::Surv(Y, E)
  if (isTRUE(ctl$timefix)) ys <- survival::aeqSurv(ys)
  survival::coxph.fit(
    x        = matrix(as.double(Treat), ncol = 1L,
                      dimnames = list(NULL, "Treat")),
    y        = ys,
    strata   = NULL,
    offset   = rep(0, n_sg),
    init     = NULL,
    control  = ctl,
    weights  = NULL,
    method   = cv$ties,
    rownames = as.character(seq_len(n_sg)),
    resid    = TRUE,
    nocenter = cv$nocenter
  )
}

#' Once-per-session probe: does the lean core reproduce `coxph()`?
#'
#' Fits a fixed 30-row fixture both ways -- ten clusters of three near-tied
#' times that `aeqSurv()` collapses to exact ties (the tripwire for the
#' `timefix` convention), both arms present, events in both arms -- and
#' compares `coefficients` and `var` with `identical()`.  An error (for
#' example a changed `coxph.fit()` signature in a future survival) or any
#' difference turns the lean core off for the session: the search-stage fit
#' then goes through the formula interface, which is the same estimator, and
#' one message says so.  The verdict is cached in `.fs_cox_lean_state`.
#'
#' @return `TRUE` if the lean core may be used in this session.
#' @keywords internal
#' @noRd
.fs_cox_lean_ok <- function() {
  ok <- .fs_cox_lean_state$ok
  if (!is.null(ok)) return(ok)
  ok <- isTRUE(tryCatch({
    Y <- rep(seq(5, 50, by = 5), each = 3) + rep(c(0, 1e-9, 2e-9), 10)
    E <- rep(c(1L, 1L, 0L), 10)
    Treat <- rep(c(0, 1), 15)
    lean <- .fs_cox_two_group(Y, E, Treat)
    ref  <- survival::coxph(survival::Surv(Y, E) ~ Treat, robust = FALSE)
    identical(unname(lean$coefficients), unname(ref$coefficients)) &&
      identical(unname(as.vector(lean$var)), unname(as.vector(ref$var)))
  }, error = function(e) FALSE))
  if (!ok) {
    message("forestsearch: survival::coxph.fit() did not reproduce coxph() ",
            "on the probe fixture (survival ",
            as.character(utils::packageVersion("survival")),
            "); the unadjusted search-stage Cox fit uses the formula ",
            "interface in this session.")
  }
  .fs_cox_lean_state$ok <- ok
  ok
}

#' Fit Cox Model for Subgroup
#'
#' @param yy,dd,tt,id.x Numeric vectors: outcome, event, treatment, and the
#'   subgroup membership indicator (1 = in subgroup).
#' @param df_clean Data frame or `NULL`. Cleaned analysis frame row-aligned
#'   with the vectors, used only to source raw `adjust_covariates` columns.
#' @param adjust_covariates Character vector or `NULL`. Additional Cox terms
#'   (e.g. `"strata(x1)"`) appended after `Treat`.  `NULL` (default) fits the
#'   treatment-only model.
#' @keywords internal
#' @importFrom survival coxph Surv survfit
fit_cox_for_subgroup <- function(yy, dd, tt, id.x, df_clean = NULL,
                                 adjust_covariates = NULL) {

  adj <- .fs_adjust_terms(adjust_covariates)
  idx <- id.x == 1

  # Fit Cox model (treatment-only or adjusted)
  if (length(adj) == 0L) {
    # Unadjusted fast branch (0.3.3): the same Cox fit (through coxph.fit()
    # since 0.4.0.9000, see below), but the consumed $conf.int row is
    # computed directly instead of through summary.coxph(),
    # whose full summary table cost 40.3% of the fit bucket for one CI row
    # (REPORT_bootstrap_reprofile_2026-09-01.md, section 4a).  The
    # arithmetic replicates survival 3.8.9 summary.coxph() operation for
    # operation, non-robust branch, conf.int = 0.95, scale = 1 (the
    # `* scale` multiplications are omitted: x * 1 is exact in IEEE-754):
    #   beta <- cox$coefficients * scale
    #   se <- sqrt(diag(cox$var)) * scale
    #   z <- qnorm((1 + conf.int)/2, 0, 1)
    #   tmp <- cbind(exp(beta), exp(-beta), exp(beta - z*se), exp(beta + z*se))
    #   dimnames(tmp) <- list(names(beta), c("exp(coef)", "exp(-coef)",
    #     paste("lower .", round(100*conf.int, 2), sep = ""), ...))  # ".95"
    # The try() wrapper and its NULL-on-error contract are unchanged; a
    # degenerate fit (monotone likelihood) warns from coxph() exactly as
    # before and produces the identical row.  The fit runs on the three
    # subset locals below, resolved from the function environment (0.3.5):
    # the medians move (0.3.4) left the two coxph() calls as the frame's
    # only consumers, so the per-candidate frame is now built only for
    # adjusted fits.  Same values, same row order, same variable names --
    # the coefficient is named "Treat" exactly as with the frame-based fit.
    Y <- yy[idx]
    E <- dd[idx]
    Treat <- tt[idx]
    hr.cox <- try({
      # Unadjusted fit (0.4.0.9000): the lean core .fs_cox_two_group() --
      # survival::coxph.fit() with exactly the arguments coxph() passes for
      # Surv(Y, E) ~ Treat -- once the per-session probe .fs_cox_lean_ok()
      # has confirmed it reproduces coxph(); otherwise the 0.4.0 formula
      # fit.  The same estimator either way; coefficients and var are the
      # only fields consumed below.  Identity: tests/testthat/test-lean-fits.R.
      fit.cox <- if (.fs_cox_lean_ok()) {
        .fs_cox_two_group(Y, E, Treat)
      } else {
        survival::coxph(survival::Surv(Y, E) ~ Treat, robust = FALSE)
      }
      beta <- fit.cox$coefficients
      names(beta) <- "Treat"
      se_beta <- sqrt(diag(fit.cox$var))
      z_ci <- stats::qnorm((1 + 0.95) / 2, 0, 1)
      ci <- cbind(exp(beta), exp(-beta),
                  exp(beta - z_ci * se_beta), exp(beta + z_ci * se_beta))
      dimnames(ci) <- list(names(beta),
                           c("exp(coef)", "exp(-coef)",
                             "lower .95", "upper .95"))
      ci
    }, silent = TRUE)
  } else {
    # Adjusted arm: the only arm that still needs a frame (covariate
    # columns).  The df.x assembly relocated here verbatim (0.3.5).

    # Create subgroup data
    data.x <- data.table::data.table(Y = yy, E = dd, Treat = tt, id.x = id.x)

    # Attach raw adjustment columns (row-aligned with the vectors) when present
    rhs <- "Treat"
    if (!is.null(df_clean)) {
      adj_vars <- intersect(.fs_adjust_vars(adjust_covariates), names(df_clean))
      if (length(adj_vars) > 0L) {
        adj_cols <- as.data.frame(df_clean)[, adj_vars, drop = FALSE]
        data.x <- cbind(data.x, adj_cols)
      }
      rhs <- paste(c("Treat", adj), collapse = " + ")
    }

    df.x <- data.x[id.x == 1]

    cox_fmla <- stats::as.formula(paste0("survival::Surv(Y, E) ~ ", rhs))
    hr.cox <- try(
      summary(survival::coxph(cox_fmla, data = df.x, robust = FALSE))$conf.int,
      silent = TRUE
    )
  }

  if (inherits(hr.cox, "try-error")) return(NULL)

  # Extract the treatment row.  conf.int is a matrix with one row per
  # coefficient; the adjusted fit has several, so index by name.
  if (is.null(dim(hr.cox))) {
    hr.cox <- matrix(hr.cox, nrow = 1L,
                     dimnames = list("Treat", names(hr.cox)))
  }
  trow <- if ("Treat" %in% rownames(hr.cox)) hr.cox["Treat", ] else hr.cox[1, ]

  # Median survival times are no longer computed here (0.3.4): the survfit
  # call moved to the post-screen point of the per-candidate iteration in
  # evaluate_combination_with_status(), so only effect-screen survivors pay
  # for it.  The return contract is unchanged; med0/med1 are patched there
  # for passing candidates before the row is built.
  list(
    hr = trow[1],
    lower = trow[3],
    upper = trow[4],
    med0 = NA_real_,
    med1 = NA_real_
  )
}


#' Fit GLM for Subgroup via Estimator Closure
#'
#' Subsets the analysis data frame to the candidate subgroup and calls the
#' pre-built estimator closure.  Returns a list compatible with
#' \code{\link{create_result_row}} so the downstream pipeline is unchanged.
#'
#' For binary outcomes with `effect_measure = "RD"`, the `hr` slot contains
#' the risk difference (not a hazard ratio) -- the name is retained for
#' pipeline compatibility.  Similarly, `lower`/`upper` are Wald-type CI
#' bounds and `med0`/`med1` are `NA`.
#'
#' @param df_clean Data frame.  The analysis data, row-aligned with the
#'   cleaned vectors.
#' @param id.x Integer vector.  1 = subject in this subgroup, 0 = not.
#' @param estimator_fn Closure from \code{\link{make_effect_estimator}}.
#'
#' @return A list with components `hr`, `lower`, `upper`, `med0`, `med1`,
#'   or `NULL` on failure.
#'
#' @keywords internal
fit_glm_for_subgroup <- function(df_clean, id.x, estimator_fn) {
  df_sg <- df_clean[id.x == 1, , drop = FALSE]

  if (nrow(df_sg) < 6L) return(NULL)

  res <- tryCatch(
    estimator_fn(df_sg),
    error = function(e) NULL
  )

  if (is.null(res)) return(NULL)

  # A non-estimable candidate carries a reason from the estimator boundary.
  # It still fails the fit (status 5, as any NA estimate always has), but the
  # reason travels so the run can say how many candidates were non-estimable
  # and why, rather than dropping them silently.
  if (is.na(res$estimate)) {
    if (!is.null(res$reason)) {
      return(list(nonestimable = TRUE, reason = res$reason))
    }
    return(NULL)
  }

  # Wald CI: estimate +/- 1.96 * SE
  z_crit <- 1.96
  lower  <- res$estimate - z_crit * res$se
  upper  <- res$estimate + z_crit * res$se

  list(
    hr    = res$estimate,    # effect estimate (RD, log-OR, etc.)
    lower = lower,
    upper = upper,
    med0  = NA_real_,        # no median survival for GLM outcomes
    med1  = NA_real_
  )
}

#' Fast Vector-Path GLM Fit for Subgroup
#'
#' Vector twin of \code{fit_glm_for_subgroup()} for the tagged unadjusted
#' continuous closure: subsets the outcome and treatment VECTORS (no
#' data-frame slice) and runs the bit-identical two-group OLS core
#' \code{.fs_lm_two_group()}.  Contract identical to
#' \code{fit_glm_for_subgroup()}: \code{NULL} when the slice has fewer than
#' 6 rows, when the fit errors, or when the estimate is \code{NA} (the
#' rank-deficient single-arm slice); otherwise the
#' \code{hr/lower/upper/med0/med1} list with the same Wald CI arithmetic.
#' The sign convention and treatment column name are read from the tagged
#' closure's environment (\code{adverse_outcome}, \code{treat.name} are
#' \code{force()}d there), so no signature beyond the vectors changes.
#'
#' The tagged unadjusted binary OR closure
#' (\code{.make_glm_or_estimator_fast()}) is routed here too; its environment
#' carries \code{fs_fast_core = "logit_or"}, on which the OR vector path
#' \code{.fit_or_for_subgroup_vector()} is taken instead of the OLS core.
#'
#' @param yy,tt Numeric vectors: cleaned outcome and treatment, full length.
#' @param id.x Integer vector. 1 = subject in this subgroup, 0 = not.
#' @param estimator_fn The tagged fast closure (attribute
#'   \code{fs_fast_unadjusted}).
#' @keywords internal
#' @noRd
fit_glm_for_subgroup_fast <- function(yy, tt, id.x, estimator_fn) {
  idx <- id.x == 1
  if (sum(idx) < 6L) return(NULL)

  fn_env <- environment(estimator_fn)
  y <- yy[idx]
  t <- tt[idx]
  # Binary OR core (0.4.0.9000): the tagged fast OR closure marks its
  # environment; the OLS closure carries no marker and takes the path below.
  if (identical(fn_env$fs_fast_core, "logit_or")) {
    return(.fit_or_for_subgroup_vector(y, t, fn_env))
  }

  if (!isTRUE(fn_env$adverse_outcome)) y <- -y

  res <- tryCatch(
    .fs_lm_two_group(y, t, fn_env$treat.name),
    error = function(e) NULL
  )

  if (is.null(res) || is.na(res$estimate)) return(NULL)

  # Wald CI: estimate +/- 1.96 * SE (as in fit_glm_for_subgroup)
  z_crit <- 1.96
  lower  <- res$estimate - z_crit * res$se
  upper  <- res$estimate + z_crit * res$se

  list(
    hr    = res$estimate,
    lower = lower,
    upper = upper,
    med0  = NA_real_,
    med1  = NA_real_
  )
}

#' Vector-path binary OR fit for a candidate subgroup
#'
#' The vector twin of `fit_glm_for_subgroup()` with the unadjusted OR
#' closure: the same sign flip, the same existence check
#' (`.fs_existence_reason()` on the 2x2 cells), the same non-convergence
#' rule and the same `NULL` / `nonestimable` contract, with the fit done by
#' `.fs_logit_two_group()` on the already-sliced vectors instead of
#' `stats::glm()` on a data-frame slice.  Called by
#' `fit_glm_for_subgroup_fast()` after its `< 6 rows -> NULL` check.
#'
#' @param y,t Numeric vectors: outcome and treatment, already sliced.
#' @param fn_env The tagged OR closure's environment (`adverse_outcome`,
#'   `treat.name`).
#' @keywords internal
#' @noRd
.fit_or_for_subgroup_vector <- function(y, t, fn_env) {
  if (!isTRUE(fn_env$adverse_outcome)) y <- 1L - y

  why <- .fs_existence_reason("OR", .fs_binary_cells(y, t))
  if (!is.null(why)) return(list(nonestimable = TRUE, reason = why))

  core <- tryCatch(.fs_logit_two_group(y, t, fn_env$treat.name),
                   error = function(e) NULL)
  # The slow chain's error branch: NA estimate with no reason -> NULL.
  if (is.null(core)) return(NULL)
  if (isFALSE(core$converged) && !is.na(core$estimate)) {
    return(list(nonestimable = TRUE, reason = "non-convergent fit"))
  }
  if (is.na(core$estimate)) return(NULL)

  # Wald CI: estimate +/- 1.96 * SE (as in fit_glm_for_subgroup)
  z_crit <- 1.96
  list(
    hr    = core$estimate,
    lower = core$estimate - z_crit * core$se,
    upper = core$estimate + z_crit * core$se,
    med0  = NA_real_,
    med1  = NA_real_
  )
}

#' Create Result Row
#'
#' @keywords internal
create_result_row <- function(kk, covs.in, nx, event_counts, cox_result) {
  c(
    kk,                           # group id
    sum(covs.in),                 # K (number of factors)
    nx,                           # n (subgroup size)
    event_counts$total,           # E (total events)
    event_counts$d1,              # d1 (events in treatment)
    cox_result$med1,              # m1 (median survival treatment)
    cox_result$med0,              # m0 (median survival control)
    cox_result$hr,                # HR
    cox_result$lower,             # Lower CI
    cox_result$upper,             # Upper CI
    covs.in                       # Factor indicators
  )
}

#' Format Search Results
#'
#' @param results_list List of result rows
#' @param Z Matrix of factor indicators
#' @param details Logical. Print details
#' @param t.sofar Numeric. Time elapsed
#' @param L Integer. Number of factors
#' @param max_count Integer. Maximum combinations
#' @param filter_counts List. Counts at each filtering stage (optional)
#'
#' @keywords internal
#' @importFrom data.table data.table setorder
format_search_results <- function(results_list, Z, details, t.sofar, L, max_count,
                                  filter_counts = NULL) {

  # No results found
  if (length(results_list) == 0) {
    if (details) cat("NO subgroup candidates found\n")

    return(list(
      out.found = NULL,
      max_sg_est = NA,
      time_search = t.sofar,
      L = L,
      max_count = max_count,
      prop_max_count = 1,
      filter_counts = filter_counts
    ))
  }

  # Combine results into matrix
  HR.model.k <- do.call(rbind, results_list)

  # Convert to data.table with proper names
  hr.out <- data.table::data.table(HR.model.k)
  names(hr.out) <- c("grp", "K", "n", "E", "d1", "m1", "m0",
                     "HR", "L(HR)", "U(HR)", colnames(Z))
  rownames(hr.out) <- NULL

  # Sort by HR (descending) and K (ascending)
  hr.out <- data.table::setorder(hr.out, -HR, K)

  if (details) {
    cat("Found", nrow(hr.out), "subgroup candidate(s)\n")
  }

  # Return formatted output
  list(
    out.found = list(hr.subgroups = hr.out),
    max_sg_est = max(hr.out$HR),
    time_search = t.sofar,
    L = L,
    max_count = max_count,
    prop_max_count = 1,
    filter_counts = filter_counts
  )
}

Try the forestsearch package in your browser

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

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