View source: R/compare_selection_rules.R
| compare_selection_rules | R Documentation |
Runs forestsearch once per combination of
sg_focus[i] + selection_rule[i] (tuple semantics; the
two vectors are paired element-by-element and must have the same
length). All other arguments are held fixed across runs and passed
through via ....
compare_selection_rules(
df.analysis,
sg_focus,
selection_rule,
compute_cis = TRUE,
n_splits = 1000L,
ci_seed = 1L,
plot_xlim = NULL,
show_band = TRUE,
combo_labels = NULL,
verbose = TRUE,
...
)
df.analysis |
Analysis-ready data frame; passed to
|
sg_focus |
Character vector of |
selection_rule |
Character vector of |
compute_cis |
Logical. If |
n_splits |
Integer. Passed to
|
ci_seed |
Integer. Passed to
|
plot_xlim |
Numeric vector of length 2 (or |
show_band |
Logical. Whether to draw the effect-band
shading on each plot. Default |
combo_labels |
Character vector of length |
verbose |
Logical. Print one line per combination during
execution. Default |
... |
Additional arguments passed through to every
|
For each combination the wrapper:
Captures the in-flight console output from forestsearch
(including the pre-consistency Candidate Evaluation
Preview and post-consistency Candidate Evaluation
Summary when show_candidate_summary = TRUE is passed).
Optionally computes the frontier CIs via
compute_frontier_cis.
Builds the Pareto-frontier plot via
plot_pareto_frontier.
The captured stdout is returned per combination so the caller can
cat() it later for side-by-side inspection in a Quarto chunk.
Plot objects are returned individually and (when
patchwork is installed) composed into a single side-by-side
figure. The full fs object for each combination is returned
so downstream diagnostics (pareto_frontier_table,
explain_pareto_selection) can be run without re-fitting.
A list with class "forestsearch_comparison" and
components:
combosdata.frame with columns
sg_focus, selection_rule, label.
fsNamed list of forestsearch result
objects, one per combination. NULL entries mark fits that
errored.
ci_tabNamed list of frontier-CI tables (or all
NULL if compute_cis = FALSE).
plotsNamed list of ggplot objects, one per
combination.
plot_gridA single patchwork object placing
the plots side by side, or NULL if patchwork isn't
installed.
plot_combinedA single ggplot composing all
configurations onto one Pareto plot, with each winner labeled
S1: <combo_label>, S2: <combo_label>, etc.
Returned only when ALL successful configurations share an
identical passing set (see plot_pareto_combined
for the equality criterion); NULL otherwise. See
plot_combined_subsets below for the per-subset
fallback when some – but not all – configurations match.
plot_combined_subsetsNamed list of ggplot
objects, one per equivalence class of configurations sharing
an identical passing set. Only groups of size \ge 2
are included (a singleton group has no peer to combine
with). Names are derived from the shared sg_focus
when constant within a group (e.g., "effMaxSG"); from
the concatenated combo labels otherwise. When all valid
combos share one passing set this list contains exactly one
element, equal to plot_combined. The list is empty
when no two combos match.
combined_skip_reasonCharacter scalar or
NULL. When plot_combined is NULL
because the equality precondition failed, this captures the
specific reason – size mismatch, definition-set mismatch,
or value drift on a named column – as a single string.
NULL when the combined plot was built or when fewer
than two fits succeeded.
consoleNamed list of character vectors – the captured stdout from each forestsearch run (full output).
diagnosticsNamed list of per-combo slices of the
captured output: each element is a list with character-scalar
fields preview (the CANDIDATE EVALUATION
PREVIEW block), summary (the CANDIDATE
EVALUATION SUMMARY block), and full (the entire
captured stdout, same content as console[[i]]
collapsed to a single string). preview and
summary are NA_character_ when the corresponding
banner is absent (e.g.\ show_candidate_summary was
FALSE, or the run errored before reaching it). This
slice is what a comparison document should display as the
primary diagnostic; full (or console[[i]])
remains available for an expandable / on-demand view of the
complete run output.
errorsNamed list of error messages (or NULL) for combos that failed.
With sg_focus = c("hrMaxSG", "hrMaxSG") and
selection_rule = c("pareto", "both"), two runs are
performed: one with (hrMaxSG, pareto) and one with
(hrMaxSG, both). The length-mismatch case raises an error.
All stdout from each forestsearch() call is captured (not
just the diagnostic tables) via capture.output(). The
PREVIEW / SUMMARY blocks are clearly delineated by banner separators
within the captured text. Use cat(out$console[[i]]) to
replay the output in a Quarto chunk; results = "asis" works
but is not required since the captured text already includes
newlines.
forestsearch,
plot_pareto_frontier,
plot_pareto_combined,
pareto_frontier_table,
explain_pareto_selection,
compute_frontier_cis.
## Not run:
out <- compare_selection_rules(
df.analysis = actg_df,
sg_focus = c("hrMaxSG", "hrMaxSG"),
selection_rule = c("pareto", "both"),
# All other forestsearch args:
confounders.name = confounders.name,
outcome.name = adverse_outcome,
treat.name = treat.name,
id.name = id.name,
outcome_type = "continuous",
effect_measure = "MD",
adverse_outcome = TRUE,
hr.threshold = 10,
hr.consistency = 5,
pconsistency.threshold = 0.90,
show_candidate_summary = TRUE,
details = TRUE
)
# Inspect captured console output for combo 1
cat(out$console[[1]])
# Side-by-side plot
print(out$plot_grid)
# Use fs object for downstream diagnostics
pareto_frontier_table(out$fs[[1]], ci_table = out$ci_tab[[1]])
explain_pareto_selection(out$fs[[2]], ci_table = out$ci_tab[[2]])
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.