plot_sg_glm_outcomes: Plot GLM Subgroup Outcomes

View source: R/plot_sg_glm_outcomes.R

plot_sg_glm_outcomesR Documentation

Plot GLM Subgroup Outcomes

Description

Creates a publication-ready visualization of identified subgroup outcomes for binary or continuous endpoints. This is the GLM counterpart to plot_sg_weighted_km for survival endpoints.

Usage

plot_sg_glm_outcomes(
  fs.est,
  fs_bc = NULL,
  outcome.name,
  treat.name,
  offset.name = NULL,
  effect_measure = NULL,
  outcome_type = NULL,
  adjust_covariates = NULL,
  sg0_name = "Questionable",
  sg1_name = "Recommend",
  E.name = "Treatment",
  C.name = "Control",
  bar_colors = c("steelblue", "coral"),
  show_effect = TRUE,
  show_bc = TRUE,
  show_itt = TRUE,
  conf.level = 0.95,
  title = NULL,
  subtitle = NULL,
  verbose = FALSE
)

## S3 method for class 'fs_binary_plot'
print(x, ...)

## S3 method for class 'fs_binary_plot'
plot(x, ...)

Arguments

fs.est

A forestsearch object containing df.est with treat.recommend column.

fs_bc

Optional. Bootstrap results from forestsearch_bootstrap_dofuture for bias-corrected annotations.

outcome.name

Character. Name of outcome column.

treat.name

Character. Name of treatment column.

offset.name

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

effect_measure

Character or NULL. Effect measure. Auto-detected from fs.est$effect_measure if NULL.

outcome_type

Character or NULL. One of "binary", "continuous". Auto-detected from fs.est$outcome_type if NULL.

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 plotted effect model for, matching the adjustment used during search/estimation. When NULL, resolved from fs.est$args_call_all$adjust_covariates so the plot reflects the same (adjusted or unadjusted) scale as the fit. Columns must be present in fs.est$df.est.

sg0_name

Character. Label for H subgroup (treat.recommend == 0). Default: "Questionable".

sg1_name

Character. Label for Hc subgroup (treat.recommend == 1). Default: "Recommend".

E.name

Character. Label for experimental/treatment arm. Default: "Treatment".

C.name

Character. Label for control arm. Default: "Control".

bar_colors

Character vector of length 2. Colors for control and treatment bars. Default: c("steelblue", "coral").

show_effect

Logical. Annotate with effect estimate. Default TRUE.

show_bc

Logical. Annotate with bias-corrected estimate when fs_bc is provided. Default TRUE.

show_itt

Logical. Include an ITT (full population) panel. Default TRUE.

conf.level

Numeric. Confidence level for intervals. Default 0.95.

title

Character or NULL. Plot title.

subtitle

Character or NULL. Plot subtitle.

verbose

Logical. Print diagnostic messages. Default FALSE.

x

An fs_binary_plot object.

...

Additional arguments (unused).

Details

For binary outcomes, displays grouped bar charts of event rates by treatment arm within each subgroup. For continuous outcomes, displays point-and-errorbar charts of means (+/- SE) by treatment arm. Both are annotated with the effect estimate and optional bias-corrected estimate from the bootstrap.

The effect annotation follows the fit's orientation: its estimator is built with the fit's stored adverse_outcome (fs.est$args_call_all$adverse_outcome) or, when none is stored, with forestsearch's rule (TRUE for binary and count outcomes, FALSE otherwise), so it is on the scale of the fit's own estimates, sign included. The plotted per-arm rates or means (and the returned data) are the raw outcome and do not follow it. So for an unadjusted fit where a lower outcome is adverse (adverse_outcome = FALSE, the default for continuous outcomes) the annotated effect and the treated-minus-control difference of the plotted values have opposite signs (for OR and RR, the log of the effect): an MD annotation is the control mean minus the treated mean. Count outcomes and the rate measures (IRR, IRD) are not reoriented (see make_effect_estimator).

Value

A list of class "fs_binary_plot" containing:

plot

A ggplot2 object.

data

Data frame of per-arm summaries used for the plot.

effects

Data frame of effect estimates per subgroup.

sg_definition

Character. Subgroup definition label.

figure_note

Character. Auto-generated figure note.

Examples

## Not run: 
fs <- forestsearch(df, outcome_type = "binary", effect_measure = "OR",
                   ...)
result <- plot_sg_glm_outcomes(fs, outcome.name = "status",
                                treat.name = "hormon")
print(result)

## End(Not run)


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