plot_subgroup_results_forestplot: Plot Subgroup Results Forest Plot

View source: R/plot_subgroup_results_forestplot.R

plot_subgroup_results_forestplotR Documentation

Plot Subgroup Results Forest Plot

Description

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

Usage

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")
)

Arguments

fs_results

List. A list containing ForestSearch analysis results with elements:

  • fs.est: ForestSearch estimation object from forestsearch

  • fs_bc: Bootstrap bias-corrected results from forestsearch_bootstrap_dofuture

  • fs_kfold: K-fold cross-validation results from forestsearch_Kfold or forestsearch_tenfold (optional)

  • fs_OOB: Out-of-bag cross-validation results (optional, alternative to fs_kfold)

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:

  • subset_expr: Character string for subsetting (e.g., "BM> 1")

  • name: Display name for the subgroup

  • type: Either "reference" for pre-specified or "posthoc" for identified

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 set_xaxis(x_trans = "log") since 0.4.0.9000; earlier versions documented the log axis but drew a linear one (GitHub #7).

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 create_forest_theme(). Use this to control plot sizing (fonts, row height, CI appearance, CV annotation font size). Default: NULL (uses default theme).

outcome_type

Character or NULL (default). One of "survival", "binary", or "continuous". If NULL, auto-detected from fs_results$fs.est$outcome_type, or "survival" when that is absent.

effect_measure

Character or NULL. Effect measure for GLM outcomes (e.g., "OR", "RR", "IRR", "RD", "IRD", "MD"). Auto-detected from fs_results$fs.est$effect_measure if NULL.

offset.name

Character or NULL. Follow-up time column for rate-based measures (IRR, IRD).

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 NULL. Baseline covariates to adjust the GLM-row effect models for, matching the adjustment used during search/estimation. When NULL, resolved from fs_results$fs.est$args_call_all$adjust_covariates so the forest-plot CIs share the fit's scale. Applies to GLM rows only.

extreme_ci_cap

Numeric. Multiplier for outlier-resistant axis limits when xlim_method = "data". If the most extreme CI bound exceeds twice the second-most extreme, the axis limit is capped at extreme_ci_cap times the second-most extreme bound. Default 1.5. Set to Inf to disable.

xlim_method

Character. Method for computing default axis limits for GLM measures when xlim is not user-supplied. "clinical" (default) uses fixed clinically meaningful ranges: HR/OR/RR/IRR = (0.25, 4.0), RD/IRD = (-0.50, 0.50), MD = data-driven. "data" computes limits from the actual estimates with outlier resistance controlled by extreme_ci_cap.

Details

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 Labeling Convention

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

Orientation of the GLM rows

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.

Value

A list containing:

plot

The forestploter grob object (can be rendered with plot())

data

The data frame used for the forest plot

row_types

Character vector of row types for styling reference

cv_metrics

Cross-validation metrics text (if available)

See Also

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

Examples

## 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)


forestsearch documentation built on Nov. 15, 2026, 9:06 a.m.