View source: R/bootstrap_dofuture_main.R
| forestsearch_bootstrap_dofuture | R Documentation |
Orchestrates bootstrap analysis for ForestSearch using doFuture parallelization. Implements bias correction methods to adjust for optimism in subgroup selection.
forestsearch_bootstrap_dofuture(
fs.est,
nb_boots,
seed = 8316951L,
details = FALSE,
show_three = FALSE,
parallel_args = list(),
digits = 4,
mr_in_replicates = FALSE
)
fs.est |
List. ForestSearch results object from |
nb_boots |
Integer. Number of bootstrap samples (recommend 500-1000). |
seed |
Integer. Random seed for reproducibility of bootstrap sample
generation. Default |
details |
Logical. If |
show_three |
Logical. If |
parallel_args |
List. Parallelization configuration with elements:
If empty list, inherits settings from original forestsearch call. |
digits |
Integer. Decimal places for construction-time numeric
formatting in |
mr_in_replicates |
Logical. Whether multiplier resampling (MR) runs
inside each bootstrap replicate. Default
The retained objects are not aggregable into an estimate for the
original analysis. Each replicate re-runs the search, selects its own
subgroup, and de-biases that subgroup – so the collection
describes MR's sampling behaviour across resampled selections, not a
better estimate of the original quantity. Averaging them, or pooling
their intervals, is an error. The bias-corrected estimate for the
original analysis is the one this function already returns in
|
An fs_bootstrap object (a list with class
c("fs_bootstrap", "list")) containing:
Data.table with bias-corrected estimates for each bootstrap iteration
List of confidence intervals for H and Hc (raw and bias-corrected)
Formatted table of subgroup estimates
Matrix (nb_boots x n) of bootstrap sample indicators
Detailed estimates for subgroup H
Detailed estimates for subgroup Hc
NULL under the default
mr_in_replicates = FALSE. Otherwise a list of length
nb_boots, element b holding replicate b's
mr_inference object (or NULL for a failed or
no-subgroup replicate), each computed against that replicate's
candidate family and selected subgroup. See the
mr_in_replicates parameter for why these must not be averaged.
(If create_summary=TRUE) Enhanced summary with tables and diagnostics
Integer. Number of bootstrap iterations requested.
Used by print.fs_bootstrap to compute identification
percentages without re-inspecting results. Added in v0.2.0.
Character vector. The subgroup identified by the
primary forestsearch call (fs.est$sg.harm),
carried forward so that print.fs_bootstrap can
report exact- and partial-match rates without retaining a
reference to fs.est. Added in v0.2.0.
Character. Outcome type of the underlying
analysis: one of "survival", "binary",
"continuous", or "count". Added in v0.2.0.
Character. Effect measure label
("HR" for survival; "OR", "RR", "RD",
"IRR", "IRD", or "MD" for GLM outcomes).
Added in v0.2.0.
Character. Estimation scale for confidence
intervals ("hr" or "1/hr"). Added in v0.2.0.
Two bias correction approaches are implemented:
Method 1 (Simple Optimism):
H_{adj1} = H_{obs} - (H^*_{*} - H^*_{obs})
where H^*_{*} is the new subgroup HR on bootstrap data and
H^*_{obs} is the new subgroup HR on original data.
Method 2 (Double Bootstrap):
H_{adj2} = 2 \times H_{obs} - (H_{*} + H^*_{*} - H^*_{obs})
where H_{*} is the original subgroup HR on bootstrap data.
H: Original subgroup (harm/questionable, treat.recommend == 0)
Hc: Complement subgroup (recommend, treat.recommend == 1)
_obs: Estimate from original data
_star: Estimate from bootstrap data
_biasadj_1: Bias correction method 1
_biasadj_2: Bias correction method 2
Unlike multiplier resampling, the full bootstrap places no alignment requirement on the identifier. It replays the entire pipeline on each resample – refitting the front ends, re-enumerating the candidate family and re-running selection – rather than linearizing the selection event, so neither of MR's two conditions (selection ranking on the inferential coefficient, and a fixed candidate family) bears on its validity. In the equivalence result those conditions state, the bootstrap is the reference standard, not a party to it.
It is therefore valid for all six identifier configurations, including the
three that rank on a native statistic: DINA under
dina_select_statistic = "dina", GRF under
grf_select_statistic = "dr", and GRF under
grf_selection = "tree". For those, it correctly estimates the
selection bias that ranking on the native statistic induces on the
reported effect \hat\beta. That is a coherent quantity, and the
estimate of it is valid – it simply sits outside the framework the
manuscript develops, which is about identifiers whose selection map and
reported effect are the same functional.
The one place an alignment check does apply here is
mr_in_replicates = TRUE, which asks for MR inside each
replicate; see that parameter.
Typical runtime: 1-5 seconds per bootstrap iteration. For 1000 bootstraps with 6 workers, expect 3-10 minutes total. Memory usage scales with dataset size and number of workers.
Original fs.est must have identified a valid subgroup
Requires packages: data.table, foreach, doFuture,
survival
For plots: requires ggplot2
forestsearch for initial subgroup identification, and its
vocabulary section for how the full bootstrap (FB) implemented here
relates to multiplier resampling (MR)
fs_mr_inference for MR, the fast refit-free approximation to
this function
mr_estimates_table to render MR estimates in this function's
table layout
fs_fdr_report for harm-confirmation threshold sweeps
bootstrap_results for the core bootstrap worker function
build_cox_formula for Cox formula construction
fit_cox_models for Cox model fitting
## Not run:
# Run ForestSearch
fs_result <- forestsearch(
df.analysis = mydata,
outcome.name = "time",
event.name = "status",
treat.name = "treatment",
confounders.name = c("age", "sex", "stage")
)
# Run bootstrap with bias correction
boot_results <- forestsearch_bootstrap_dofuture(
fs.est = fs_result,
nb_boots = 1000,
parallel_args = list(
plan = "multisession",
workers = 6,
show_message = TRUE
),
create_summary = TRUE,
create_plots = TRUE
)
# View results
print(boot_results$FSsg_tab)
print(boot_results$summary$table)
# Check success rate
mean(!is.na(boot_results$results$H_biasadj_2))
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.