forestsearch

Exploratory subgroup identification in clinical trials with survival endpoints using bootstrap bias correction.

forestsearch implements the Forest Search methodology described in Leon et al. (2024), “Exploratory subgroup identification in the heterogeneous Cox model,” Statistics in Medicine. The package screens all possible subgroups (formed by combinations of baseline factors) against Cox hazard ratio thresholds indicative of harm, selects the subgroup “maximally consistent with harm” via split-sample evaluation, and provides bias-corrected treatment effect estimates with valid confidence intervals through an infinitesimal jackknife bootstrap procedure.

Overview

In randomized clinical trials, important subgroups based on patient characteristics may not be anticipated or well understood prior to the trial. Forest Search addresses the need for exploratory, post-hoc subgroup identification by:

1. Constructing candidate factors via LASSO, Generalized Random Forests (GRF), and quartile-based binary splits.
2. Enumerating all one- and two-factor subgroup combinations meeting minimum sample size and event criteria.
3. Screening candidates against a hazard ratio threshold (default HR >= 1.25) and evaluating split-sample consistency across repeated random 50/50 splits (default R = 400).
4. Selecting the subgroup with the highest consistency rate (>= 90%) as the estimated detrimental subgroup.
5. Correcting for selection bias via bootstrap bias correction with infinitesimal jackknife variance estimation.
6. Validating stability through N-fold (leave-one-out) and K-fold cross-validation.

By reversing the treatment indicator, the same framework identifies subgroups with substantial benefit.

Installation

You can install the development version of forestsearch from GitHub:

# install.packages("pak")
pak::pak("larry-leon/forestsearch")

Or using remotes:

# install.packages("remotes")
remotes::install_github("larry-leon/forestsearch")

The package depends on weightedsurv, which is installed automatically from GitHub via the Remotes field in the DESCRIPTION.

Quick Start

library(forestsearch)

# --- Step 1: Run ForestSearch ---
fs <- forestsearch(
  df.analysis     = trial_data,
  outcome.name    = "tte",
  event.name      = "event",
  treat.name      = "treat",
  confounders.name = c("age", "biomarker", "stage", "region"),
  sg_focus        = "maxSG",
  hr.threshold    = 1.25,
  hr.consistency  = 1.0,
  pconsistency.threshold = 0.90,
  fs.splits       = 400,
  use_lasso       = TRUE,
  use_grf         = TRUE,
  parallel_args   = list(plan = "multisession", workers = 4)
)

print(fs)
summary(fs)

# --- Step 2: Bootstrap Bias Correction ---
fs_bc <- forestsearch_bootstrap_dofuture(
  fs.est    = fs,
  nb_boots  = 2000,
  parallel_args = list(plan = "multisession", workers = 6)
)

# Publication-ready tables
summaries <- summarize_bootstrap_results(fs_bc)
summaries$main_table_gt

# --- Step 3: Cross-Validation ---
# K-fold CV (repeated 10-fold)
fs_cv <- forestsearch_tenfold(
  fs.est  = fs,
  sims    = 200,
  Kfolds  = 10,
  parallel_args = list(plan = "multisession", workers = 6)
)

cv_metrics_tables(fs_cv)

# N-fold (leave-one-out) CV
fs_oob <- forestsearch_Kfold(
  fs.est  = fs,
  Kfolds  = nrow(trial_data),
  parallel_args = list(plan = "multisession", workers = 6)
)

# --- Step 4: Visualization ---
# Forest plot with bias-corrected estimates and CV metrics
plot_subgroup_results_forestplot(
  fs_results  = list(fs.est = fs, fs_bc = fs_bc, fs_kfold = fs_cv),
  df_analysis = trial_data,
  outcome.name = "tte",
  event.name   = "event",
  treat.name   = "treat"
)

# Weighted Kaplan-Meier curves by subgroup
plot_sg_weighted_km(fs, fs_bc = fs_bc)

Key Features

Core Algorithm

Bootstrap Inference

Cross-Validation

Visualization

Simulation Framework

Multi-Regional Clinical Trials

Methodology at a Glance

Forest Search identifies the subgroup maximally consistent with harm through the following procedure:

Candidate Factors ──► Enumerate Subgroups ──► HR Screening (≥ 1.25)
                                                     │
                                              Consistency Evaluation
                                              (R = 400 random 50/50 splits)
                                                     │
                                              Select Ĥ (consistency ≥ 90%)
                                                     │
                                              Bootstrap Bias Correction
                                              (B = 300–2000 replicates)

The bias-corrected estimator accounts for two sources of optimism:

β̂*(Ĥ) = β̂(Ĥ) − (1/B) Σ [η*_b(Ĥ*_b) + η*_b(Ĥ)]

where η*_b(Ĥ*_b) and η*_b(Ĥ) capture the discrepancies between bootstrap and observed data estimates for the bootstrap-selected and observed subgroups, respectively. Confidence intervals use the infinitesimal jackknife variance estimator.

Simulation studies (20,000 replicates) demonstrate:

• Type-1 error ≤ 3% for FS with LASSO (FS_l), even with noise factors
• Power 71–96% for detecting HR = 2.0 subgroups (N = 300–700)
• Conservative estimation: bias-corrected estimates underestimate harm and overestimate benefit—a favorable property for exploratory analyses
• Oracle CI coverage ≥ 95% across all scenarios

Requirements

• R ≥ 4.1.0
• Key dependencies: survival, data.table, glmnet, grf, doFuture, future, ggplot2, gt
• Optional: forestploter (forest plots), DiagrammeR (diagrams), cubature (numerical integration)

Documentation

• Getting Started vignette: vignette("forestsearch") — end-to-end walkthrough with the GBSG breast cancer trial
• Methodology vignette: vignette("methodology") — detailed statistical framework, algorithm, simulation results, and applications
• pkgdown site: https://larry-leon.github.io/forestsearch/
• Function reference: organised across 16 topic areas (core algorithm, bootstrap, CV, visualization, simulation, MRCT, and more)

Citation

If you use forestsearch in your work, please cite:

@article{Leon2024,
  author  = {Le{\'o}n, Larry F. and Jemielita, Thomas and Guo, Zifang
             and Marceau West, Rachel and Anderson, Keaven M.},
  title   = {Exploratory subgroup identification in the heterogeneous
             {C}ox model: A relatively simple procedure},
  journal = {Statistics in Medicine},
  year    = {2024},
  doi     = {10.1002/sim.10163}
}

Related Work

• Athey, S. & Imbens, G. (2016). Recursive partitioning for heterogeneous causal effects. PNAS.
• Wager, S. & Athey, S. (2018). Estimation and inference of heterogeneous treatment effects using random forests. JASA.
• Efron, B. (2014). Estimation and accuracy after model selection. JASA.

License

MIT © Larry F. Leon