View source: R/forestsearch_main.R
| forestsearch | R Documentation |
Implements advanced statistical methods for exploratory subgroup
identification in clinical trials. Provides tools for identifying
patient subgroups with differential treatment effects using machine
learning approaches including Generalized Random Forests ('GRF'),
LASSO regularization, and exhaustive combinatorial search algorithms.
Supports survival endpoints (Cox proportional hazards), binary
outcomes (log odds ratio, log relative risk, risk difference),
continuous outcomes (mean difference), and count / rate outcomes
(log incidence rate ratio via Poisson, quasi-Poisson, or
negative-binomial GLMs with optional person-time offset). Features
bootstrap bias correction using infinitesimal jackknife methods to
address selection bias in post-hoc analyses. Designed for clinical
researchers conducting exploratory subgroup analyses in randomized
controlled trials, particularly for multi-regional clinical trials
('MRCT') requiring regional consistency evaluation. Methods are
described in Leon et al. (2024) \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1002/sim.10163")}.
Post-selection inference for the reported subgroup (multiplier
resampling, mr_inference = TRUE) follows León and Anderson
(2026a) \Sexpr[results=rd]{tools:::Rd_expr_doi("10.48550/arXiv.2609.38361")}. The current methodology for
the search itself – forest search as closed-form stability selection
on splitting consistency, the family-wise false-declaration rate and
the two-subgroup claim – is given in León and Anderson (2026b)
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.48550/arXiv.2610.28379")}.
forestsearch(
df.analysis,
outcome.name = "tte",
event.name = "event",
treat.name = "treat",
id.name = "id",
potentialOutcome.name = NULL,
flag_harm.name = NULL,
confounders.name = NULL,
parallel_args = list(plan = "multisession", workers = .default_parallel_workers(),
show_message = TRUE),
df.predict = NULL,
df.test = NULL,
is.RCT = TRUE,
seedit = 8316951,
est.scale = "hr",
use_lasso = FALSE,
use_grf = FALSE,
grf_res = NULL,
grf_cuts = NULL,
use_dina = FALSE,
dina_res = NULL,
dina_cuts = NULL,
dina_args = list(),
dina_select_statistic = c("effect", "dina"),
subgroup_method = c("consistency", "dina", "grf"),
max_n_confounders = 1000,
grf_depth = 2,
grf_selection = c("frontier", "tree"),
grf_select_statistic = c("effect", "dr"),
dmin.grf = 0,
frac.tau = 0.8,
return_selected_cuts_only = TRUE,
conf_force = NULL,
defaultcut_names = NULL,
cut_type = "default",
exclude_cuts = NULL,
replace_med_grf = FALSE,
cont.cutoff = 4,
conf.cont_medians = NULL,
conf.cont_medians_force = NULL,
conf.cont_jcuts = NULL,
collapse_cuts = TRUE,
collapse_cuts_args = list(),
n.min = 60,
n.min.frac = 0.1,
effect.threshold = NULL,
consistency.threshold = NULL,
hr.threshold = 1.25,
hr.consistency = 1,
sg_focus = "hr",
selection_rule = "neighborhood",
effect_neighborhood = 0.1,
fs.splits = 1000,
m1.threshold = Inf,
pconsistency.threshold = 0.9,
stop_threshold = pconsistency.threshold,
pconsistency.digits = 2,
show_candidate_summary = FALSE,
max_print = 10,
d0.min = 10,
d1.min = 10,
max.minutes = 3,
minp = 0.025,
details = FALSE,
quiet = FALSE,
maxk = 2,
by.risk = 12,
plot.sg = FALSE,
plot.grf = FALSE,
max_subgroups_search = Inf,
vi.grf.min = NULL,
use_twostage = TRUE,
twostage_args = list(),
consistency_method = c("resample", "split"),
outcome_type = c("survival", "binary", "continuous", "count"),
effect_measure = NULL,
offset.name = NULL,
adverse_outcome = NULL,
overdispersion = c("none", "quasi", "negbin"),
grf_count_transform = c("log", "identity"),
tune_grf = FALSE,
adjust_covariates = NULL,
ps_method = NULL,
ps_adjust_method = c("none", "iptw", "dr_gcomp"),
ps_hat = NULL,
mr_inference = FALSE,
mr_inference_args = list()
)
df.analysis |
Data frame. Analysis dataset with required columns. | |||||||||||||||||||||||||
outcome.name |
Character. Name of time-to-event outcome variable. Default "tte". | |||||||||||||||||||||||||
event.name |
Character. Name of event indicator (1=event, 0=censored). Default "event". | |||||||||||||||||||||||||
treat.name |
Character. Name of treatment variable (1=treatment, 0=control). Default "treat". | |||||||||||||||||||||||||
id.name |
Character. Name of subject ID variable. Default "id". | |||||||||||||||||||||||||
potentialOutcome.name |
Character. Name of potential outcome variable (optional). | |||||||||||||||||||||||||
flag_harm.name |
Character. Name of true harm flag for simulations (optional). | |||||||||||||||||||||||||
confounders.name |
Character vector. Names of candidate subgroup-defining variables. | |||||||||||||||||||||||||
parallel_args |
List. Parallel processing configuration:
To disable parallelism entirely, pass
| |||||||||||||||||||||||||
df.predict |
Data frame. Prediction dataset (optional). | |||||||||||||||||||||||||
df.test |
Data frame. Test dataset (optional). | |||||||||||||||||||||||||
is.RCT |
Logical. Is this a randomized controlled trial? Default TRUE. | |||||||||||||||||||||||||
seedit |
Integer. Random seed. Default 8316951. | |||||||||||||||||||||||||
est.scale |
Character. Estimation scale ("hr" or "1/hr"). Default "hr". | |||||||||||||||||||||||||
use_lasso |
Logical. Use LASSO for variable selection. Default FALSE.
The default changed from | |||||||||||||||||||||||||
use_grf |
Logical. Generate additional candidate cuts from a GRF
fit: tree-derived cutpoints are extracted via
| |||||||||||||||||||||||||
grf_res |
GRF results object (optional, for reuse). | |||||||||||||||||||||||||
grf_cuts |
List. Custom GRF cut points (optional). | |||||||||||||||||||||||||
use_dina |
Logical. Generate additional screening-stage candidate
cuts from a DINA per-covariate Pareto frontier, fed into
| |||||||||||||||||||||||||
dina_res |
A fitted DINA object (optional, for reuse). When NULL
and | |||||||||||||||||||||||||
dina_cuts |
Character vector of pre-supplied DINA cut expressions (optional). When supplied, the DINA fit / frontier step is skipped and these are used directly. | |||||||||||||||||||||||||
dina_args |
Named list of DINA tuning options, all optional.
Recognised keys:
The same holds for every frontier key, not only
Under | |||||||||||||||||||||||||
dina_select_statistic |
Character, one of | |||||||||||||||||||||||||
subgroup_method |
Character, one of | |||||||||||||||||||||||||
max_n_confounders |
Deprecated (0.4.0.9000): accepted and
ignored with a warning. GRF variable-importance screening of the
candidate cut columns was removed so that the candidate family is the
cut grid alone unless | |||||||||||||||||||||||||
grf_depth |
Integer. GRF tree depth. Default 2. | |||||||||||||||||||||||||
grf_selection |
Character, one of | |||||||||||||||||||||||||
grf_select_statistic |
Character, one of | |||||||||||||||||||||||||
dmin.grf |
Numeric. Harm threshold on GRF's doubly robust (DR) scale,
not a number of events. It is compared with a subgroup's DR harm effect,
the subgroup mean of the DR score for control minus the subgroup mean of
the DR score for treatment (the two columns of
| |||||||||||||||||||||||||
frac.tau |
Numeric in (0, 1]. Multiplier on the GRF time horizon
passed to | |||||||||||||||||||||||||
return_selected_cuts_only |
Logical. If TRUE (default), GRF returns only cuts from the
tree depth that identified the selected subgroup meeting | |||||||||||||||||||||||||
conf_force |
Character vector of forced cut expressions (optional),
e.g. | |||||||||||||||||||||||||
defaultcut_names |
Character vector. Default cut variable names (optional). | |||||||||||||||||||||||||
cut_type |
Character. Cut strategy: | |||||||||||||||||||||||||
exclude_cuts |
Character vector. Variables to exclude from cutting (optional). | |||||||||||||||||||||||||
replace_med_grf |
Logical. Replace median with GRF cuts. Default FALSE. | |||||||||||||||||||||||||
cont.cutoff |
Integer. Cutoff for continuous vs categorical. Default 4. | |||||||||||||||||||||||||
conf.cont_medians |
Character vector of continuous confounders to cut at
their median (optional). Names, not values – the cut location is the
median computed from the supplied data, so it is not fixed by this
argument and moves with a resample. To pin a cut location, pass a literal
cut expression via | |||||||||||||||||||||||||
conf.cont_medians_force |
Character vector of additional continuous
confounders to force a median cut on (optional). Names, not values, with
the same consequence as | |||||||||||||||||||||||||
conf.cont_jcuts |
Named integer list (each value >= 1). Per-variable
J-quantile cut override for continuous covariates: for an entry
| |||||||||||||||||||||||||
collapse_cuts |
Logical. If TRUE, collapse near-redundant continuous
candidate cuts before the search. Continuous covariates can generate many
thresholds that are practically redundant (e.g. | |||||||||||||||||||||||||
collapse_cuts_args |
List of overrides merged onto the defaults
| |||||||||||||||||||||||||
n.min |
Integer or | |||||||||||||||||||||||||
n.min.frac |
Numeric in (0, 1). Fraction of the analysis sample size
used for the adaptive | |||||||||||||||||||||||||
effect.threshold |
Numeric or NULL. | |||||||||||||||||||||||||
consistency.threshold |
Numeric or NULL. | |||||||||||||||||||||||||
hr.threshold |
Numeric. Legacy name for | |||||||||||||||||||||||||
hr.consistency |
Numeric. Legacy name for
| |||||||||||||||||||||||||
sg_focus |
Character. Subgroup selection focus – what is
selected, not merely how candidates are sorted. Except for
The descriptions above are for For Per-engine resolution. Every accepted spelling, and the rule that actually runs for it on each engine:
The collapse sets, stated explicitly. On
Default Scope of the band arguments. Choosing between the three effect-oriented rules.
| |||||||||||||||||||||||||
selection_rule |
Character. Rule defining the candidate
inclusion set for | |||||||||||||||||||||||||
effect_neighborhood |
Numeric in | |||||||||||||||||||||||||
fs.splits |
Integer. Number of splits for consistency evaluation (or maximum
splits when | |||||||||||||||||||||||||
m1.threshold |
Numeric. Maximum median survival threshold. Default Inf. | |||||||||||||||||||||||||
pconsistency.threshold |
Numeric. | |||||||||||||||||||||||||
stop_threshold |
Numeric in Applies to For every other focus
Note: Values > 1.0 are not permitted. To disable early
stopping, use | |||||||||||||||||||||||||
pconsistency.digits |
Integer. Number of decimal places to which the
consistency proportion is rounded before it is compared with
| |||||||||||||||||||||||||
show_candidate_summary |
Logical. If | |||||||||||||||||||||||||
max_print |
Integer. Maximum number of candidate subgroups to print in
the pre- and post-consistency candidate summaries when
| |||||||||||||||||||||||||
d0.min |
Integer. Minimum per-arm filter for candidate subgroups.
For | |||||||||||||||||||||||||
d1.min |
Integer. Same as | |||||||||||||||||||||||||
max.minutes |
Deprecated (0.4.0.9000): accepted and
ignored. It was documented as a wall-clock budget for the
combination search but was never enforced in the parallel search
path. A non-default value emits one warning. Search scope is governed
by | |||||||||||||||||||||||||
minp |
Numeric. Minimum prevalence threshold. Default 0.025. | |||||||||||||||||||||||||
details |
Logical. Print progress details. Default FALSE. | |||||||||||||||||||||||||
quiet |
Logical. If TRUE, suppress the configuration summary
message printed at startup. Useful when | |||||||||||||||||||||||||
maxk |
Integer. Maximum number of factors per subgroup. Default 2. | |||||||||||||||||||||||||
by.risk |
Integer. Risk table interval. Default 12. | |||||||||||||||||||||||||
plot.sg |
Logical. Plot subgroup survival curves. Default FALSE. | |||||||||||||||||||||||||
plot.grf |
Logical. Plot GRF results. Default FALSE. | |||||||||||||||||||||||||
max_subgroups_search |
Numeric. Maximum subgroups to evaluate.
Default Set a finite value only to bound runtime, knowing it can change which
subgroup is selected. The default was | |||||||||||||||||||||||||
vi.grf.min |
Deprecated (0.4.0.9000): accepted and ignored
with a warning. GRF variable-importance screening of the candidate cut
columns was removed so that the candidate family is the cut grid alone
unless | |||||||||||||||||||||||||
use_twostage |
Logical. Use two-stage sequential consistency algorithm for
improved performance. Default TRUE. When TRUE,
| |||||||||||||||||||||||||
twostage_args |
List. Parameters for two-stage algorithm (only used when
| |||||||||||||||||||||||||
consistency_method |
Character. | |||||||||||||||||||||||||
outcome_type |
Character. One of | |||||||||||||||||||||||||
effect_measure |
Character or | |||||||||||||||||||||||||
offset.name |
Character or | |||||||||||||||||||||||||
adverse_outcome |
Logical or | |||||||||||||||||||||||||
overdispersion |
Character. Overdispersion correction for
| |||||||||||||||||||||||||
grf_count_transform |
Character. Transformation applied to the
count outcome before passing to | |||||||||||||||||||||||||
tune_grf |
Logical. If | |||||||||||||||||||||||||
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 | |||||||||||||||||||||||||
ps_method |
This option is implemented but has not been
tested against the manuscript analyses or the simulation studies of
León and Anderson (2026a, 2026b), which use the unadjusted
treatment-only fits.
Character or GLM outcome types only ( | |||||||||||||||||||||||||
ps_adjust_method |
This option is implemented but has not been
tested against the manuscript analyses or the simulation studies of
León and Anderson (2026a, 2026b), which use the unadjusted
treatment-only fits.
Character. PS adjustment method: GLM outcome types only, and consumed only when | |||||||||||||||||||||||||
ps_hat |
This option is implemented but has not been
tested against the manuscript analyses or the simulation studies of
León and Anderson (2026a, 2026b), which use the unadjusted
treatment-only fits.
Numeric vector or Not carried into bootstrap replicates or cross-validation folds: a
resample has the same row count but different subjects, so a supplied
score would be attached to the wrong people. Both re-estimate their own
score per replicate/fold under | |||||||||||||||||||||||||
mr_inference |
Logical. Whether to follow the search with multiplier
resampling (MR): a refit-free de-biased estimate of the selected
subgroup's treatment effect, an interval for it, and a harm-confirmation
flag. Default | |||||||||||||||||||||||||
mr_inference_args |
List of optional MR controls; used only when
|
Algorithm Overview:
Variable Selection: GRF identifies variables with treatment effect heterogeneity; LASSO selects most predictive
Subgroup Discovery: Exhaustive search over factor combinations
up to maxk
Consistency Validation: Split-sample validation ensures reproducibility
Selection: Choose subgroup based on sg_focus criterion
Two-Stage Consistency Algorithm:
When use_twostage = TRUE, the consistency evaluation uses an optimized
algorithm that can provide 3-10x speedup:
Stage 1: Quick screening with n.splits.screen splits
eliminates clearly non-viable candidates
Stage 2: Sequential batched evaluation with early stopping for candidates passing Stage 1
The two-stage algorithm is recommended for:
Exploratory analyses with many candidate subgroups
Large fs.splits values (>200)
Iterative model development
For final regulatory submissions, use_twostage = FALSE may be preferred
for exact reproducibility.
A list of class "forestsearch" containing:
Consistency evaluation results including:
out_sg: Selected subgroup based on sg_focus
sg_focus: Focus criterion used
df_flag: Treatment recommendations
sg.harm: Subgroup definition labels (character vector
of cut names) – same as the top-level sg.harm
sg.harm.id: per-subject 0/1 membership indicator (not a character vector of cut expressions; see the Field naming collision section below)
algorithm: "twostage" or "fixed"
n_candidates_evaluated: Number evaluated
n_passed: Number passing threshold
Subgroup search results
Candidate confounders considered
Confounders after variable selection
Analysis data with treatment recommendations
Prediction data with recommendations (if provided)
Test data with recommendations (if provided)
Total computation time
GRF results object
Subgroup focus criterion used
Selected subgroup definition – character vector
of factor-level cut names. Recommended accessor for
displaying the identified subgroup (e.g.,
paste(obj$sg.harm, collapse = " & ")). NULL if
no subgroup was identified.
GRF cut points used
Proportion of max combinations searched
Maximum subgroup HR estimate
GRF plot object (if plot.grf = TRUE)
All arguments for reproducibility
The resolved threshold configuration:
outcome_type, effect_measure, screening,
consistency, screening_natural,
consistency_natural, scale, pconsistency and
two description strings. Read $scale before reading
$screening. The phrase "the screening threshold" names two
different numbers depending on which object is inspected:
On the survival path $screening is
log(hr.threshold) – the scale the admission set and
multiplier resampling work on – while the candidate search
itself compares the fitted hazard ratio against
hr.threshold on the natural scale. The two
are the same threshold on two scales, and
$screening_natural holds the search's value.
On the GLM paths $screening is the value
the search compares against directly: the link scale for ratio
measures (log of the supplied ratio) and the identity
scale for RD, IRD and MD.
$consistency follows the same convention, and
$pconsistency is the rate pconsistency.threshold,
which has no scale.
Character scalar recording whether the candidate
family the identifier ranked over is fixed – the condition
multiplier resampling requires (see mr_inference).
"no-front-end": subgroup_method = "consistency" with
use_lasso, use_grf and use_dina all
FALSE. Named for what it checks: no fitted model shapes the
family on the observed data. This is weaker than the manuscript's
Section 2.1 fixed family, which additionally requires resample-
invariant cut locations – quantile-derived cuts are not. "conditional-removable": the same method with
at least one front end on – data-dependent, but fixed by turning
those off. "conditional-inherent": subgroup_method of
"dina" or "grf", where the family is generated by
fitting a model to the same data and cannot be made fixed.
Descriptive only; it never raises a condition.
Multiplier-resampling (MR) result, or NULL
when MR did not run. See fs_mr_inference for fields
(naive, debiased, selection_bias,
settings, harm_flag, timing_seconds). MR
approximates the full bootstrap (FB) to leading order; its interval is
the infinitesimal-jackknife analogue of the FB interval under
ci_method = "field" (the default under
subgroup_method = "consistency") and under "ij", and the
subgroup robust-SE interval under "wald". Under "field"
the return also carries the field element.
Logical, three-valued. TRUE when MR ran
and the de-biased estimate still indicates harm under
confirm_rule; FALSE when MR ran and it does not;
NA when MR did not run or could not be computed.
NA is therefore absence of evidence, not evidence
against harm – test it with is.na() before
isTRUE(), which collapses NA to FALSE and so
reports "harm not confirmed" for an analysis that never ran. See
the vocabulary section.
Three arguments carry thresholds, and two of them have the word "consistency" in the name. They are different quantities:
c1 – effect.threshold (legacy hr.threshold)The screening threshold on a candidate subgroup's own effect, estimated on the full sample. A candidate must clear it to enter the consistency stage.
c2 – consistency.threshold (legacy
hr.consistency)An effect threshold, applied to the subgroup's effect estimated within each split half. Not a proportion, and not the consistency rate.
p* – pconsistency.thresholdA proportion in
[0, 1]: the fraction of splits that must clear c2.
Not an effect threshold.
In one line: c2 sets the bar a split half must clear, and p* counts how
often that bar is met.
Resolved defaults, per estimand. Reading
hr.consistency's default as "1.0" is misleading on the GLM paths:
when neither threshold is supplied, the value a run actually uses is
resolved from the estimand. The resolved pairs are:
| resolved estimand | c1 | c2 |
HR (survival) | 1.25, compared by the search on the natural HR scale | 1.0 |
OR, RR, IRR | log(1.25) | log(1.0), i.e. 0 |
RD | 0.05 | 0.0 |
IRD | 0.01 | 0.0 |
MD | 0.0 | 0.0 |
Supplying effect.threshold or consistency.threshold (or the
legacy names) suppresses the corresponding default remap, and the supplied
value is used on the scale shown above, with one exception: for RD
and IRD a supplied value greater than 1 is taken to be on a ratio
scale and is replaced by the default in the table: effect.threshold
by 0.05 for RD or 0.01 for IRD, with two warnings (one from
the input check, one from the remap), and consistency.threshold by
0, with one warning. The remapped effect.threshold
is the value the fit records (in threshold_config and
args_call_all, which a bootstrap or cross-validation replay
re-uses), and it is also the DINA harm floor wherever DINA selects a cut
(subgroup_method = "dina", or use_dina = TRUE screening with
selected_only = TRUE): on these two routes RD and IRD
run with DINA only on the gaussian family, whose floor is the
resolved effect.threshold (see dina_args). Screening with
selected_only = FALSE has neither the restriction nor this floor:
it contributes the frontier candidate set on any family, for RD and
IRD too.
The pair rule, on the consistency path with a ratio estimand. For
subgroup_method = "consistency" with survival (HR) or binary
effect_measure = "OR" – the two estimands whose c1 and c2 sit on
one comparable ratio scale – the two thresholds are treated as a pair:
c2 > c1 is an error. It is degenerate: the
consistency-stage entry condition re-screens the admitted family on c2,
so candidates the screen let through are discarded at the stage boundary,
and when none survives the consistency stage does not run at all and the
fit reads as a finding of no subgroup. c2 = c1 is allowed.
c1 supplied without c2 derives
c2 = 0.80 * c1 on the ratio scale (on the log scale an
additive shift of log(0.80), never 0.80 * log(c1)):
1.25 -> 1.00, 1.00 -> 0.80, 0.90 -> 0.72. Announced with a message, and
carried into every bootstrap replicate and CV fold. The default pair
(1.25, 1.0) is the rule's fixed point, so a call that sets neither
threshold is unaffected. An explicitly supplied c2, in either
spelling, is never overridden.
Supplying both spellings of one threshold at disagreeing values is an error naming both.
Neither rule applies under subgroup_method = "dina" or
"grf" (which return before the consistency stage and never consult
c2), nor to the identity-scale estimands RD, IRD,
MD, nor to IRR.
pconsistency.threshold is not remapped. It is a rate, and
it is identical for every outcome_type and every estimand.
The top-level sg.harm on this object and the
grp.consistency$sg.harm nested field both hold a character
vector of cut expressions. The nested grp.consistency$sg.harm.id
field holds a per-subject 0/1 membership indicator, not a cut
vector – unlike sg.harm.id on GRF result objects, which
does hold cut expressions. See
subgroup.consistency and grf.subg.harm.glm
for the full discussion of this naming collision. Code that must
handle both object types should prefer the top-level sg.harm
accessor on forestsearch results.
Four different things in this package used to share the word "gate". They are distinct, they happen at different stages, and only the last one is a pass/fail decision:
Which candidate subgroups are even eligible
to be considered: hr.threshold, pconsistency.threshold,
n.min, d0.min, d1.min, maxk. Applied during
the search.
Which admissible candidate is chosen as the
estimated subgroup: sg_focus. Applied during the search.
Correcting the chosen subgroup's treatment effect for the optimism of having chosen it, and putting an interval around the corrected value. This is FB and MR below. Applied after the search.
The one pass/fail: does the corrected estimate
still indicate harm? This is confirm_rule against
t_confirm, reported as mr_harm_confirmed.
Full bootstrap (FB) — forestsearch_bootstrap_dofuture.
Resamples subjects, and re-runs the entire subgroup search inside
every replicate, so the replicate may select a different subgroup than the
original analysis did. That is what lets it correct the selection-induced
bias in the reported treatment effect, and supply an
infinitesimal-jackknife interval. It is the reference method, and it is
expensive: cost scales with nb_boots times the cost of one search.
Multiplier resampling (MR) — fs_mr_inference, turned
on by mr_inference = TRUE. Resamples nothing; it perturbs the
per-subject influence contributions (dfbeta) of a single set of
fits with random mean-zero multipliers, and re-applies the selection rule on
each perturbed draw. It corrects the same selection bias FB corrects and
produces the same kind of interval, to leading order, at a small fraction of
the cost — no refits. MR is post-selection inference on a
completed analysis: it runs after the subgroup has been chosen and
cannot change which subgroup is identified. Running with
mr_inference = TRUE and FALSE gives identical
sg.harm, df.est and max_sg_est. MR approximates FB;
it does not replace it.
Harm confirmation. Once MR has produced a de-biased estimate,
mr_inference_args$confirm_rule decides whether that estimate still
indicates harm:
"point" (default)Compares the de-biased point
estimate to t_confirm.
"ci"Compares the one-sided 95% selection-adjusted
lower bound to t_confirm. Strictly the stronger
requirement, so anything it confirms "point" also confirms.
t_confirm is the threshold those rules compare against, on
the effect scale (HR, OR, RR, IRR; or RD, MD for differences) —
not the working log scale used internally. Left NULL it resolves to
the null effect: 1 for ratio measures, 0 for differences. It
is deliberately set near the null rather than at hr.threshold,
because the de-biasing correction over-shrinks genuine effects, so
re-applying the screening threshold to a corrected estimate would discard
true findings.
mr_harm_confirmed carries the answer, and is three-valued:
TRUE = MR ran and harm is confirmed; FALSE = MR ran and harm
is not confirmed; NA = MR did not run, or could not be computed.
NA is not evidence against harm. It arises when
mr_inference = FALSE (the default), when no subgroup was identified,
or when the MR step was skipped or failed for the outcome/consistency
combination in use. Because isTRUE(NA) is FALSE, code that
reads this field with isTRUE() alone silently reports "harm not
confirmed" for an analysis that was never performed; branch on
is.na() first.
The arguments adjust_covariates, ps_method,
ps_adjust_method and ps_hat are implemented, but the
published analyses and simulation studies of León and Anderson (2026a,
2026b) use the unadjusted treatment-only fits, and no coverage or bias
results exist for these paths. They are untested, not known to be wrong.
Users who need them should check them on their own data, for example
against a direct coxph() or glm() fit of the selected
subgroup.
León, L. F. and Anderson, K. M. (2026a). Inference for standard trial estimands after data-driven subgroup discovery. arXiv:2609.38361. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.48550/arXiv.2609.38361")}
León, L. F. and Anderson, K. M. (2026b). Interpretable subgroup identification across survival and generalized-linear outcomes. arXiv:2610.28379. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.48550/arXiv.2610.28379")}
FDA Guidance for Industry: Enrichment Strategies for Clinical Trials
Athey & Imbens (2016). Recursive partitioning for heterogeneous causal effects. PNAS.
Wager & Athey (2018). Estimation and inference of heterogeneous treatment effects using random forests. JASA.
León et al. (2024). \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1002/sim.10163")}
subgroup.consistency for consistency evaluation details
forestsearch_bootstrap_dofuture for the full bootstrap (FB)
fs_mr_inference for multiplier resampling (MR), the
mr_inference = TRUE step
mr_estimates_table to render the MR estimates
fs_fdr_report to sweep harm-confirmation thresholds
(c_confirm) and measure what confirmation buys
forestsearch_Kfold for cross-validation
Package website: https://larry-leon.github.io/forestsearch/
Source code: https://github.com/larry-leon/forestsearch
## Not run:
## Example 1 -- Survival (GBSG, hormone therapy): the analysis of
## León and Anderson (2026a, Sec. 6) and of the survival-post-selection
## article on the package website. Forest search over the cut grid (no
## model-based front ends), effMaxSG selection in a 10% effect
## neighbourhood, multiplier-resampling inference for the reported
## subgroup computed inside the fit.
library(survival)
df_gbsg <- within(gbsg, {
id <- seq_len(nrow(gbsg))
time_months <- rfstime / 30.4375
grade3 <- ifelse(grade == "3", 1, 0)
})
fs_surv <- forestsearch(
df.analysis = df_gbsg,
outcome.name = "time_months",
event.name = "status",
treat.name = "hormon",
id.name = "id",
confounders.name = c("age", "meno", "size", "grade3", "nodes",
"pgr", "er"),
is.RCT = TRUE,
use_lasso = FALSE, use_grf = FALSE, use_dina = FALSE,
conf.cont_jcuts = list(er = 10, pgr = 10),
conf_force = c("er <= 0", "pgr <= 0"),
subgroup_method = "consistency",
sg_focus = "effMaxSG",
selection_rule = "neighborhood",
effect_neighborhood = 0.10,
hr.threshold = 1.0,
hr.consistency = 1.0,
pconsistency.threshold = 0.90,
consistency_method = "resample",
fs.splits = 1000,
n.min = 60, d0.min = 10, d1.min = 10, maxk = 2,
mr_inference = TRUE,
mr_inference_args = list(draws = 5000L),
parallel_args = list(plan = "multisession", workers = 4),
seedit = 8316951
)
print(fs_surv)
## mr_estimates_table() lays the multiplier-resampling estimates out in the
## format of the bootstrap tables. A bootstrap template is optional:
## mr_estimates_table(fs_surv) builds the table from fs_surv alone. With a
## template, the descriptive columns come from the bootstrap result (a few
## replicates are enough for the layout; the survival-post-selection
## article compares the two at full size).
fs_boot <- forestsearch_bootstrap_dofuture(
fs.est = fs_surv,
nb_boots = 20,
parallel_args = list(plan = "multisession", workers = 4)
)
mr_estimates_table(fs_surv, boot_results = fs_boot, est.scale = "hr")
## Example 2 -- Binary outcome, odds ratio (ACTG175, ZDV+ddI vs ddI):
## the forest-search analysis of León and Anderson (2026a, Table S3); the
## binary analysis of León and Anderson (2026b) selects the same region
## with effect_neighborhood = 0.20. Adverse-scale outcome (1 = no CD4
## improvement at week 20), OR thresholds at the null, same selection rule
## and multiplier-resampling gate as Example 1.
if (requireNamespace("speff2trial", quietly = TRUE)) {
actg <- subset(speff2trial::ACTG175, arms %in% c(1L, 3L))
actg <- actg[!is.na(actg$cd420), ]
actg$id <- seq_len(nrow(actg))
actg$treat <- as.integer(actg$arms == 1L)
actg$y_binary_neg <- as.integer(!(actg$cd420 > actg$cd40))
bin_vars <- c("hemo", "homo", "drugs", "race", "gender", "symptom")
for (v in bin_vars) actg[[v]] <- as.numeric(actg[[v]])
fs_bin <- forestsearch(
df.analysis = actg,
outcome.name = "y_binary_neg",
event.name = "y_binary_neg",
treat.name = "treat",
id.name = "id",
confounders.name = c("age", "preanti", "wtkg", "karnof", "cd40",
"cd80", bin_vars),
outcome_type = "binary",
effect_measure = "OR",
adverse_outcome = TRUE,
use_lasso = FALSE, use_grf = FALSE, use_dina = FALSE,
conf.cont_jcuts = list(cd40 = 10, wtkg = 10),
subgroup_method = "consistency",
sg_focus = "effMaxSG",
selection_rule = "neighborhood",
effect_neighborhood = 0.10,
effect.threshold = 1.0,
consistency.threshold = 1.0,
pconsistency.threshold = 0.90,
consistency_method = "resample",
fs.splits = 500,
n.min = 60, d0.min = 10, d1.min = 10, maxk = 2,
mr_inference = TRUE,
mr_inference_args = list(draws = 5000L),
parallel_args = list(plan = "multisession", workers = 4),
seedit = 8316951
)
print(fs_bin)
}
## Example 3 -- Continuous outcome, mean difference (ACTG175): the
## continuous application of León and Anderson (2026b), with the field
## (calibrated one-sided) bounds for the selected subgroup and its
## complement. Outcome is CD4 decline from baseline to week 20 (adverse
## scale); thresholds are on the mean-difference scale.
if (requireNamespace("speff2trial", quietly = TRUE)) {
actg <- subset(speff2trial::ACTG175, arms %in% c(1L, 3L))
actg <- actg[!is.na(actg$cd420), ]
actg$id <- seq_len(nrow(actg))
actg$treat <- as.integer(actg$arms == 1L)
actg$y_decline <- actg$cd40 - actg$cd420
bin_vars <- c("hemo", "homo", "drugs", "race", "gender", "symptom")
for (v in bin_vars) actg[[v]] <- as.factor(actg[[v]])
fs_cont <- forestsearch(
df.analysis = actg,
outcome.name = "y_decline",
treat.name = "treat",
id.name = "id",
confounders.name = c("age", "preanti", "wtkg", "karnof", "cd40",
"cd80", bin_vars),
outcome_type = "continuous",
effect_measure = "MD",
adverse_outcome = TRUE,
use_lasso = FALSE, use_grf = FALSE, use_dina = FALSE,
conf.cont_jcuts = list(age = 10, preanti = 10, wtkg = 10,
karnof = 10, cd40 = 10, cd80 = 10),
sg_focus = "effMaxSG",
selection_rule = "neighborhood",
effect_neighborhood = 0.20,
effect.threshold = 10,
consistency.threshold = 5,
pconsistency.threshold = 0.90,
consistency_method = "resample",
fs.splits = 500,
n.min = 60, d0.min = 10, d1.min = 10, maxk = 2,
mr_inference = TRUE,
mr_inference_args = list(ci_method = "field", draws = 5000L,
include_complement = TRUE,
field_complement = TRUE,
field_scale_complement = "selected",
return_reselection = TRUE),
parallel_args = list(plan = "sequential"),
seedit = 8316951
)
print(fs_cont)
}
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.