R/plot_sg_glm_outcomes.R

Defines functions plot.fs_binary_plot print.fs_binary_plot plot_sg_glm_outcomes

Documented in plot.fs_binary_plot plot_sg_glm_outcomes print.fs_binary_plot

# =============================================================================
# plot_sg_glm_outcomes.R
#
# Subgroup outcome visualization for GLM (binary and continuous) outcomes.
# Analogous to plot_sg_weighted_km() for survival endpoints.
#
# For binary outcomes: grouped bar chart of event rates by treatment arm.
# For continuous outcomes: point-and-errorbar chart of means by treatment arm.
# Both annotated with effect estimates (OR, RR, RD, IRR, IRD, MD) and
# optional bias-corrected estimates from the bootstrap.
# =============================================================================


#' Plot GLM Subgroup Outcomes
#'
#' Creates a publication-ready visualization of identified subgroup outcomes
#' for binary or continuous endpoints.  This is the GLM counterpart to
#' \code{\link{plot_sg_weighted_km}} for survival endpoints.
#'
#' 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 \code{adverse_outcome}
#' (\code{fs.est$args_call_all$adverse_outcome}) or, when none is stored,
#' with \code{\link{forestsearch}}'s rule (\code{TRUE} for binary and count
#' outcomes, \code{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 \code{data}) are the raw outcome and do not follow it.  So
#' for an unadjusted fit where a lower outcome is adverse
#' (\code{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
#' \code{\link{make_effect_estimator}}).
#'
#' @param fs.est A forestsearch object containing \code{df.est} with
#'   \code{treat.recommend} column.
#' @param fs_bc Optional. Bootstrap results from
#'   \code{\link{forestsearch_bootstrap_dofuture}} for bias-corrected
#'   annotations.
#' @param outcome.name Character. Name of outcome column.
#' @param treat.name Character. Name of treatment column.
#' @param offset.name Character or \code{NULL}. Name of follow-up time
#'   column for rate-based measures (IRR, IRD).
#' @param effect_measure Character or \code{NULL}. Effect measure.
#'   Auto-detected from \code{fs.est$effect_measure} if \code{NULL}.
#' @param outcome_type Character or \code{NULL}. One of \code{"binary"},
#'   \code{"continuous"}.  Auto-detected from \code{fs.est$outcome_type}
#'   if \code{NULL}.
#' @param 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 \code{NULL}. Baseline
#'   covariates to adjust the plotted effect model for, matching the
#'   adjustment used during search/estimation.  When \code{NULL}, resolved
#'   from \code{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 \code{fs.est$df.est}.
#' @param sg0_name Character. Label for H subgroup (treat.recommend == 0).
#'   Default: \code{"Questionable"}.
#' @param sg1_name Character. Label for Hc subgroup (treat.recommend == 1).
#'   Default: \code{"Recommend"}.
#' @param E.name Character. Label for experimental/treatment arm.
#'   Default: \code{"Treatment"}.
#' @param C.name Character. Label for control arm.
#'   Default: \code{"Control"}.
#' @param bar_colors Character vector of length 2. Colors for control and
#'   treatment bars.  Default: \code{c("steelblue", "coral")}.
#' @param show_effect Logical. Annotate with effect estimate.  Default
#'   \code{TRUE}.
#' @param show_bc Logical. Annotate with bias-corrected estimate when
#'   \code{fs_bc} is provided.  Default \code{TRUE}.
#' @param show_itt Logical. Include an ITT (full population) panel.
#'   Default \code{TRUE}.
#' @param conf.level Numeric. Confidence level for intervals.
#'   Default \code{0.95}.
#' @param title Character or \code{NULL}. Plot title.
#' @param subtitle Character or \code{NULL}. Plot subtitle.
#' @param verbose Logical. Print diagnostic messages. Default \code{FALSE}.
#'
#' @return A list of class \code{"fs_binary_plot"} containing:
#'   \describe{
#'     \item{plot}{A ggplot2 object.}
#'     \item{data}{Data frame of per-arm summaries used for the plot.}
#'     \item{effects}{Data frame of effect estimates per subgroup.}
#'     \item{sg_definition}{Character. Subgroup definition label.}
#'     \item{figure_note}{Character. Auto-generated figure note.}
#'   }
#'
#' @examples
#' \dontrun{
#' fs <- forestsearch(df, outcome_type = "binary", effect_measure = "OR",
#'                    ...)
#' result <- plot_sg_glm_outcomes(fs, outcome.name = "status",
#'                                 treat.name = "hormon")
#' print(result)
#' }
#'
#' @importFrom ggplot2 ggplot aes geom_col geom_point geom_segment geom_text geom_hline labs theme theme_minimal element_text element_blank scale_fill_manual scale_colour_manual coord_cartesian facet_wrap position_dodge
#' @export
plot_sg_glm_outcomes <- function(
    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
) {

  # ===========================================================================
  # SECTION 1: INPUT VALIDATION AND AUTO-DETECTION
  # ===========================================================================

  if (!requireNamespace("ggplot2", quietly = TRUE)) {
    stop("Package 'ggplot2' is required.", call. = FALSE)
  }

  # Avoid R CMD check NOTE for ggplot2 NSE variables
  Arm <- effect_label <- bc_label <- NULL

  if (is.null(fs.est) || is.null(fs.est$df.est)) {
    stop("fs.est must contain a non-empty df.est data frame.", call. = FALSE)
  }

  df <- fs.est$df.est

  # Auto-detect outcome_type first -- reject survival before other checks
  if (is.null(outcome_type)) {
    outcome_type <- fs.est$outcome_type
  }
  if (is.null(outcome_type) || outcome_type == "survival") {
    stop("plot_sg_glm_outcomes is for binary/continuous outcomes. ",
         "Use plot_sg_weighted_km for survival.", call. = FALSE)
  }

  if (!"treat.recommend" %in% names(df)) {
    stop("df.est must contain a 'treat.recommend' column.", call. = FALSE)
  }

  # Auto-detect remaining parameters
  if (is.null(effect_measure)) {
    effect_measure <- fs.est$effect_measure
  }
  if (is.null(effect_measure)) {
    effect_measure <- switch(outcome_type,
      binary = "RD", continuous = "MD", count = "IRR")
  }

  if (is.null(offset.name) && !is.null(fs.est$args_call_all$offset.name)) {
    offset.name <- fs.est$args_call_all$offset.name
  }

  # Adjustment terms: use the same covariates the search/estimate used, so the
  # plotted effect matches the (adjusted) estimate.  Resolved from the call
  # record unless the caller overrides explicitly.
  if (is.null(adjust_covariates) &&
      !is.null(fs.est$args_call_all$adjust_covariates)) {
    adjust_covariates <- fs.est$args_call_all$adjust_covariates
  }

  # Orientation: the fit's resolved adverse_outcome, so the annotated effect
  # is the fit's own estimate, sign included.  NULL only on an object not
  # built by forestsearch(); resolved by forestsearch()'s rule.
  adverse_outcome <- fs.est$args_call_all$adverse_outcome
  if (is.null(adverse_outcome)) {
    adverse_outcome <- outcome_type %in% c("binary", "count")
  }

  is_log_scale <- effect_measure %in% c("OR", "RR", "IRR")
  z_alpha <- qnorm(1 - (1 - conf.level) / 2)

  # Subgroup definition label
  sg_definition <- if (!is.null(fs.est$sg.harm)) {
    paste(fs.est$sg.harm, collapse = " & ")
  } else {
    "Identified subgroup"
  }

  # ===========================================================================
  # SECTION 2: BUILD PER-ARM SUMMARIES
  # ===========================================================================

  # Split data into subgroups
  df_H  <- df[df$treat.recommend == 0, ]   # H: questionable
  df_Hc <- df[df$treat.recommend == 1, ]   # Hc: recommend

  build_arm_summary <- function(dfa, sg_label) {
    Y <- dfa[[outcome.name]]
    Treat <- dfa[[treat.name]]

    if (outcome_type == "binary") {
      # Event rates per arm
      rate_c <- mean(Y[Treat == 0], na.rm = TRUE)
      rate_t <- mean(Y[Treat == 1], na.rm = TRUE)
      n_c <- sum(Treat == 0)
      n_t <- sum(Treat == 1)
      # Wilson CI for proportions
      se_c <- sqrt(rate_c * (1 - rate_c) / n_c)
      se_t <- sqrt(rate_t * (1 - rate_t) / n_t)
      y_label <- "Event Rate"
    } else if (outcome_type == "count" && !is.null(offset.name)) {
      # Incidence rates per person-time
      PT <- dfa[[offset.name]]
      n_c <- sum(Treat == 0)
      n_t <- sum(Treat == 1)
      rate_c <- sum(Y[Treat == 0], na.rm = TRUE) / sum(PT[Treat == 0], na.rm = TRUE)
      rate_t <- sum(Y[Treat == 1], na.rm = TRUE) / sum(PT[Treat == 1], na.rm = TRUE)
      # Poisson-based SE for rates: sqrt(events) / person_time
      se_c <- sqrt(sum(Y[Treat == 0], na.rm = TRUE)) / sum(PT[Treat == 0], na.rm = TRUE)
      se_t <- sqrt(sum(Y[Treat == 1], na.rm = TRUE)) / sum(PT[Treat == 1], na.rm = TRUE)
      y_label <- "Event Rate (per person-year)"
    } else {
      # Means per arm
      rate_c <- mean(Y[Treat == 0], na.rm = TRUE)
      rate_t <- mean(Y[Treat == 1], na.rm = TRUE)
      n_c <- sum(Treat == 0)
      n_t <- sum(Treat == 1)
      se_c <- sd(Y[Treat == 0], na.rm = TRUE) / sqrt(n_c)
      se_t <- sd(Y[Treat == 1], na.rm = TRUE) / sqrt(n_t)
      y_label <- "Mean"
    }

    data.frame(
      Subgroup = sg_label,
      Arm = c(C.name, E.name),
      y = c(rate_c, rate_t),
      se = c(se_c, se_t),
      lo = c(rate_c - z_alpha * se_c, rate_t - z_alpha * se_t),
      hi = c(rate_c + z_alpha * se_c, rate_t + z_alpha * se_t),
      n = c(n_c, n_t),
      stringsAsFactors = FALSE
    )
  }

  # Build summaries
  summ_list <- list(
    build_arm_summary(df_H, sg0_name),
    build_arm_summary(df_Hc, sg1_name)
  )
  if (show_itt) {
    summ_list <- c(list(build_arm_summary(df, "ITT")), summ_list)
  }
  summ_df <- do.call(rbind, summ_list)

  # Order subgroups for display
  sg_levels <- if (show_itt) c("ITT", sg0_name, sg1_name) else c(sg0_name, sg1_name)
  summ_df$Subgroup <- factor(summ_df$Subgroup, levels = sg_levels)
  summ_df$Arm <- factor(summ_df$Arm, levels = c(C.name, E.name))

  # ===========================================================================
  # SECTION 3: COMPUTE EFFECT ESTIMATES
  # ===========================================================================

  effects_df <- NULL

  if (show_effect) {
    fn <- make_effect_estimator(
      outcome_type = outcome_type,
      treat.name = treat.name,
      outcome.name = outcome.name,
      offset.name = offset.name,
      effect_measure = effect_measure,
      adverse_outcome = adverse_outcome,
      adjust_covariates = adjust_covariates,
      ps_adjust_method = "none"
    )

    compute_effect <- function(dfa, sg_label) {
      res <- tryCatch(fn(dfa), error = function(e) NULL)
      if (is.null(res) || is.na(res$estimate)) return(NULL)

      est <- res$estimate
      se  <- res$se

      if (is_log_scale) {
        est_disp <- exp(est)
        lo_disp  <- exp(est - z_alpha * se)
        hi_disp  <- exp(est + z_alpha * se)
        label <- sprintf("%s = %.2f (%.2f, %.2f)",
                         effect_measure, est_disp, lo_disp, hi_disp)
      } else {
        lo_disp <- est - z_alpha * se
        hi_disp <- est + z_alpha * se
        label <- sprintf("%s = %.3f (%.3f, %.3f)",
                         effect_measure, est, lo_disp, hi_disp)
      }

      data.frame(
        Subgroup = sg_label,
        effect_label = label,
        stringsAsFactors = FALSE
      )
    }

    eff_list <- list(
      compute_effect(df_H, sg0_name),
      compute_effect(df_Hc, sg1_name)
    )
    if (show_itt) {
      eff_list <- c(list(compute_effect(df, "ITT")), eff_list)
    }
    effects_df <- do.call(rbind, Filter(Negate(is.null), eff_list))

    if (!is.null(effects_df)) {
      effects_df$Subgroup <- factor(effects_df$Subgroup, levels = sg_levels)
    }
  }

  # ===========================================================================
  # SECTION 4: BIAS-CORRECTED ANNOTATIONS
  # ===========================================================================

  bc_df <- NULL

  if (show_bc && !is.null(fs_bc)) {
    H_bc  <- fs_bc$H_estimates
    Hc_bc <- fs_bc$Hc_estimates

    build_bc_label <- function(bc_est, sg_label) {
      if (is.null(bc_est)) return(NULL)
      hr_bc <- bc_est$H2
      hr_lo <- bc_est$H2_lower
      hr_hi <- bc_est$H2_upper
      if (is.na(hr_bc)) return(NULL)

      label <- sprintf("%s(bc) = %.2f (%.2f, %.2f)",
                       effect_measure, hr_bc, hr_lo, hr_hi)
      data.frame(Subgroup = sg_label, bc_label = label,
                 stringsAsFactors = FALSE)
    }

    bc_list <- list(
      build_bc_label(H_bc, sg0_name),
      build_bc_label(Hc_bc, sg1_name)
    )
    bc_df <- do.call(rbind, Filter(Negate(is.null), bc_list))

    if (!is.null(bc_df)) {
      bc_df$Subgroup <- factor(bc_df$Subgroup, levels = sg_levels)
    }
  }

  # ===========================================================================
  # SECTION 5: BUILD GGPLOT
  # ===========================================================================

  y_label <- switch(outcome_type,
    binary = "Event Rate",
    count  = "Event Rate (per person-year)",
    "Mean Outcome"
  )

  if (is.null(title)) {
    title <- paste0("Subgroup Outcomes: ", sg_definition)
  }
  if (is.null(subtitle)) {
    subtitle <- paste0(
      effect_measure, " | ",
      outcome_type, " outcome | N = ", nrow(df)
    )
  }

  dodge_width <- 0.7

  if (outcome_type %in% c("binary", "count")) {
    # Grouped bar chart for event rates
    p <- ggplot2::ggplot(
      summ_df,
      ggplot2::aes(x = Subgroup, y = y, fill = Arm)
    ) +
      ggplot2::geom_col(
        position = ggplot2::position_dodge(width = dodge_width),
        width = 0.6, colour = "grey30", linewidth = 0.3
      ) +
      ggplot2::geom_errorbar(
        ggplot2::aes(ymin = pmax(lo, 0), ymax = hi),
        position = ggplot2::position_dodge(width = dodge_width),
        width = 0.15, linewidth = 0.5
      ) +
      # N labels above bars
      ggplot2::geom_text(
        ggplot2::aes(
          y = hi + 0.02 * max(summ_df$hi, na.rm = TRUE),
          label = paste0("n=", n)
        ),
        position = ggplot2::position_dodge(width = dodge_width),
        size = 3, vjust = 0
      ) +
      ggplot2::coord_cartesian(ylim = c(0, min(1, max(summ_df$hi, na.rm = TRUE) + 0.10)))

  } else {
    # Point-and-errorbar chart for continuous means
    p <- ggplot2::ggplot(
      summ_df,
      ggplot2::aes(x = Subgroup, y = y, colour = Arm)
    ) +
      ggplot2::geom_point(
        position = ggplot2::position_dodge(width = dodge_width),
        size = 3
      ) +
      ggplot2::geom_errorbar(
        ggplot2::aes(ymin = lo, ymax = hi),
        position = ggplot2::position_dodge(width = dodge_width),
        width = 0.2, linewidth = 0.6
      ) +
      # N labels
      ggplot2::geom_text(
        ggplot2::aes(
          y = hi + (max(summ_df$hi) - min(summ_df$lo)) * 0.03,
          label = paste0("n=", n)
        ),
        position = ggplot2::position_dodge(width = dodge_width),
        size = 3, vjust = 0
      )
  }

  # Common aesthetics
  p <- p +
    ggplot2::scale_fill_manual(
      values = stats::setNames(bar_colors, c(C.name, E.name)),
      name = NULL
    ) +
    ggplot2::scale_colour_manual(
      values = stats::setNames(bar_colors, c(C.name, E.name)),
      name = NULL
    ) +
    ggplot2::labs(
      title = title,
      subtitle = subtitle,
      x = NULL,
      y = y_label
    ) +
    ggplot2::theme_minimal(base_size = 12) +
    ggplot2::theme(
      plot.title = ggplot2::element_text(face = "bold", size = 13),
      plot.subtitle = ggplot2::element_text(size = 10, colour = "grey40"),
      axis.text.x = ggplot2::element_text(face = "bold", size = 11),
      legend.position = "top",
      panel.grid.major.x = ggplot2::element_blank()
    )

  # ===========================================================================
  # SECTION 6: ADD EFFECT ESTIMATE ANNOTATIONS
  # ===========================================================================

  if (!is.null(effects_df) && nrow(effects_df) > 0) {
    # Compute y position for annotation (below bars)
    if (outcome_type %in% c("binary", "count")) {
      annot_y <- -0.06 * max(summ_df$hi, na.rm = TRUE)
    } else {
      y_range <- max(summ_df$hi, na.rm = TRUE) - min(summ_df$lo, na.rm = TRUE)
      annot_y <- min(summ_df$lo, na.rm = TRUE) - y_range * 0.12
    }

    p <- p + ggplot2::geom_text(
      data = effects_df,
      ggplot2::aes(x = Subgroup, y = annot_y, label = effect_label),
      inherit.aes = FALSE,
      size = 3.2, fontface = "italic", colour = "grey20"
    )

    # Add BC annotation below the effect estimate
    if (!is.null(bc_df) && nrow(bc_df) > 0) {
      bc_y <- if (outcome_type %in% c("binary", "count")) {
        annot_y - 0.05 * max(summ_df$hi, na.rm = TRUE)
      } else {
        annot_y - y_range * 0.08
      }

      p <- p + ggplot2::geom_text(
        data = bc_df,
        ggplot2::aes(x = Subgroup, y = bc_y, label = bc_label),
        inherit.aes = FALSE,
        size = 3.0, fontface = "bold.italic", colour = "darkblue"
      )
    }

    # Extend y-axis to accommodate annotations
    if (outcome_type %in% c("binary", "count")) {
      bottom <- if (!is.null(bc_df)) annot_y - 0.08 * max(summ_df$hi, na.rm = TRUE) else annot_y - 0.04 * max(summ_df$hi, na.rm = TRUE)
      y_top <- max(summ_df$hi, na.rm = TRUE) * 1.15
      if (outcome_type == "binary") y_top <- min(1, y_top)
      p <- p + ggplot2::coord_cartesian(
        ylim = c(bottom, y_top),
        clip = "off"
      )
    }
  }

  # ===========================================================================
  # SECTION 7: FIGURE NOTE
  # ===========================================================================

  note_parts <- character(0)
  note_parts <- c(note_parts,
    paste0("Identified subgroup (H): ", sg_definition, "."))

  if (outcome_type %in% c("binary", "count")) {
    note_parts <- c(note_parts,
      "Bars show event rates per arm; error bars show 95 percent CI.")
  } else {
    note_parts <- c(note_parts,
      "Points show arm means; error bars show +/- 1.96 SE.")
  }

  if (!is.null(bc_df) && nrow(bc_df) > 0) {
    note_parts <- c(note_parts,
      paste0(effect_measure, "(bc) = bootstrap bias-corrected estimate."))
  }

  figure_note <- paste(note_parts, collapse = " ")

  if (verbose) {
    cat("Figure note:", figure_note, "\n")
  }

  # ===========================================================================
  # SECTION 8: RETURN
  # ===========================================================================

  result <- list(
    plot = p,
    data = summ_df,
    effects = effects_df,
    bc = bc_df,
    sg_definition = sg_definition,
    sg0_name = sg0_name,
    sg1_name = sg1_name,
    outcome_type = outcome_type,
    effect_measure = effect_measure,
    figure_note = figure_note
  )

  class(result) <- c("fs_binary_plot", "list")
  return(result)
}


#' @rdname plot_sg_glm_outcomes
#' @param x An fs_binary_plot object.
#' @param ... Additional arguments (unused).
#' @export
print.fs_binary_plot <- function(x, ...) {
  print(x$plot)
  invisible(x)
}

#' @rdname plot_sg_glm_outcomes
#' @export
plot.fs_binary_plot <- function(x, ...) {
  print(x$plot)
  invisible(x)
}

Try the forestsearch package in your browser

Any scripts or data that you put into this service are public.

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