R/oc_analyses.R

Defines functions format_oc_results summarize_single_analysis summarize_simulation_results compute_cde compute_cde_glm compute_aor compute_ahr create_subgroup_indicator compute_dgm_cde get_dgm_hr `%||%`

Documented in compute_ahr compute_aor compute_cde compute_cde_glm compute_dgm_cde create_subgroup_indicator format_oc_results get_dgm_hr summarize_simulation_results summarize_single_analysis

# =============================================================================
# DGM and Simulation Reporting Utilities
# =============================================================================
#
# Utility functions for extracting true effects from DGM objects,
# computing subgroup-level estimands, and formatting operating
# characteristics tables.
#
# These are internal helpers used by:
#   - run_simulation_analysis.R (effect extraction, classification)
#   - simulation_tables.R (build_estimation_table, format_oc_results)
#   - setup_gbsg_dgm.R (compute_dgm_cde)
#   - generate_glm_dgm.R (get_dgm_hr compatibility)
#
# Key functions:
#   - get_dgm_hr()                  DGM effect accessor
#   - compute_dgm_cde()             Causal direct effect from DGM
#   - create_subgroup_indicator()   Build subgroup flag from cut expressions
#   - compute_ahr()                 Average hazard ratio (survival)
#   - compute_cde()                 Causal direct effect (survival)
#   - summarize_simulation_results() Summary table from stacked results
#   - summarize_single_analysis()   Single-analysis summary
#   - format_oc_results()           Operating characteristics gt table
# =============================================================================

# Null-coalescing operator (used by compute_dgm_cde)
`%||%` <- function(a, b) if (!is.null(a)) a else b



# =============================================================================
# Helper Functions
# =============================================================================

#' Extract HR from DGM (Backward Compatible)
#'
#' Extracts hazard ratios from DGM object, supporting both old and new formats.
#' Also supports CDE (controlled direct effect) extraction for Table 5 of
#' Leon et al. (2024) alignment (theta-ddagger).
#'
#' @param dgm DGM object (gbsg_dgm or aft_dgm_flex)
#' @param which Character. Which HR to extract: \code{"hr_H"}, \code{"hr_Hc"},
#'   \code{"ahr_H"}, \code{"ahr_Hc"}, \code{"hr_overall"}, \code{"ahr"},
#'   \code{"cde_H"}, \code{"cde_Hc"}, \code{"cde"}.
#'
#' @return Numeric hazard ratio value
#'
#' @keywords internal
get_dgm_hr <- function(dgm, which = "hr_H") {

  # Try new hazard_ratios list first (aligned format)
  if (!is.null(dgm$hazard_ratios)) {
    hr_list <- dgm$hazard_ratios
    result <- switch(which,
      "hr_H" = hr_list$harm_subgroup,
      "hr_Hc" = hr_list$no_harm_subgroup,
      "ahr_H" = hr_list$AHR_harm,
      "ahr_Hc" = hr_list$AHR_no_harm,
      "hr_overall" = hr_list$overall,
      "ahr" = hr_list$AHR,
      "cde_H" = hr_list$CDE_harm,
      "cde_Hc" = hr_list$CDE_no_harm,
      "cde" = hr_list$CDE,
      NA_real_
    )
    if (!is.null(result) && !is.na(result)) return(result)
  }


  # Fall back to old format (direct properties)
  result <- switch(which,
    "hr_H" = dgm$hr_H_true,
    "hr_Hc" = dgm$hr_Hc_true,
    "ahr_H" = dgm$AHR_H_true,
    "ahr_Hc" = dgm$AHR_Hc_true,
    "hr_overall" = dgm$hr_causal,
    "ahr" = dgm$AHR,
    "cde_H" = dgm$cde_H,
    "cde_Hc" = dgm$cde_Hc,
    "cde" = dgm$CDE,
    NA_real_
  )

  if (is.null(result)) NA_real_ else result
}


#' Compute and Attach CDE Values to a DGM Object
#'
#' Calculates Controlled Direct Effect (CDE) hazard ratios from the
#' super-population potential outcomes (\code{theta_0}, \code{theta_1})
#' and attaches them to the DGM's \code{hazard_ratios} list. This enables
#' automatic CDE detection by \code{\link{build_estimation_table}}.
#'
#' @details
#' The CDE for subgroup S is defined as:
#'
#' \code{CDE(S) = mean(exp(theta_1[S])) / mean(exp(theta_0[S]))}
#'
#' which is the ratio of average hazard contributions on the natural scale.
#' This differs from the AHR (\code{exp(mean(loghr_po))}) due to Jensen's
#' inequality. In the notation of Leon et al. (2024), CDE corresponds to
#' theta-ddagger.
#'
#' The function detects the subgroup indicator column automatically,
#' checking for \code{flag.harm}, \code{flag_harm}, and \code{H} in
#' the super-population data frame.
#'
#' @param dgm A DGM object (e.g., from \code{generate_aft_dgm_flex} or
#'   \code{setup_gbsg_dgm}). The super-population is read from
#'   \code{dgm$df_super_rand} when present (as from \code{setup_gbsg_dgm}),
#'   otherwise from \code{dgm$df_super} (as from
#'   \code{generate_aft_dgm_flex}); it must have columns \code{theta_0} and
#'   \code{theta_1}. If neither data frame is present, or those columns are
#'   missing, the function warns and returns \code{dgm} unchanged.
#' @param harm_col Character. Name of the subgroup indicator column in
#'   that super-population data frame. If \code{NULL} (default), auto-detected
#'   from \code{flag.harm}, \code{flag_harm}, or \code{H}.
#'
#' @return The DGM object with CDE values added to
#'   \code{dgm$hazard_ratios} (\code{CDE}, \code{CDE_harm},
#'   \code{CDE_no_harm}) and to top-level fields (\code{dgm$CDE},
#'   \code{dgm$cde_H}, \code{dgm$cde_Hc}).
#'
#' @examples
#' \dontrun{
#' dgm <- setup_gbsg_dgm(model = "alt", k_inter = 2.0)
#' dgm <- compute_dgm_cde(dgm)
#' dgm$hazard_ratios$CDE_harm   # theta-ddagger(H)
#' dgm$hazard_ratios$CDE         # theta-ddagger overall
#' }
#'
#' @seealso \code{\link{build_estimation_table}}, \code{\link{get_dgm_hr}}
#' @export
compute_dgm_cde <- function(dgm, harm_col = NULL) {

  # Support both gbsg_dgm (df_super_rand) and aft_dgm_flex (df_super)
  df <- dgm$df_super_rand %||% dgm$df_super
  if (is.null(df)) {
    warning("DGM has no df_super_rand or df_super; cannot compute CDE.")
    return(dgm)
  }
  if (!all(c("theta_0", "theta_1") %in% names(df))) {
    warning("df_super_rand lacks theta_0/theta_1; cannot compute CDE.")
    return(dgm)
  }

  # Auto-detect subgroup indicator
  if (is.null(harm_col)) {
    candidates <- c("flag.harm", "flag_harm", "H")
    found <- intersect(candidates, names(df))
    if (length(found) == 0) {
      warning("No subgroup indicator found (tried: flag.harm, flag_harm, H).")
      # Compute overall CDE only
      cde_overall <- mean(exp(df$theta_1)) / mean(exp(df$theta_0))
      dgm$CDE <- cde_overall
      if (is.null(dgm$hazard_ratios)) dgm$hazard_ratios <- list()
      dgm$hazard_ratios$CDE <- cde_overall
      return(dgm)
    }
    harm_col <- found[1]
  }

  in_H <- df[[harm_col]] == 1

  # CDE(S) = mean(exp(theta_1[S])) / mean(exp(theta_0[S]))
  cde_H  <- mean(exp(df$theta_1[in_H]))  / mean(exp(df$theta_0[in_H]))
  cde_Hc <- mean(exp(df$theta_1[!in_H])) / mean(exp(df$theta_0[!in_H]))
  cde_overall <- mean(exp(df$theta_1))    / mean(exp(df$theta_0))

  # Attach to hazard_ratios list (for get_dgm_hr auto-detection)
  if (is.null(dgm$hazard_ratios)) dgm$hazard_ratios <- list()
  dgm$hazard_ratios$CDE         <- cde_overall
  dgm$hazard_ratios$CDE_harm    <- cde_H
  dgm$hazard_ratios$CDE_no_harm <- cde_Hc

  # Also attach as top-level fields (for old-format fallback)
  dgm$CDE    <- cde_overall
  dgm$cde_H  <- cde_H
  dgm$cde_Hc <- cde_Hc

  dgm
}


#' Create Subgroup Indicator from Factor Definitions
#'
#' Parses factor definitions (e.g., "v1.1", "grade3.1") and creates
#' a binary indicator for subgroup membership.
#'
#' @param df Data frame containing the variables
#' @param sg_factors Character vector of factor definitions
#'
#' @return Integer vector (1 = in subgroup, 0 = not in subgroup)
#'
#' @keywords internal
create_subgroup_indicator <- function(df, sg_factors) {
  indicator <- rep(TRUE, nrow(df))

  for (factor_def in sg_factors) {
    if (is.na(factor_def) || factor_def == "") next

    parts <- strsplit(factor_def, "\\.")[[1]]
    if (length(parts) >= 2) {
      var_name <- parts[1]
      level <- parts[2]

      if (var_name %in% names(df)) {
        indicator <- indicator & (as.character(df[[var_name]]) == level)
      }
    }
  }

  as.integer(indicator)
}


#' Compute AHR from loghr_po
#'
#' Computes Average Hazard Ratio from individual log hazard ratios.
#'
#' @param df Data frame with loghr_po column
#' @param subset_indicator Optional logical/integer vector for subsetting
#'
#' @return Numeric AHR value
#'
#' @keywords internal
compute_ahr <- function(df, subset_indicator = NULL) {
  if (!"loghr_po" %in% names(df)) {
    return(NA_real_)
  }

  loghr <- df$loghr_po

  if (!is.null(subset_indicator)) {
    loghr <- loghr[subset_indicator == 1]
  }

  if (length(loghr) == 0 || all(is.na(loghr))) {
    return(NA_real_)
  }

  exp(mean(loghr, na.rm = TRUE))
}


#' Compute Marginal Causal Effect from GLM Potential Outcomes
#'
#' Computes the marginal (average) treatment effect from individual-level
#' potential outcomes stored in GLM simulation data.
#' This is the GLM analogue of \code{\link{compute_ahr}} for survival data.
#'
#' For binary outcomes (\code{p0}, \code{p1}):
#' \itemize{
#'   \item \code{OR}: \code{odds(mean(p1)) / odds(mean(p0))}
#'   \item \code{RD}: \code{mean(p1) - mean(p0)}
#'   \item \code{RR}: \code{mean(p1) / mean(p0)}
#' }
#'
#' For continuous or count outcomes (\code{mu0}, \code{mu1}):
#' \itemize{
#'   \item \code{MD}: \code{mean(mu1) - mean(mu0)}
#'   \item \code{IRR}: \code{mean(mu1) / mean(mu0)}
#'   \item \code{IRD}: \code{mean(mu1) - mean(mu0)}
#' }
#'
#' @param df Data frame with potential outcome columns (\code{p0}/\code{p1}
#'   or \code{mu0}/\code{mu1}).
#' @param subset_indicator Optional logical/integer vector for subsetting.
#'   If provided, only rows where \code{subset_indicator == 1} are used.
#' @param effect_measure Character.  One of \code{"OR"}, \code{"RD"},
#'   \code{"RR"}, \code{"MD"}, \code{"IRR"}, \code{"IRD"}.
#'   Default \code{"OR"}.
#'
#' @return Numeric effect value, or \code{NA_real_} if required columns
#'   are missing.
#'
#' @keywords internal
#' @export
compute_aor <- function(df, subset_indicator = NULL,
                        effect_measure = "OR") {

  has_binary <- all(c("p0", "p1") %in% names(df))
  has_cont   <- all(c("mu0", "mu1") %in% names(df))

  if (!has_binary && !has_cont) return(NA_real_)

  if (has_binary) {
    y0 <- df$p0
    y1 <- df$p1
  } else {
    y0 <- df$mu0
    y1 <- df$mu1
  }

  if (!is.null(subset_indicator)) {
    idx <- subset_indicator == 1
    y0 <- y0[idx]
    y1 <- y1[idx]
  }

  if (length(y0) == 0 || all(is.na(y0))) return(NA_real_)

  m0 <- mean(y0, na.rm = TRUE)
  m1 <- mean(y1, na.rm = TRUE)

  switch(effect_measure,
    "OR" = (m1 / (1 - m1)) / (m0 / (1 - m0)),
    "RD" = , "IRD" = , "MD" = m1 - m0,
    "RR" = , "IRR" = m1 / m0,
    NA_real_
  )
}


#' Compute CDE Analogue from GLM Potential Outcomes
#'
#' Computes the Controlled Direct Effect analogue for GLM outcomes.
#' For binary (logit link), this averages the individual-level odds
#' first, then takes the ratio --- analogous to
#' \code{mean(exp(theta_1)) / mean(exp(theta_0))} in survival:
#'
#' \code{CDE(S) = mean(p1[S]/(1-p1[S])) / mean(p0[S]/(1-p0[S]))}
#'
#' This differs from the AOR (\code{odds(mean(p1)) / odds(mean(p0))})
#' due to Jensen's inequality whenever individual probabilities are
#' heterogeneous.  For identity-link (MD) and log-link (IRR) outcomes,
#' CDE equals AOR and this function returns \code{NA_real_}.
#'
#' @inheritParams compute_aor
#'
#' @return Numeric CDE value (binary OR only), or \code{NA_real_}.
#'
#' @keywords internal
#' @export
compute_cde_glm <- function(df, subset_indicator = NULL,
                            effect_measure = "OR") {

  # Only meaningful for binary (logit link)
  if (!all(c("p0", "p1") %in% names(df))) return(NA_real_)
  if (!(effect_measure %in% c("OR"))) return(NA_real_)

  p0 <- df$p0
  p1 <- df$p1

  if (!is.null(subset_indicator)) {
    idx <- subset_indicator == 1
    p0 <- p0[idx]
    p1 <- p1[idx]
  }

  if (length(p0) == 0 || all(is.na(p0))) return(NA_real_)

  # Individual odds, then average
  odds0 <- p0 / (1 - p0)
  odds1 <- p1 / (1 - p1)

  mean(odds1, na.rm = TRUE) / mean(odds0, na.rm = TRUE)
}


#' Compute CDE from theta_0 and theta_1
#'
#' Computes Controlled Direct Effect as the ratio of average hazard
#' contributions on the natural scale:
#' \code{CDE(S) = mean(exp(theta_1[S])) / mean(exp(theta_0[S]))}.
#'
#' @param df Data frame with \code{theta_0} and \code{theta_1} columns.
#' @param subset_indicator Optional logical/integer vector for subsetting.
#'   If provided, only rows where \code{subset_indicator == 1} are used.
#'
#' @return Numeric CDE value, or \code{NA_real_} if columns are missing.
#'
#' @keywords internal
compute_cde <- function(df, subset_indicator = NULL) {
  if (!all(c("theta_0", "theta_1") %in% names(df))) {
    return(NA_real_)
  }

  t0 <- df$theta_0
  t1 <- df$theta_1

  if (!is.null(subset_indicator)) {
    idx <- subset_indicator == 1
    t0 <- t0[idx]
    t1 <- t1[idx]
  }

  if (length(t0) == 0 || all(is.na(t0))) {
    return(NA_real_)
  }

  mean(exp(t1), na.rm = TRUE) / mean(exp(t0), na.rm = TRUE)
}




# =============================================================================
# Summary Functions
# =============================================================================

#' Summarize Simulation Results
#'
#' Creates a summary table of operating characteristics across all simulations.
#' Includes both HR and AHR metrics.
#'
#' @param results data.table with simulation results from run_simulation_analysis
#' @param analyses Character vector. Analysis methods to include. Default: NULL, meaning all analyses in results
#' @param digits Integer. Decimal places for proportions. Default: 2
#' @param digits_hr Integer. Decimal places for hazard ratios. Default: 3
#'
#' @return Data frame with summary statistics
#'
#' @examples
#' \dontrun{
#' dgm <- setup_gbsg_dgm()
#' # run_simulation_analysis() runs one replicate per call; ten are stacked.
#' # confounders_base names the DGM's numeric candidate covariates, as in the
#' # simulations article (the default v1-v7 columns are factors).
#' sim_res <- data.table::rbindlist(lapply(1:10, function(i)
#'   run_simulation_analysis(sim_id = i, dgm = dgm, n_sample = 500,
#'     confounders_base = c("z1", "z2", "z3", "z4", "z5", "size", "grade3"))),
#'   fill = TRUE)
#' summarize_simulation_results(sim_res)
#' }
#' @export
summarize_simulation_results <- function(
    results,
    analyses = NULL,
    digits = 2,
    digits_hr = 3
) {

  if (is.null(analyses)) {
    analyses <- unique(results$analysis)
  }

  summaries <- lapply(analyses, function(a) {
    res <- subset(results, analysis == a)
    summarize_single_analysis(res, digits = digits, digits_hr = digits_hr)
  })

  summary_df <- do.call(cbind, summaries)
  colnames(summary_df) <- analyses

  summary_df
}


#' Summarize Single Analysis Results
#'
#' @param result data.table with results for a single analysis method
#' @param digits Integer. Decimal places for proportions
#' @param digits_hr Integer. Decimal places for hazard ratios
#'
#' @return Data frame with summary statistics
#'
#' @keywords internal
summarize_single_analysis <- function(result, digits = 2, digits_hr = 3) {

  # ---------------------------------------------------------------------------
  # Classification metrics (all replicates)
  # ---------------------------------------------------------------------------
  class_cols <- c("any.H", "sens", "spec", "ppv", "npv")
  class_cols <- intersect(class_cols, names(result))
  class_means <- sapply(result[, class_cols, with = FALSE], mean, na.rm = TRUE)
  class_means <- round(class_means, digits)

  # ---------------------------------------------------------------------------
  # Subgroup sizes (H: conditional on detection; Hc: all replicates)
  # ---------------------------------------------------------------------------
  res_found <- subset(result, any.H == 1)

  if (nrow(res_found) > 0) {
    avg_H <- round(mean(res_found$size.H, na.rm = TRUE), 0)
    min_H <- round(min(res_found$size.H, na.rm = TRUE), 0)
    max_H <- round(max(res_found$size.H, na.rm = TRUE), 0)
  } else {
    avg_H <- min_H <- max_H <- NA
  }

  avg_Hc <- round(mean(result$size.Hc, na.rm = TRUE), 0)
  min_Hc <- round(min(result$size.Hc, na.rm = TRUE), 0)
  max_Hc <- round(max(result$size.Hc, na.rm = TRUE), 0)

  # ---------------------------------------------------------------------------
  # HR and AHR estimates (conditional on detection)
  # ---------------------------------------------------------------------------
  if (nrow(res_found) > 0) {
    # Cox-based HRs
    hr_H_true <- round(mean(res_found$hr.H.true, na.rm = TRUE), digits_hr)
    hr_H_hat <- round(mean(res_found$hr.H.hat, na.rm = TRUE), digits_hr)
    hr_Hc_true <- round(mean(res_found$hr.Hc.true, na.rm = TRUE), digits_hr)
    hr_Hc_hat <- round(mean(res_found$hr.Hc.hat, na.rm = TRUE), digits_hr)

    # AHR estimates (true subgroup and identified subgroup)
    ahr_H_true <- if ("ahr.H.true" %in% names(res_found)) {
      round(mean(res_found$ahr.H.true, na.rm = TRUE), digits_hr)
    } else NA
    ahr_Hc_true <- if ("ahr.Hc.true" %in% names(res_found)) {
      round(mean(res_found$ahr.Hc.true, na.rm = TRUE), digits_hr)
    } else NA
    ahr_H_hat <- if ("ahr.H.hat" %in% names(res_found)) {
      round(mean(res_found$ahr.H.hat, na.rm = TRUE), digits_hr)
    } else NA
    ahr_Hc_hat <- if ("ahr.Hc.hat" %in% names(res_found)) {
      round(mean(res_found$ahr.Hc.hat, na.rm = TRUE), digits_hr)
    } else NA
  } else {
    hr_H_true <- hr_H_hat <- hr_Hc_true <- hr_Hc_hat <- NA
    ahr_H_true <- ahr_Hc_true <- ahr_H_hat <- ahr_Hc_hat <- NA
  }

  # ---------------------------------------------------------------------------
  # Unconditional estimates (all replicates)
  # ---------------------------------------------------------------------------
  hr_H_true_all <- round(mean(result$hr.H.true, na.rm = TRUE), digits_hr)
  hr_Hc_true_all <- round(mean(result$hr.Hc.true, na.rm = TRUE), digits_hr)
  hr_itt <- round(mean(result$hr.itt, na.rm = TRUE), digits_hr)
  hr_adj_itt <- if ("hr.adj.itt" %in% names(result)) {
    round(mean(result$hr.adj.itt, na.rm = TRUE), digits_hr)
  } else NA

  # AHR unconditional (all replicates)
  ahr_H_true_all <- if ("ahr.H.true" %in% names(result)) {
    round(mean(result$ahr.H.true, na.rm = TRUE), digits_hr)
  } else NA
  ahr_Hc_true_all <- if ("ahr.Hc.true" %in% names(result)) {
    round(mean(result$ahr.Hc.true, na.rm = TRUE), digits_hr)
  } else NA

  # ---------------------------------------------------------------------------
  # Combine into output data frame
  # ---------------------------------------------------------------------------
  values <- c(
    class_means,
    avg_H, min_H, max_H, avg_Hc, min_Hc, max_Hc,
    hr_H_true, hr_H_hat, hr_Hc_true, hr_Hc_hat,
    hr_H_true_all, hr_Hc_true_all, hr_itt, hr_adj_itt,
    ahr_H_true, ahr_H_hat, ahr_Hc_true, ahr_Hc_hat,
    ahr_H_true_all, ahr_Hc_true_all
  )

  row_names <- c(
    names(class_means),
    "Avg(#H)", "minH", "maxH", "Avg(#Hc)", "minHc", "maxHc",
    "theta-dag(H)", "theta-hat(H-hat)", "theta-dag(Hc)", "theta-hat(Hc-hat)",
    "theta-dag(H)all", "theta-dag(Hc)all", "theta-hat(ITT)", "theta-hat(ITTadj)",
    "ahr-dag(H)", "ahr-hat(H-hat)", "ahr-dag(Hc)", "ahr-hat(Hc-hat)",
    "ahr-dag(H)all", "ahr-dag(Hc)all"
  )

  out <- data.frame(value = values, stringsAsFactors = FALSE)
  rownames(out) <- row_names

  out
}


# =============================================================================
# Format Operating Characteristics Table
# =============================================================================

#' Format Operating Characteristics Results as GT Table
#'
#' Creates a formatted gt table from simulation operating characteristics results.
#'
#' @param results data.table or data.frame. Simulation results from
#'   \code{\link{run_simulation_analysis}} or combined results from multiple simulations.
#' @param analyses Character vector. Analysis methods to include.
#'   Default: NULL (all analyses in results)
#' @param metrics Character vector. Metrics to display. Options include:
#'   "detection", "classification", "hr_estimates", "ahr_estimates",
#'   "cde_estimates", "subgroup_size", "all". Default: "all"
#' @param digits Integer. Decimal places for proportions. Default: 3
#' @param digits_hr Integer. Decimal places for hazard ratios. Default: 3
#' @param title Character. Table title. Default: "Operating Characteristics Summary"
#' @param subtitle Character or \code{NULL}. Table subtitle.  When
#'   \code{NULL} (default) and a \code{dgm} is provided, an informative
#'   subtitle is auto-generated showing the number of simulations and
#'   true effect sizes using notation-aware labels (e.g.,
#'   \code{"100 sims, OR(H) = 2.00, OR(Hc) = 0.65"}).
#' @param use_gt Logical. Return gt table if TRUE, data.frame if FALSE. Default: TRUE
#' @param effect_measure Character or \code{NULL}.  The effect measure
#'   used in the simulation (e.g., \code{"HR"}, \code{"OR"}, \code{"MD"}).
#'   When provided, identity-scale measures (MD, RD, IRD) are negated
#'   rather than reciprocated during benefit-search inversion.  When
#'   \code{NULL} (default), auto-detected from \code{dgm$effect_measure}
#'   if \code{dgm} is provided; otherwise ratio-scale inversion
#'   (\code{1/x}) is used for backward compatibility.
#' @param dgm Optional DGM object (\code{gbsg_dgm}, \code{aft_dgm_flex},
#'   or \code{glm_dgm}).  When provided, \code{effect_measure} is
#'   auto-detected from \code{dgm$effect_measure} (unless explicitly
#'   overridden) and column spanner labels adapt to the outcome type.
#' @param subgroup_notation Character. \code{"harm"} (default) labels
#'   subgroups as H/Hc; \code{"benefit"} labels as G/Gc for
#'   benefit-search analyses (treatment switching).
#'
#' @return A gt table object (if use_gt = TRUE and gt package available) or data.frame
#'
#' @details
#' The function summarizes simulation results across multiple metrics:
#' \itemize{
#'   \item \strong{Found}: Proportion of simulations finding a subgroup (any.H)
#'   \item \strong{Classification}: Sen, spec, PPV, NPV
#'   \item \strong{HR Estimates}: Mean Cox hazard ratios in true (H) and
#'     identified (H-hat) subgroups and their complements
#'   \item \strong{AHR Estimates}: Mean average hazard ratios (from loghr_po)
#'     in true and identified subgroups
#'   \item \strong{CDE Estimates}: Controlled direct effects (from
#'     theta_0/theta_1) in true and identified subgroups
#'   \item \strong{Subgroup Size}: Average, min, max sizes
#' }
#'
#' Column notation aligns with \code{\link{build_estimation_table}} and
#' Leon et al. (2024): \code{H} = true (oracle) subgroup, \code{H-hat} =
#' identified subgroup. The asterisk (\code{*}) is reserved for bootstrap
#' bias-corrected estimates and is not used in this summary table.
#'
#' @importFrom data.table is.data.table as.data.table
#' @examples
#' \dontrun{
#' # format_oc_results() is called by summarize_simulation_results().
#' # See run_simulation_analysis() for the standard entry point.
#' }
#' @export
format_oc_results <- function(
    results,
    analyses = NULL,
    metrics = "all",
    digits = 3,
    digits_hr = 3,
    title = "Operating Characteristics Summary",
    subtitle = NULL,
    use_gt = TRUE,
    effect_measure = NULL,
    dgm = NULL,
    subgroup_notation = c("harm", "benefit")
) {

  subgroup_notation <- match.arg(subgroup_notation)
  L <- get_sg_labels(subgroup_notation)

  # Auto-detect effect_measure from DGM if not explicitly provided
  if (is.null(effect_measure) && !is.null(dgm)) {
    effect_measure <- dgm$effect_measure
  }

  # Auto-generate subtitle from DGM when not explicitly provided
  if (is.null(subtitle) && !is.null(dgm)) {
    n_sims_total <- if (is.data.frame(results)) {
      length(unique(results$sim))
    } else {
      nrow(results)
    }
    em_label <- if (!is.null(effect_measure)) effect_measure else "HR"
    hr_H  <- dgm$hazard_ratios$harm_subgroup
    hr_Hc <- dgm$hazard_ratios$no_harm_subgroup
    subtitle <- sprintf(
      "%d sims, %s(%s) = %.2f, %s(%s) = %.2f",
      n_sims_total, em_label, L$sg, hr_H,
      em_label, L$sg_c, hr_Hc
    )
  }

  # Benefit search: invert effects from switched -> original scale
  if (subgroup_notation == "benefit") {
    results <- invert_hr_columns(results, effect_measure)
  }

  # Convert to data.table if needed
  if (!data.table::is.data.table(results)) {
    results <- data.table::as.data.table(results)
  }

  # Get analyses if not specified
  if (is.null(analyses)) {
    analyses <- unique(results$analysis)
  }

  # Filter to requested analyses
  results <- results[results$analysis %in% analyses, ]

  # Compute summary statistics for each analysis
  summary_list <- lapply(analyses, function(a) {
    res <- results[results$analysis == a, ]
    n_sims <- nrow(res)

    # Detection rate
    detection_rate <- mean(res$any.H, na.rm = TRUE)

    # Classification metrics (averaged over every sim with a stored value: a
    # sim with no subgroup contributes spec = 1 and npv = |Hc|/N as
    # run_simulation_analysis() stores them; NA rows drop out).
    # Under null models (León et al. 2024, Sec 3): Q = emptyset,
    # so sens = NA and ppv = 0.  NaN from mean(all-NA) is replaced
    # with NA for clean table display.
    sens <- mean(res$sens, na.rm = TRUE)
    spec <- mean(res$spec, na.rm = TRUE)
    ppv <- mean(res$ppv, na.rm = TRUE)
    npv <- mean(res$npv, na.rm = TRUE)

    if (is.nan(sens)) sens <- NA
    if (is.nan(spec)) spec <- NA
    if (is.nan(ppv))  ppv  <- NA
    if (is.nan(npv))  npv  <- NA

    # HR estimates (only when subgroup found)
    res_found <- res[res$any.H == 1, ]
    if (nrow(res_found) > 0) {
      hr_H_hat <- mean(res_found$hr.H.hat, na.rm = TRUE)
      hr_Hc_hat <- mean(res_found$hr.Hc.hat, na.rm = TRUE)
      hr_H_true <- mean(res_found$hr.H.true, na.rm = TRUE)
      hr_Hc_true <- mean(res_found$hr.Hc.true, na.rm = TRUE)
      size_H_mean <- mean(res_found$size.H, na.rm = TRUE)
      size_H_min <- min(res_found$size.H, na.rm = TRUE)
      size_H_max <- max(res_found$size.H, na.rm = TRUE)
    } else {
      hr_H_hat <- hr_Hc_hat <- hr_H_true <- hr_Hc_true <- NA
      size_H_mean <- size_H_min <- size_H_max <- NA
    }

    # AHR estimates (conditional on detection)
    if (nrow(res_found) > 0) {
      ahr_H_true <- if ("ahr.H.true" %in% names(res_found)) {
        mean(res_found$ahr.H.true, na.rm = TRUE)
      } else NA
      ahr_Hc_true <- if ("ahr.Hc.true" %in% names(res_found)) {
        mean(res_found$ahr.Hc.true, na.rm = TRUE)
      } else NA
      ahr_H_hat <- if ("ahr.H.hat" %in% names(res_found)) {
        mean(res_found$ahr.H.hat, na.rm = TRUE)
      } else NA
      ahr_Hc_hat <- if ("ahr.Hc.hat" %in% names(res_found)) {
        mean(res_found$ahr.Hc.hat, na.rm = TRUE)
      } else NA
    } else {
      ahr_H_true <- ahr_Hc_true <- ahr_H_hat <- ahr_Hc_hat <- NA
    }

    # CDE estimates (conditional on detection)
    if (nrow(res_found) > 0) {
      cde_H_true <- if ("cde.H.true" %in% names(res_found)) {
        mean(res_found$cde.H.true, na.rm = TRUE)
      } else NA
      cde_Hc_true <- if ("cde.Hc.true" %in% names(res_found)) {
        mean(res_found$cde.Hc.true, na.rm = TRUE)
      } else NA
      cde_H_hat <- if ("cde.H.hat" %in% names(res_found)) {
        mean(res_found$cde.H.hat, na.rm = TRUE)
      } else NA
      cde_Hc_hat <- if ("cde.Hc.hat" %in% names(res_found)) {
        mean(res_found$cde.Hc.hat, na.rm = TRUE)
      } else NA
    } else {
      cde_H_true <- cde_Hc_true <- cde_H_hat <- cde_Hc_hat <- NA
    }

    # ITT estimate (all simulations)
    hr_itt <- mean(res$hr.itt, na.rm = TRUE)

    data.frame(
      Analysis = a,
      N_sims = n_sims,
      Detection = detection_rate,
      Sen = sens,
      Spec = spec,
      PPV = ppv,
      NPV = npv,
      HR_H_hat = hr_H_hat,
      HR_Hc_hat = hr_Hc_hat,
      HR_H_true = hr_H_true,
      HR_Hc_true = hr_Hc_true,
      HR_ITT = hr_itt,
      AHR_H_true = ahr_H_true,
      AHR_Hc_true = ahr_Hc_true,
      AHR_H_hat = ahr_H_hat,
      AHR_Hc_hat = ahr_Hc_hat,
      CDE_H_true = cde_H_true,
      CDE_Hc_true = cde_Hc_true,
      CDE_H_hat = cde_H_hat,
      CDE_Hc_hat = cde_Hc_hat,
      Size_H_mean = size_H_mean,
      Size_H_min = size_H_min,
      Size_H_max = size_H_max,
      stringsAsFactors = FALSE
    )
  })

  summary_df <- do.call(rbind, summary_list)

  # Filter columns based on metrics
  if (!"all" %in% metrics) {
    cols_to_keep <- c("Analysis", "N_sims")
    if ("detection" %in% metrics) {
      cols_to_keep <- c(cols_to_keep, "Detection")
    }
    if ("classification" %in% metrics) {
      cols_to_keep <- c(cols_to_keep, "Sen", "Spec", "PPV", "NPV")
    }
    if ("hr_estimates" %in% metrics) {
      cols_to_keep <- c(cols_to_keep, "HR_H_hat", "HR_Hc_hat",
                        "HR_H_true", "HR_Hc_true", "HR_ITT")
    }
    if ("ahr_estimates" %in% metrics) {
      cols_to_keep <- c(cols_to_keep, "AHR_H_true", "AHR_Hc_true",
                        "AHR_H_hat", "AHR_Hc_hat")
    }
    if ("cde_estimates" %in% metrics) {
      cols_to_keep <- c(cols_to_keep, "CDE_H_true", "CDE_Hc_true",
                        "CDE_H_hat", "CDE_Hc_hat")
    }
    if ("subgroup_size" %in% metrics) {
      cols_to_keep <- c(cols_to_keep, "Size_H_mean", "Size_H_min", "Size_H_max")
    }
    # Only keep columns that exist (AHR may be all-NA and still present)
    cols_to_keep <- intersect(cols_to_keep, names(summary_df))
    summary_df <- summary_df[, cols_to_keep, drop = FALSE]
  }

  # Format as gt table if requested and available
  if (use_gt && requireNamespace("gt", quietly = TRUE)) {
    gt_table <- gt::gt(summary_df)

    # Add title
    gt_table <- gt::tab_header(
      gt_table,
      title = title,
      subtitle = subtitle
    )

    # Proportion columns (0-1 scale)
    prop_cols <- intersect(c("Detection", "Sen", "Spec", "PPV", "NPV"),
                           names(summary_df))
    if (length(prop_cols) > 0) {
      gt_table <- gt::fmt_number(
        gt_table,
        columns = gt::all_of(prop_cols),
        decimals = digits
      )
    }

    # Cox HR columns
    hr_cols <- intersect(c("HR_H_hat", "HR_Hc_hat", "HR_H_true",
                           "HR_Hc_true", "HR_ITT"),
                         names(summary_df))
    if (length(hr_cols) > 0) {
      gt_table <- gt::fmt_number(
        gt_table,
        columns = gt::all_of(hr_cols),
        decimals = digits_hr
      )
    }

    # AHR columns
    ahr_cols <- intersect(c("AHR_H_true", "AHR_Hc_true",
                            "AHR_H_hat", "AHR_Hc_hat"),
                          names(summary_df))
    if (length(ahr_cols) > 0) {
      gt_table <- gt::fmt_number(
        gt_table,
        columns = gt::all_of(ahr_cols),
        decimals = digits_hr
      )
    }

    # CDE columns
    cde_cols <- intersect(c("CDE_H_true", "CDE_Hc_true",
                            "CDE_H_hat", "CDE_Hc_hat"),
                          names(summary_df))
    if (length(cde_cols) > 0) {
      gt_table <- gt::fmt_number(
        gt_table,
        columns = gt::all_of(cde_cols),
        decimals = digits_hr
      )
    }

    # Size columns
    size_cols <- intersect(c("Size_H_mean", "Size_H_min", "Size_H_max"),
                           names(summary_df))
    if (length(size_cols) > 0) {
      gt_table <- gt::fmt_number(
        gt_table,
        columns = gt::all_of(size_cols),
        decimals = 0
      )
    }

    # Rename columns for display using math notation (pure Unicode)
    # Notation-aware: H/Hc for harm search, G/Gc for benefit search
    # Unicode: \u0302 = combining circumflex, \u1D9C = superscript-c,
    #          \u2020 = dagger, \u2021 = double-dagger,
    #          \u03b8 = theta, \u00e2 = a-hat

    label_list <- list(
      Analysis  = "Method",
      N_sims    = "Sims",
      Detection = "Found"
    )

    # HR column labels (conditional on existence)
    hr_label_map <- list(
      HR_H_hat   = sprintf("\u03b8\u0302(%s)", L$sg_hat),
      HR_Hc_hat  = sprintf("\u03b8\u0302(%s)", L$sg_hat_c),
      HR_H_true  = sprintf("\u03b8\u0302(%s)", L$sg),
      HR_Hc_true = sprintf("\u03b8\u0302(%s)", L$sg_c),
      HR_ITT     = "\u03b8\u0302(ITT)"
    )
    for (col_nm in names(hr_label_map)) {
      if (col_nm %in% names(summary_df)) {
        label_list[[col_nm]] <- hr_label_map[[col_nm]]
      }
    }

    # AHR column labels (conditional on existence)
    ahr_label_map <- list(
      AHR_H_true  = sprintf("\u00e2hr(%s)", L$sg),
      AHR_Hc_true = sprintf("\u00e2hr(%s)", L$sg_c),
      AHR_H_hat   = sprintf("\u00e2hr(%s)", L$sg_hat),
      AHR_Hc_hat  = sprintf("\u00e2hr(%s)", L$sg_hat_c)
    )
    for (col_nm in names(ahr_label_map)) {
      if (col_nm %in% names(summary_df)) {
        label_list[[col_nm]] <- ahr_label_map[[col_nm]]
      }
    }

    # CDE column labels (conditional on existence)
    cde_label_map <- list(
      CDE_H_true  = sprintf("\u03b8\u2021(%s)", L$sg),
      CDE_Hc_true = sprintf("\u03b8\u2021(%s)", L$sg_c),
      CDE_H_hat   = sprintf("\u03b8\u2021(%s)", L$sg_hat),
      CDE_Hc_hat  = sprintf("\u03b8\u2021(%s)", L$sg_hat_c)
    )
    for (col_nm in names(cde_label_map)) {
      if (col_nm %in% names(summary_df)) {
        label_list[[col_nm]] <- cde_label_map[[col_nm]]
      }
    }

    # Size column labels (notation-aware: avg|Ĥ| for harm, avg|Ĝ| for benefit)
    size_label_map <- list(
      Size_H_mean = sprintf("avg|%s|", L$sg_hat),
      Size_H_min  = sprintf("min|%s|", L$sg_hat),
      Size_H_max  = sprintf("max|%s|", L$sg_hat)
    )
    for (col_nm in names(size_label_map)) {
      if (col_nm %in% names(summary_df)) {
        label_list[[col_nm]] <- size_label_map[[col_nm]]
      }
    }

    gt_table <- gt::cols_label(gt_table, .list = label_list)

    # Add column spanners
    if ("all" %in% metrics || "classification" %in% metrics) {
      class_cols <- intersect(c("Sen", "Spec", "PPV", "NPV"), names(summary_df))
      if (length(class_cols) > 0) {
        gt_table <- gt::tab_spanner(
          gt_table,
          label = "Classification",
          columns = gt::all_of(class_cols)
        )
      }
    }

    if ("all" %in% metrics || "hr_estimates" %in% metrics) {
      hr_span_cols <- intersect(c("HR_H_hat", "HR_Hc_hat", "HR_H_true",
                                  "HR_Hc_true", "HR_ITT"),
                                names(summary_df))
      if (length(hr_span_cols) > 0) {
        hr_label <- if (!is.null(effect_measure) &&
                        is_identity_scale(effect_measure)) {
          effect_measure
        } else if (!is.null(effect_measure) &&
                   effect_measure %in% c("OR", "RR", "IRR")) {
          paste0("GLM ", effect_measure)
        } else {
          "Cox Hazard Ratios"
        }
        gt_table <- gt::tab_spanner(
          gt_table,
          label = hr_label,
          columns = gt::all_of(hr_span_cols)
        )
      }
    }

    if ("all" %in% metrics || "ahr_estimates" %in% metrics) {
      ahr_span_cols <- intersect(c("AHR_H_true", "AHR_Hc_true",
                                   "AHR_H_hat", "AHR_Hc_hat"),
                                 names(summary_df))
      if (length(ahr_span_cols) > 0) {
        gt_table <- gt::tab_spanner(
          gt_table,
          label = "Average Hazard Ratios",
          columns = gt::all_of(ahr_span_cols)
        )
      }
    }

    if ("all" %in% metrics || "cde_estimates" %in% metrics) {
      cde_span_cols <- intersect(c("CDE_H_true", "CDE_Hc_true",
                                   "CDE_H_hat", "CDE_Hc_hat"),
                                 names(summary_df))
      if (length(cde_span_cols) > 0) {
        gt_table <- gt::tab_spanner(
          gt_table,
          label = "Controlled Direct Effects",
          columns = gt::all_of(cde_span_cols)
        )
      }
    }

    if ("all" %in% metrics || "subgroup_size" %in% metrics) {
      size_span_cols <- intersect(c("Size_H_mean", "Size_H_min", "Size_H_max"),
                                  names(summary_df))
      if (length(size_span_cols) > 0) {
        gt_table <- gt::tab_spanner(
          gt_table,
          label = sprintf("Identified %s Subgroup Size",
                          tools::toTitleCase(L$word)),
          columns = gt::all_of(size_span_cols)
        )
      }
    }

    # Style
    gt_table <- gt::tab_style(
      gt_table,
      style = gt::cell_text(weight = "bold"),
      locations = gt::cells_column_labels()
    )

    # Handle missing values
    if (utils::packageVersion("gt") >= "0.6.0") {
      gt_table <- gt::sub_missing(
        gt_table,
        columns = gt::everything(),
        missing_text = "-"
      )
    }

    return(gt_table)
  }

  # Return data.frame if gt not available or not requested
  summary_df
}

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.