View source: R/plot_subgroup_results_forestplot.R
| plot_subgroup_results_forestplot | R Documentation |
Generates a comprehensive forest plot showing:
ITT (Intent-to-Treat) population estimate
Reference subgroups (e.g., by biomarker levels)
Post-hoc identified subgroups with bias-corrected estimates
Cross-validation agreement metrics as annotations
plot_subgroup_results_forestplot(
fs_results,
df_analysis,
subgroup_list = NULL,
outcome.name,
event.name,
treat.name,
E.name = "Experimental",
C.name = "Control",
est.scale = "hr",
xlog = TRUE,
title_text = NULL,
arrow_text = c("Favors Experimental", "Favors Control"),
footnote_text = c("Eg 80% of training found SG: 70% of B (+) also B in CV testing"),
xlim = c(0.25, 1.5),
ticks_at = c(0.25, 0.7, 1, 1.5),
show_cv_metrics = TRUE,
cv_source = c("auto", "kfold", "oob", "both"),
posthoc_colors = c("powderblue", "beige"),
reference_colors = c("yellow", "powderblue"),
ci_column_spaces = 20,
conf.level = 0.95,
theme = NULL,
outcome_type = NULL,
effect_measure = NULL,
offset.name = NULL,
adjust_covariates = NULL,
extreme_ci_cap = 1.5,
xlim_method = c("clinical", "data")
)
fs_results |
List. A list containing ForestSearch analysis results with elements:
|
df_analysis |
Data frame. The analysis dataset with outcome, event, and treatment variables. |
subgroup_list |
List. Named list of subgroup definitions to include in the plot. Each element should be a list with:
|
outcome.name |
Character. Name of the survival time variable. |
event.name |
Character. Name of the event indicator variable. |
treat.name |
Character. Name of the treatment variable. |
E.name |
Character. Label for experimental arm (default: "Experimental"). |
C.name |
Character. Label for control arm (default: "Control"). |
est.scale |
Character. Estimate scale: "hr" or "1/hr" (default: "hr"). |
xlog |
Logical. If TRUE (default), the x-axis is plotted on a
logarithmic scale. This is standard for hazard ratio forest plots
where equal distances represent equal relative effects.
Implemented through forestploter's |
title_text |
Character. Plot title (default: NULL). |
arrow_text |
Character vector of length 2. Arrow labels for forest plot (default: c("Favors Experimental", "Favors Control")). |
footnote_text |
Character vector. Footnote text for the plot explaining CV metrics (default provides CV interpretation guidance; set to NULL to omit). |
xlim |
Numeric vector of length 2. X-axis limits (default: c(0.25, 1.5)). |
ticks_at |
Numeric vector. X-axis tick positions (default: c(0.25, 0.70, 1.0, 1.5)). |
show_cv_metrics |
Logical. Whether to show cross-validation metrics (default: TRUE if fs_kfold or fs_OOB available). |
cv_source |
Character. Source for CV metrics: "auto" (default, uses both if available, otherwise whichever is present), "kfold" (use fs_kfold only), "oob" (use fs_OOB only), or "both" (explicitly use both fs_kfold and fs_OOB, with K-fold first then OOB). |
posthoc_colors |
Character vector. Colors for post-hoc subgroup rows (default: c("powderblue", "beige")). |
reference_colors |
Character vector. Colors for reference subgroup rows (default: c("yellow", "powderblue")). |
ci_column_spaces |
Integer. Number of spaces for the CI plot column width. More spaces = wider CI column (default: 20). |
conf.level |
Numeric. Confidence level for intervals (default: 0.95 for 95% CI). Used to calculate the z-multiplier as qnorm(1 - (1 - conf.level)/2). |
theme |
An fs_forest_theme object from |
outcome_type |
Character or |
effect_measure |
Character or |
offset.name |
Character or |
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 |
extreme_ci_cap |
Numeric. Multiplier for outlier-resistant axis
limits when |
xlim_method |
Character. Method for computing default axis limits
for GLM measures when |
Creates a publication-ready forest plot displaying identified subgroups with hazard ratios, bias-corrected estimates, and cross-validation metrics. This wrapper integrates ForestSearch results with the forestploter package.
ForestSearch identifies subgroups based on hazard ratio thresholds:
sg.harm: Contains the definition of the "harm" or "questionable"
subgroup (H)
treat.recommend == 0: Patient is IN the harm subgroup (H)
treat.recommend == 1: Patient is in the COMPLEMENT subgroup
(Hc, typically benefit)
For est.scale = "hr" (searching for harm):
H (treat.recommend=0): Subgroup defined by sg.harm with elevated HR (harm/questionable)
Hc (treat.recommend=1): Complement of sg.harm (potential benefit)
For est.scale = "1/hr" (searching for benefit):
Roles are reversed: H becomes the benefit group
For a non-survival outcome every row estimated from the data (ITT,
reference and post-hoc subgroups) is a GLM effect. What follows is for
the default est.scale = "hr". With a fit
(fs_results$fs.est) its estimator is built with the fit's stored
adverse_outcome or, when none is stored, with
forestsearch's rule (TRUE for binary and count
outcomes, FALSE otherwise), so each row is on the scale of the
fit's own estimates, sign included; without a fit the estimator's
default (adverse_outcome = TRUE) is used. The rows show the arm
sizes, not the arm means; the arm means and their raw difference
(Diff in sg_tables and
mr_estimates_table) do not follow the orientation. So for
an unadjusted fit where a lower outcome is adverse
(adverse_outcome = FALSE, the default for continuous outcomes) a
row's effect and the raw treated-minus-control difference have opposite
signs (for OR and RR, the log of the effect): an MD row is the control
mean minus the treated mean. Count outcomes and the rate measures (IRR,
IRD) are not reoriented (see make_effect_estimator).
Bias-corrected rows are taken from fs_results$fs_bc, whose
estimator forestsearch_bootstrap_dofuture builds with the
same rule.
A list containing:
The forestploter grob object (can be rendered with plot())
The data frame used for the forest plot
Character vector of row types for styling reference
Cross-validation metrics text (if available)
forestsearch for running the subgroup analysis
forestsearch_bootstrap_dofuture for bootstrap bias correction
forestsearch_Kfold for cross-validation
create_forest_theme for customizing plot appearance
render_forestplot for rendering the plot
## Not run:
# Load ForestSearch results
load("fs_analysis_results.Rdata") # Contains fs.est, fs_bc, fs_kfold
# Define subgroups to display
subgroups <- list(
bm_gt1 = list(
subset_expr = "BM > 1",
name = "BM > 1",
type = "reference"
),
bm_gt1_size_gt19 = list(
subset_expr = "BM > 1 & tmrsize > 19",
name = "BM > 1 & Tumor Size > 19",
type = "posthoc"
)
)
# Create the forest plot with default theme
result <- plot_subgroup_results_forestplot(
fs_results = list(fs.est = fs.est, fs_bc = fs_bc, fs_kfold = fs_kfold),
df_analysis = df_itt,
subgroup_list = subgroups,
outcome.name = "os_time",
event.name = "os_event",
treat.name = "combo",
E.name = "Experimental+CT",
C.name = "CT"
)
# Create with custom theme for larger plot
large_theme <- create_forest_theme(
base_size = 14,
row_padding = c(6, 4),
cv_fontsize = 11
)
result <- plot_subgroup_results_forestplot(
fs_results = list(fs.est = fs.est, fs_bc = fs_bc, fs_kfold = fs_kfold),
df_analysis = df_itt,
subgroup_list = subgroups,
outcome.name = "os_time",
event.name = "os_event",
treat.name = "combo",
theme = large_theme
)
# Display the plot
render_forestplot(result)
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.