View source: R/subgroup_consistency_main.R
| subgroup.consistency | R Documentation |
Evaluates candidate subgroups using split-sample consistency validation. For each candidate, repeatedly splits the data and checks whether the treatment effect direction is consistent across splits.
subgroup.consistency(
df,
hr.subgroups,
hr.threshold = 1,
hr.consistency = 1,
pconsistency.threshold = 0.9,
m1.threshold = Inf,
n.splits = 100,
details = FALSE,
by.risk = 12,
plot.sg = FALSE,
maxk = 7,
Lsg,
confs_labels,
sg_focus = "hr",
selection_rule = "neighborhood",
effect_neighborhood = 0.1,
stop_Kgroups = 200,
stop_threshold = NULL,
show_candidate_summary = FALSE,
max_print = 10,
pconsistency.digits = 2,
seed = 8316951,
checking = FALSE,
use_twostage = FALSE,
twostage_args = list(),
parallel_args = list(),
estimator_fn = NULL,
consistency_threshold = NULL,
effect_label = "HR",
effect_log_scale = FALSE,
adjust_covariates = NULL,
consistency_method = c("resample", "split"),
glm_resample_spec = NULL
)
df |
Data frame containing the analysis dataset. Must include columns for outcome (Y), event indicator (Event), and treatment (Treat). |
hr.subgroups |
Data.table of candidate subgroups from subgroup search, containing columns: HR, n, E, K, d0, d1, m0, m1, grp, and factor indicators. |
hr.threshold |
Numeric. |
hr.consistency |
Numeric. |
pconsistency.threshold |
Numeric. |
m1.threshold |
Numeric. Maximum m1 threshold for filtering. Default: Inf |
n.splits |
Integer. Number of splits for consistency evaluation. Default: 100 |
details |
Logical. Print progress details. Default: FALSE |
by.risk |
Numeric. Risk interval for KM plots. Default: 12 |
plot.sg |
Logical. Generate subgroup plots. Default: FALSE |
maxk |
Integer. Maximum number of factors in subgroup. Default: 7 |
Lsg |
List of subgroup parameters. |
confs_labels |
Character vector mapping factor names to labels. |
sg_focus |
Character. Subgroup selection criterion. One of:
Default: |
selection_rule |
Character. Rule defining the candidate
inclusion set for |
effect_neighborhood |
Numeric in |
stop_Kgroups |
Integer. Maximum number of candidates to evaluate.
When the ranked pool exceeds this cap it is truncated and a warning naming
both counts and the |
stop_threshold |
Numeric in Note: Values > 1.0 are not permitted. To disable early
stopping, use Interaction with
For parallel execution, early stopping is checked after each batch
completes, so some additional candidates beyond the first meeting the
threshold may be evaluated. Use a smaller |
show_candidate_summary |
Logical. If |
max_print |
Integer. Maximum number of candidate rows printed in
each |
pconsistency.digits |
Integer. Number of decimal places to which the
consistency proportion is rounded before it is compared with
|
seed |
Integer. Random seed for reproducible consistency splits. Default: 8316951. Set to NULL for non-reproducible random splits. The seed is used both for sequential execution (via set.seed()) and parallel execution (via future.seed). |
checking |
Logical. Enable additional validation checks. Default: FALSE |
use_twostage |
Logical. Use two-stage adaptive algorithm. Default: FALSE |
twostage_args |
List. Parameters for two-stage algorithm:
|
parallel_args |
List. Parallel processing configuration:
|
estimator_fn |
Closure or |
consistency_threshold |
Numeric or |
effect_label |
Character. Column label for the effect measure in
diagnostic output (e.g., candidate subgroup table). Default |
effect_log_scale |
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 |
consistency_method |
Character. |
glm_resample_spec |
List or |
A list containing:
Selected subgroup results. When non-NULL,
contains result (sorted candidate table; top row is the
selected subgroup) and pareto_frontier (data.table of
non-dominated candidates on (effect, N), both maximized – a
post-hoc diagnostic, not used for selection).
Selection criterion used
Data frame with treatment recommendations
Subgroup definition labels – character
vector of factor-level cut names (e.g., c("z1.1", "z2.1")),
of length equal to the number of cuts defining the subgroup.
NULL if no subgroup was identified.
Per-subject subgroup-membership
indicator – integer vector of length nrow(df) with
1 if subject i is in the identified subgroup and
0 otherwise. NULL if no subgroup was identified.
Not a character vector of cut expressions; see the
Field naming collision section below.
"twostage" or "fixed"
Number of candidates actually evaluated
Total candidates available
Number meeting consistency threshold
Logical indicating if early stop occurred
Index of candidate triggering early stop
Threshold used for early stopping
Random seed used for reproducibility (NULL if not set)
The field name sg.harm.id has different semantics on
this object versus on the result objects returned by
grf.subg.harm.glm and grf.subg.harm.survival:
| Object | sg.harm.id contains | Length / type |
subgroup.consistency() result (this function) | per-subject 0/1 membership indicator | integer, length nrow(df) |
grf.subg.harm.glm() result | character vector of cut expressions | character, length = depth of selected tree |
grf.subg.harm.survival() result | character vector of cut expressions | character, length = depth of selected tree |
Practical consequence. Do not paste sg.harm.id with
paste(..., collapse = " & ") to print "the identified subgroup"
without first checking object class. For subgroup labels from a
forestsearch or subgroup.consistency() result,
use sg.harm (character vector of cut names) – the FS main
result exposes sg.harm at the top level.
This naming collision is a documented CRAN-stable API for v0.1.x and v0.2.x; it is expected to be resolved via a deprecation cycle in a future minor release.
## Not run:
# Standard evaluation
result <- subgroup.consistency(
df = trial_data,
hr.subgroups = candidates,
sg_focus = "hr",
n.splits = 400,
parallel_args = list(plan = "multisession", workers = 6)
)
# Show top 10 candidates before evaluation
result <- subgroup.consistency(
df = trial_data,
hr.subgroups = candidates,
sg_focus = "hr",
show_candidate_summary = TRUE, # Post-consistency summary
n.splits = 400
)
# With early stopping and custom batch size
result <- subgroup.consistency(
df = trial_data,
hr.subgroups = candidates,
sg_focus = "hr",
stop_threshold = 0.95,
show_candidate_summary = TRUE,
parallel_args = list(
plan = "multisession",
workers = 6,
batch_size = 2 # Check early stopping after every 2 candidates
)
)
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.