Exploratory Subgroup Identification in Survival and GLM Outcomes

Documentation for package ‘forestsearch’ version 0.4.0

Help Pages

-- A --

analysis_covariates	Covariate set handed to forestsearch()/mrct_region_sims() for the paper's observed vs unobserved analysis cases.
analyze_subgroup	Analyze subgroup for summary table (OPTIMIZED)

-- B --

benchmark_spec	Random-benchmark subgroup specification
bootstrap_results	Bootstrap Results for ForestSearch with Bias Correction
bootstrap_ystar	Bootstrap Ystar Count Matrix
build_classification_table	Build Classification Rate Table from Simulation Results
build_cox_formula	Build Cox Model Formula
build_estimation_table	Build Estimation Properties Table from Simulation Results

-- C --

calibrate_cens_adjust	Calibrate Censoring Adjustment to Match DGM Reference Distribution
calibrate_glm_interaction	Calibrate GLM Interaction for a Target Subgroup Effect Size
calibrate_k_inter	Calibrate k_inter for Target Subgroup Hazard Ratio
calibrate_k_treat	Calibrate k_treat for Target Overall Hazard Ratio
calibrate_L_eff	Calibrate L_eff from Simulation Results
check_censoring_dgm	Diagnose Censoring Consistency Between DGM Source Data and Simulated Data
collect_results	Collect Results from foreach with Error Handling
compare_detection_curves	Compare Detection Curves Across Sample Sizes
compare_fs_subgroups	Compare Subgroup Membership Across Two Analyses
compare_multiple_survreg	Compare Multiple Survival Regression Models
compare_selection_rules	Compare forestsearch Runs Across Selection-Rule Combinations
compare_subgroup_sims	Compare two extreme-subgroups simulation studies
compute_detection_probability	Compute Probability of Detecting True Subgroup
compute_detection_probability_glm	Compute Detection Probability for GLM Outcomes
compute_dgm_cde	Compute and Attach CDE Values to a DGM Object
compute_frontier_cis	Compute Naive and Split-Derived 95% CIs for Pareto Frontier Members
compute_node_metrics	Compute node metrics for a policy tree
confint.dina	Wald confidence intervals for DINA coefficients.
consistency_resample	Resampling approximation to the splitting consistency rate
consistency_resample_compare	Validate the consistency approximation against literal splitting (Cox)
count_boot_id	Count ID Occurrences in Bootstrap Sample
cox_ahr_cde_analysis	Comprehensive Wrapper for Cox Spline Analysis with AHR and CDE Plotting
cox_cs_fit	Fit Cox Model with Cubic Spline for Treatment Effect Heterogeneity
cox_summary	Cox model summary for subgroup (OPTIMIZED)
create_dgm_for_mrct	Create Data Generating Mechanism for MRCT Simulations
create_forest_theme	Create Forest Plot Theme with Size Controls
create_gbsg_dgm	Create GBSG-Based AFT Data Generating Mechanism
create_glm_row	Compute GLM Effect Estimate for a Single Subgroup
create_grf_config	Helper Functions for GRF Subgroup Analysis
create_summary_table	Create Enhanced Summary Table for Baseline Characteristics
cv_compare_results	Compare Multiple CV Results
cv_metrics_tables	Create Metrics Tables for Cross-Validation Results
CV_sgs	Cross-Validation Subgroup Match Summary
cv_summary_tables	Create Summary Tables from forestsearch_KfoldOut Results
cv_summary_text	Create Compact CV Summary Text

-- D --

dina	Estimate heterogeneous treatment effects via DINA (data-frame interface)
dina_bagged	Bagged DINA with IJ variance (data-frame interface)
dina_fit	Estimate heterogeneous treatment effects via DINA
dina_fit_bagged	Bagged DINA with infinitesimal-jackknife variance
dina_frontier	Extract DINA per-covariate Pareto frontiers as forestsearch cuts
dina_subgroup	Identify a harm subgroup from a DINA fit via univariate threshold search
dina_subgroup_bootstrap	Selection-adjusted bootstrap CI for dina_subgroup()
dina_subgroup_refit	Standard within-subgroup treatment-effect model for a DINA subgroup
dummy_encode	Dummy-code a data frame (numeric pass-through, factors expanded)
d_eff_binary	Effective Information for Binary Outcomes (Logistic)
d_eff_continuous	Effective Information for Continuous Outcomes (Gaussian)
d_eff_count	Effective Information for Count Outcomes (Poisson)
d_eff_survival	Effective Information for Survival (Cox PH)

-- E --

early_stop_decision	Early Stopping Decision
estimate_propensity_scores	Estimate Propensity Scores
evaluate_comparison	Evaluate a Comparison Expression Without eval(parse())
evaluate_consistency_twostage	Evaluate Consistency (Two-Stage Algorithm)
evaluate_cuts_once	Cache and validate cut expressions efficiently
evaluate_subgroup_consistency	Evaluate Subgroup Consistency (Single-Stage)
expand_covariates	Expand a seed covariate frame to n_super rows via a Gaussian copula.
explain_pareto_selection	Describe the Pareto-Frontier Selection in Words
extract_grf_args	Recover the GRF arguments used inside a forestsearch run
extract_selected_subgroups	Tidy summary of selected subgroups across a comparison run

-- F --

figure_note	Generate Figure Note for Quarto/RMarkdown
filter_by_lassokeep	Filter a vector by LASSO-selected variables
filter_call_args	Filter and merge arguments for function calls
find_k_inter_for_target_hr	Find k_inter Value to Achieve Target Harm Subgroup Hazard Ratio
find_leaf_split	Find the split that leads to a specific leaf node (deprecated)
find_required_sample_size	Find Minimum Sample Size for Target Detection Power
fit_causal_forest	Fit causal survival forest
fit_cox_models	Fit Cox Models for Subgroups
fit_policy_trees	Fit policy trees up to specified depth
forestsearch	ForestSearch: Exploratory Subgroup Identification
forestsearch_bootstrap_dofuture	ForestSearch Bootstrap with doFuture Parallelization
forestsearch_Kfold	ForestSearch K-Fold Cross-Validation
forestsearch_KfoldOut	ForestSearch K-Fold Cross-Validation Output Summary
forestsearch_tenfold	ForestSearch Repeated K-Fold Cross-Validation
forest_height	Recommended figure height for a forest panel
format_bootstrap_table	Format Bootstrap Results Table with gt
format_CI	Format Confidence Interval for Estimates
format_fs_details	Format ForestSearch Details Output for Beamer Two-Column Display
format_oc_results	Format Operating Characteristics Results as GT Table
fpr_approx	Approximate Procedure-Level False Positive Rate
fpr_calibration	Direct Simulation-Based FPR Calibration at a Specific Threshold Pair
fpr_calibration_transfer	Transfer Corrected FPR Prediction to a Nearby Threshold Pair
frontier_member_flags	Per-Subject Membership Matrix for Pareto Frontier Members
fs_assert_membership	Assert the exported selected-subgroup membership matches forestsearch's own
fs_declaration_calibration	Calibrated declaration threshold and family-wise size of the p-star screen
fs_dgm_feasibility	Design-time feasibility of a DGM's planted region
fs_dgm_scale	Sampling Scale of the Difference-in-Means Estimator
fs_export_maxeff_family	Materialize the maxeff candidate family as 0/1 membership columns
fs_family_report	Report which stages of the candidate family are data-dependent
fs_fdr_report	Operating False-Discovery Rate of a Fitted ForestSearch Analysis
fs_focus_tag	Stem tag for a (subgroup_method, sg_focus) pair
fs_identification_summary	Identification structure across a sweep
fs_identification_table	Identification-structure table
FS_labels	Convert Factor Code to Label
fs_mr_oc_summary	Operating-Characteristics Summary of a Multiplier-Resampling Payload
fs_oc_family_enumerate	Enumerate the candidate family on a DGM's population frame
fs_oc_grid	Sweep the declaration thresholds on one draw set per trial size
fs_oc_invert	Invert the family declaration rate for a target
fs_oc_predict	Predicted operating characteristics of the search over a candidate family
fs_plot_bias_coverage	Bias-vs-coverage display (three panels)
fs_rule_covariate_pairs	Covariate signatures of the realized rules
fs_scale_se	Estimator Standard Deviation at a Given Trial Size
fs_sim_bias_coverage	Bias and coverage summary for one simulation cell
fs_sym_root	Symmetric Square Root of a Covariance Matrix
fs_to_guohe	Run Guo and He Algorithm 3 on a forestsearch maxeff fit

-- G --

generate_aft_dgm_flex	Generate Synthetic Survival Data using AFT Model with Flexible Subgroups
generate_bootstrap_synthetic	Generate Synthetic Data using Bootstrap with Perturbation
generate_bootstrap_with_noise	Generate Bootstrap Sample with Added Noise
generate_detection_curve	Generate Detection Probability Curve
generate_gbsg_bootstrap_general	Generate Synthetic GBSG Data using Generalized Bootstrap
generate_glm_dgm	Generate GLM-Based Data Generating Mechanism
get_combinations_info	Get all combinations of subgroup factors up to maxk
get_conf_force	Get forced cut expressions for variables
get_conf_force_jq	Get J-quantile cut expressions for variables
get_covs_in	Get indicator vector for selected subgroup factors
get_Cox_sg	Fit Cox Model for Subgroup
get_dfpred	Generate Prediction Dataset with Subgroup Treatment Recommendation
get_dfRes	Bootstrap Confidence Interval and Bias Correction Results
get_FSdata	ForestSearch Data Preparation and Feature Selection
get_leff	Get L_eff at a Given Sample Size
get_split_hr_fast	Fast Cox Model HR Estimation
get_subgroup_membership	Get subgroup membership vector
gg_forest	ggplot2 / patchwork forest plot
glm_cs_fit	Fit GLM with Spline Treatment-Biomarker Interaction
glm_effect_profile	GLM Treatment-Effect Profile for Continuous Biomarker Interaction
grf.subg.eval	Evaluates the performance of GRF-identified subgroups, including hazard ratios, bias, and predictive values. This function is typically used in simulation studies to assess the performance of the GRF subgroup identification method.
grf.subg.harm.glm	GRF Subgroup Identification for GLM Outcomes
grf.subg.harm.survival	GRF Subgroup Identification for Survival Data
guohe_adaptive_r	Cross-validated choice of the shrinkage tuning parameter r
guohe_algorithm3	De-biased inference for the best subgroup over a large enumerated family

-- H --

hrCI_format

Format Hazard Ratio and Confidence Interval

-- I --

inject_mrct_structure	Build an aft_dgm_flex with synthetic regions and paper-style effect structure.
interpret_estimation_table	Generate Narrative Interpretation of Estimation Properties
interpret_search_config	Interpret and Diagnose Search Configuration

-- L --

lasso_selection	LASSO selection for Cox model
latest_rds	Find the Most Recent .rds File Matching a Pattern
load_leff_calibration	Load L_eff Calibration Results

-- M --

make_effect_estimator	Make an Effect-Estimator Closure
make_region_model	Build the logistic region model and draw Region on a population.
mrct_region_sims	MRCT Regional Subgroup Simulation
mrct_truth_by_region	Truth by region on the super-population: prevalence, x_pred shift, causal AHR / CDE, and a large-sample Cox HR on UNCENSORED potential outcomes. Compare HR_cox_PO with the censored-trial HR from sim_region_metrics(): a gap between them isolates the prognostic-shift / follow-up-truncation mechanism (the Feb-2026 deck) from covariate shift (AHR itself differing by region).
mr_estimates_table	Multiplier-resampling (MR) estimates table (bootstrap-table format)

-- N --

n_pcnt

Calculate n and percent

-- P --

pareto_frontier_table	Format Pareto Frontier of Candidate Subgroups
plot.forestsearch	Plot ForestSearch Results
plot.fs_binary_plot	Plot GLM Subgroup Outcomes
plot.fs_forestplot	Plot Method for ForestSearch Forest Plot
plot.fs_sg_plot	Plot Method for fs_sg_plot Objects
plot.subgroup_sims_summary	Forest plot of an extreme-subgroups summary
plot_detection_curve	Plot Detection Probability Curve
plot_effect_distribution	Three-Panel Effect-Distribution Violin from Simulation Results
plot_fs_identification_involvement	Covariate involvement across the sweep
plot_fs_identification_structure	Composition of the identified subgroup by structure
plot_fs_rule_pairs	Selected-covariate-pair frequencies
plot_km_band_forestsearch	Plot Kaplan-Meier Survival Difference Bands for ForestSearch Subgroups
plot_pareto_combined	Combined Pareto-Frontier Plot Across Configurations Sharing a Passing Set
plot_pareto_frontier	Plot the Pareto Frontier of Candidate Subgroups
plot_region_modifier	True log-HR psi0(x) along x_pred with region histograms (paper Fig. 3 analogue)
plot_sg_distribution	Plot Distribution of Identified Subgroups
plot_sg_glm_outcomes	Plot GLM Subgroup Outcomes
plot_sg_results	Plot ForestSearch Subgroup Results
plot_sg_weighted_km	Plot Weighted Kaplan-Meier Curves for ForestSearch Subgroups
plot_spline_treatment_effect	Plot Spline Treatment Effect Function
plot_subgroup_effects	Plot Subgroup Analysis Results
plot_subgroup_results_forestplot	Plot Subgroup Results Forest Plot
predict.dina	Predicted DINA values for new covariate data.
predict_fpr_corrected	Predict Corrected Null FPR
prepare_subgroup_data	Prepare subgroup data for analysis
print.cox_ahr_cde	Print method for cox_ahr_cde objects
print.dina_bagged	Print a bagged DINA fit.
print.dina_subgroup	Print a 'dina_subgroup' result.
print.dina_subgroup_bootstrap	Print a 'dina_subgroup_bootstrap' result.
print.dina_subgroup_refit	Print a 'dina_subgroup_refit' result.
print.forestsearch	Print Method for forestsearch Objects
print.forestsearch_comparison	Print Method for forestsearch_comparison
print.fpr_calibration	Print method for 'fpr_calibration' objects
print.fs_binary_plot	Plot GLM Subgroup Outcomes
print.fs_bootstrap	Print Method for ForestSearch Bootstrap Results
print.fs_cv_summary	Print Method for fs_cv_summary Objects
print.fs_declaration_calibration	Calibrated declaration threshold and family-wise size of the p-star screen
print.fs_dgm_feasibility	Design-time feasibility of a DGM's planted region
print.fs_dgm_scale	Print method for 'fs_dgm_scale' objects
print.fs_family_report	Report which stages of the candidate family are data-dependent
print.fs_fdr_report	Print method for 'fs_fdr_report' objects
print.fs_forestplot	Print Method for ForestSearch Forest Plot
print.fs_forest_theme	Print Method for ForestSearch Forest Theme
print.fs_kfold	Print Method for K-Fold CV Results
print.fs_mr_oc	Print method for 'fs_mr_oc' objects
print.fs_sg_plot	Print Method for fs_sg_plot Objects
print.fs_tenfold	Print Method for Repeated K-Fold CV Results
print.fs_weighted_km	Print Method for fs_weighted_km Objects
print.gbsg_dgm	Print Method for gbsg_dgm Objects
print.glm_cs_fit	Fit GLM with Spline Treatment-Biomarker Interaction
print.glm_dgm	Print method for 'glm_dgm' objects
print.glm_effect_profile	Print method for glm_effect_profile objects
print.guohe_a3	Print method for guohe_a3 objects
print.guohe_ar	Print method for guohe_ar objects
print.hte_test	Print method for 'hte_test' objects
print.leff_calibration	Print method for 'leff_calibration' objects
print.multi_survreg_comparison	Print method for survreg_comparison objects
print_grf_details	Print detailed output for debugging
process_conf_force_expr	Process forced cut expression for a variable

-- Q --

quick_km_band_plot

Quick Plot KM Bands from ForestSearch

-- R --

render_forestplot	Render ForestSearch Forest Plot
render_reference_table	Render Reference Simulation Table as gt
reset_workers	Reset a Parallel Worker Pool
rmst_calculation	RMST calculation for subgroup
run_null_calibration	Run Null Calibration Simulation
run_simulation_analysis	Run One Simulation Replicate
run_single_consistency_split	Run Single Consistency Split
run_subgroup_sims	Run the extreme-subgroups simulation study

-- S --

save_forestplot	Save ForestSearch Forest Plot to File
save_leff_calibration	Save L_eff Calibration Results
select_best_subgroup	Select best subgroup based on criterion
sensitivity_analysis_k_inter	Sensitivity Analysis of Hazard Ratios to k_inter
setup_gbsg_dgm	Set Up a GBSG-Based AFT Data Generating Mechanism
setup_parallel_SGcons	Set up parallel processing for subgroup consistency
sgdist_fig_height	Adaptive Figure Height for a Subgroup-Distribution Plot
SGplot_estimates	Violin/Boxplot Visualization of HR Estimates
sg_consistency_out	Output Subgroup Consistency Results
sg_tables	Enhanced Subgroup Summary Tables (gt output)
SG_tab_estimates	Subgroup summary table estimates
simulate_from_dgm	Simulate Survival Data from AFT Data Generating Mechanism
simulate_from_gbsg_dgm	Simulate Trial Data from GBSG DGM
simulate_from_glm_dgm	Simulate Trial Data from a GLM Data Generating Mechanism
sim_region_metrics	Region-consistency metrics on a simulated trial (ITT and optionally a subgroup)
sort_subgroups	Sort Subgroups by Focus (post-consistency)
subgroup.consistency	Evaluate Subgroup Consistency
subgroup.search	Subgroup Search for Treatment Effect Heterogeneity (Improved, Parallelized)
subgroup_cox	Cox per-subgroup fit function
subgroup_glm	GLM per-subgroup fit function
suggest_thresholds	Suggest Screening and Consistency Thresholds
summarize_bootstrap_events	Summarize Bootstrap Event Counts
summarize_bootstrap_results	Enhanced Bootstrap Results Summary
summarize_bootstrap_subgroups	Summarize Bootstrap Subgroup Analysis Results
summarize_cv_results	Summarise ForestSearch Cross-Validation Diagnostics
summarize_simulation_results	Summarize Simulation Results
summary.cox_ahr_cde	Summary method for cox_ahr_cde objects
summary.dina	Summary method for a DINA fit.
summary.forestsearch	Summary Method for forestsearch Objects
summary.fpr_calibration	Summary method for 'fpr_calibration' objects
summary.subgroup_sims	Summarize an extreme-subgroups simulation study
summaryout_mrct	Summary Tables for MRCT Simulation Results

-- T --

test_constant_cate	Test for Constant Conditional Average Treatment Effect
test_hte	Run Both Crump et al. Tests
test_hte_from_forestsearch	HTE Test Using ForestSearch-Selected Covariates
test_zero_cate	Test for Zero Conditional Average Treatment Effect

-- V --

validate_grf_data	Validate input data for GRF analysis
validate_k_inter_effect	Validate k_inter Effect on HR Heterogeneity
validate_mrct_data	Validate Dataset for MRCT Simulations
validate_subgroups	Validate subgroup definitions against a data frame

-- W --

wilson_ci

Wilson Score Confidence Interval