View source: R/run_simulation_analysis.R
| run_simulation_analysis | R Documentation |
General replacement for the legacy run_simulation_analysis() that
was coupled to the legacy GBSG simulator (since removed) and GBSG-specific
column names. This version calls simulate_from_dgm and accepts
explicit column-name parameters, making it applicable to any DGM built
with generate_aft_dgm_flex.
run_simulation_analysis(
sim_id,
dgm,
n_sample,
analysis_time = Inf,
cens_adjust = 0,
max_follow = NULL,
muC_adj = NULL,
confounders_base = c("v1", "v2", "v3", "v4", "v5", "v6", "v7"),
n_add_noise = 0L,
outcome_name = "y_sim",
event_name = "event_sim",
treat_name = "treat_sim",
harm_col = "flag_harm",
run_fs = TRUE,
run_fs_grf = TRUE,
run_grf = TRUE,
methods = NULL,
fs_params = list(),
grf_params = list(),
cox_formula = NULL,
cox_formula_adj = NULL,
n_sims_total = NULL,
seed_base = 8316951L,
verbose = FALSE,
verbose_n = NULL,
debug = FALSE,
keep = character(0),
keep_first_n = Inf
)
sim_id |
Integer. Simulation replicate index (used as seed offset). |
dgm |
An |
n_sample |
Integer. Per-replicate sample size. |
analysis_time |
Numeric. Calendar time of analysis on the DGM time
scale. Use |
cens_adjust |
Numeric. Log-scale shift to censoring times passed to
|
max_follow |
Deprecated. Use |
muC_adj |
Deprecated. Use |
confounders_base |
Character vector of base confounder names. |
n_add_noise |
Integer. Number of independent N(0,1) noise variables
to append. Default |
outcome_name |
Name of the observed time column in simulated data.
Default |
event_name |
Name of the event indicator column. Default
|
treat_name |
Name of the treatment column. Default |
harm_col |
Name of the true-subgroup indicator column. Default
|
run_fs |
Logical. Run ForestSearch (LASSO). Default |
run_fs_grf |
Logical. Run ForestSearch (LASSO + GRF). Default
|
run_grf |
Logical. Run standalone GRF. Default |
methods |
Optional specification of analysis arms that generalizes the
Each arm's overrides are merged on top of |
fs_params |
Named list of ForestSearch parameter overrides. Any
element of |
grf_params |
Named list of GRF parameter overrides. |
cox_formula |
Optional Cox formula for unadjusted ITT. |
cox_formula_adj |
Optional adjusted Cox formula. |
n_sims_total |
Integer. Total simulations (for progress messages). |
seed_base |
Integer. Base seed; replicate seed = |
verbose |
Logical. Print progress messages. Default |
verbose_n |
Integer. If set, only print for |
debug |
Logical. Print detailed debug output. Default |
keep |
Character vector. Optional names of heavy diagnostic
objects to attach as a list in
Default |
keep_first_n |
Integer. When |
A data.table with one row per analysis method.
Always-present scalar columns cover: true-subgroup size/effect
from the DGM, per-method detection flag (any.H), estimated
subgroup size (size.H, size.Hc), effect estimates
(hr.H.hat, hr.Hc.hat, hr.itt, and their true
counterparts), classification metrics against the DGM-stored
subgroup (sens, spec, ppv, npv), and
pairwise concordance between methods (agree.*.*,
kappa.*.*). For a GLM outcome (fs_params$outcome_type
set and not "survival") hr.itt, hr.H.hat,
hr.Hc.hat, hr.H.true and hr.Hc.true come from a
two-arm glm() in each set and are on the scale
fs_params$effect_measure names, treatment against control: the
odds ratio ("OR") and rate ratio ("IRR") are the
exponentiated treatment coefficient and the mean difference
("MD") the coefficient; the risk difference ("RD") and
risk ratio ("RR") are the difference and ratio of the two fitted
arm proportions, and the rate difference ("IRD") the difference
of the two fitted arm rates, per unit of exposure when the column named
by fs_params$offset.name is in the data (the convention under
which the "IRR" value is their ratio). The ahr.* truth
columns (compute_aor) use the same scales, with one
exception: with an offset (the DGM's offset_var in
generate_glm_dgm, and fs_params$offset.name),
the "IRD" truth is a difference in
expected counts per patient, over each patient's own exposure, not per
unit of exposure (for a constant rate difference it is the mean exposure
times the per-unit value). As of v0.2.0 the following ForestSearch
diagnostic columns are also always populated (NA for GRF
rows):
sg.defCharacter. Cut-expression string of the
identified subgroup, formed as
paste(fs_full$sg.harm, collapse = " & "). Empty
string when no subgroup was identified. Read across all
replicates to diagnose which cuts the method is selecting
(e.g., table(results$sg.def)).
sg.n_factorsInteger. Number of factors in the identified subgroup definition.
n_candidates_evaluatedInteger. Number of candidate subgroups actually evaluated for consistency (before or at the early-stop candidate).
n_candidates_totalInteger. Total number of candidate subgroups available.
n_passedInteger. Number of candidates meeting the consistency threshold.
consistency_algorithmCharacter. "fixed"
or "twostage".
early_stop_triggeredLogical. Whether
evaluation stopped early due to stop_threshold.
fs_minutesNumeric. Wall time for the FS run in minutes.
The analogous GRF row carries sg.def (from
grf_result$sg.harm.id) and grf_selected_depth.
When keep is non-empty and sim_id <= keep_first_n,
the heavy objects are attached as
attr(result, "diagnostics") — a named list with one
element per keeper (fs_full, grf_full, etc.).
GLM-specific parameters (outcome_type, effect_measure,
offset.name) must be passed inside fs_params, not as
top-level arguments. They route only to the estimation step
(.extract_fs_estimates_gen, .extract_grf_estimates_gen),
not to forestsearch() itself, which uses Cox PH for subgroup
identification in v0.1.x. Passing these as top-level arguments will
result in them being silently ignored.
run_simulation_analysis() is designed to be called inside a
foreach() %dofuture% loop (one replicate per worker). In
that idiom, outer parallelism is provided by %dofuture%
(one replicate per worker) and the inner forestsearch()
call should run sequentially within each worker. Running both layers
multisession produces nested parallelism: each outer worker tries to
spawn its own pool of inner workers, which parallelly rejects
with a 300\
To prevent this, default_sim_params() sets
parallel_args = list(plan = "sequential") as the default for
the inner forestsearch() call. Users who call
run_simulation_analysis() once at the top level (e.g., for
interactive debugging) and want the inner pipeline to run in parallel
can opt back in by passing
fs_params = list(parallel_args = list(plan = "multisession", workers = N)).
simulate_from_dgm,
generate_aft_dgm_flex, setup_gbsg_dgm
## Not run:
dgm <- setup_gbsg_dgm(model = "null", verbose = FALSE)
# Inner forestsearch() runs sequentially by default; safe for both
# interactive use and embedding inside foreach() %dofuture% loops.
result <- run_simulation_analysis(sim_id = 1, dgm = dgm, n_sample = 500)
# Opt back into inner multisession for a one-off top-level call:
result <- run_simulation_analysis(
sim_id = 1,
dgm = dgm,
n_sample = 500,
fs_params = list(parallel_args = list(plan = "multisession",
workers = 4))
)
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.