R/simulate_from_dgm.R

Defines functions .entry_delay_vector calibrate_cens_adjust check_censoring_dgm simulate_from_dgm

Documented in calibrate_cens_adjust check_censoring_dgm simulate_from_dgm

# =============================================================================
# simulate_from_dgm() — revised
# Fixes:
#   1. follow_up scoping: was defined only inside else-branch but used
#      unconditionally after it.  n = NULL path now initialises follow_up
#      as rep(Inf, n) (no administrative censoring) and treat_sim from treat.
#   2. treat_sim scoping: was also undefined in the n = NULL path.
#
# New function:
#   check_censoring_dgm() — diagnostic comparing observed censoring in the
#   DGM source data against censoring generated by simulate_from_dgm().
# =============================================================================


#' Simulate Survival Data from AFT Data Generating Mechanism
#'
#' Generates simulated survival data from a previously created AFT data
#' generating mechanism (DGM). Samples from the super population and generates
#' survival times with specified censoring.
#'
#' @param dgm An object of class \code{"aft_dgm_flex"} created by
#'   \code{\link{generate_aft_dgm_flex}}.
#' @param n Integer specifying the sample size. If \code{NULL} (default),
#'   uses the entire super population without sampling.
#' @param rand_ratio Numeric randomisation ratio (treatment:control).
#'   Default \code{1} (1:1 allocation).
#' @param entry_var Character string naming an entry-time variable in the
#'   super population. If \code{NULL}, entry times are drawn as
#'   \code{Uniform(0, max_entry)}. Default \code{NULL}. When supplied it
#'   takes precedence over \code{entry_delay}, which is then ignored.
#'   (\code{\link{mrct_region_sims}} sets \code{entry_var = "entrytime"}
#'   whenever \code{dgm$df_super} has a column \code{entrytime}: one fixed
#'   entry time per super-population row, carried with the row into every
#'   trial that samples it.)
#' @param max_entry Numeric maximum entry time for staggered entry simulation.
#'   Only used when \code{entry_var = NULL}. Default \code{24}.
#' @param entry_delay \code{NULL} (default: every patient enters at
#'   \code{Uniform(0, max_entry)}), or a per-patient delay added to that
#'   entry time, in the DGM's time units. Either
#'   \code{list(var = <column>, delay = a)}: patients with
#'   \code{var == 1} enter at \code{a + Uniform(0, max_entry)}, the others
#'   at \code{Uniform(0, max_entry)} (e.g. \code{list(var = "z_region",
#'   delay = 6)} for a region enrolling six months later); or a numeric
#'   vector of length \code{n} (non-negative), the delay of each sampled
#'   patient in sampling order. The uniform part is redrawn every call, with
#'   the same random numbers as \code{entry_delay = NULL}, so only the
#'   delayed patients' entry (and hence follow-up
#'   \code{analysis_time - entry}) changes. Ignored when \code{entry_var} is
#'   supplied and on the \code{n = NULL} path (no entry). Passed by
#'   \code{\link{mrct_region_sims}} through its \code{sim_args}.
#' @param analysis_time Numeric calendar time of analysis. Follow-up is
#'   \code{analysis_time - entry_time}. Must be on the same time scale as
#'   the DGM (i.e. the same units as \code{outcome_var} passed to
#'   \code{generate_aft_dgm_flex}). Default \code{48}.
#' @param cens_adjust Numeric log-scale adjustment to censoring distribution.
#'   Positive values increase censoring times; negative values decrease them.
#'   Default \code{0} (no adjustment).
#' @param draw_treatment Logical. If \code{TRUE} (default), reassigns
#'   treatment according to \code{rand_ratio}. If \code{FALSE}, retains
#'   original treatment assignments from the super population.
#' @param seed Integer random seed. Default \code{NULL}.
#' @param strata_rand Character string naming a column in the sampled data
#'   for within-stratum balanced treatment allocation. If \code{NULL},
#'   marginal allocation is used. Default \code{NULL}.
#' @param hrz_crit Numeric log-HR threshold. If supplied, a column
#'   \code{hrz_flag} is added marking subjects with
#'   \code{lin_pred_1 - lin_pred_0 >= hrz_crit}. Default \code{NULL}.
#' @param keep_rand Logical. If \code{TRUE}, appends a \code{rand_order}
#'   column preserving the randomisation sequence. Default \code{FALSE}.
#' @param time_eos Numeric secondary administrative censoring cutoff
#'   (end-of-study time on the DGM scale). Applied after \code{follow_up}
#'   censoring. Default \code{NULL}.
#' @param replace Logical sampling scheme for drawing the \code{n} subjects
#'   from \code{dgm$df_super}. \code{TRUE} (default) samples with replacement
#'   (the trial-resampling / bootstrap mode used for simulated trials).
#'   \code{FALSE} samples without replacement and so requires
#'   \code{n <= nrow(dgm$df_super)}; with \code{n = nrow(dgm$df_super)} it
#'   evaluates every super-population subject exactly once while still applying
#'   randomisation and censoring (unlike the \code{n = NULL} path, which uses
#'   the pool as-is and skips both). Ignored when \code{baseline = "fixed"}.
#'   Default \code{TRUE}.
#' @param baseline Character; how baseline covariates are obtained per
#'   simulated trial. \code{"resample"} (default -- the historical behaviour)
#'   draws subjects from \code{dgm$df_super}, so covariates and therefore
#'   subgroup composition and sizes vary across trials. \code{"fixed"} uses
#'   \code{dgm$df_source} -- every source patient exactly once, in source
#'   order -- so the baseline data and all covariate-defined subgroups are
#'   identical in every simulated trial; only treatment assignment, entry
#'   times, latent event times, and censoring are re-drawn per trial.
#'   Requires a DGM built by a package version that stores \code{df_source}
#'   (rebuild with \code{generate_aft_dgm_flex()} if absent). With
#'   \code{baseline = "fixed"}, \code{n} must be \code{NULL} or equal
#'   \code{nrow(dgm$df_source)}, and \code{replace} is ignored.
#'
#' @return A \code{data.frame} with columns: \describe{
#'   \item{\code{id}}{Subject identifier.}
#'   \item{\code{treat}}{Original treatment from super population.}
#'   \item{\code{treat_sim}}{Simulated treatment assignment.}
#'   \item{\code{flag_harm}}{Subgroup indicator (1 = all subgroup conditions
#'     met).}
#'   \item{\code{z_*}}{Covariate values.}
#'   \item{\code{lin_pred_1}, \code{lin_pred_0}}{Counterfactual log-time
#'     linear predictors.}
#'   \item{\code{y_sim}}{Observed survival time (\code{min(T, C)}).}
#'   \item{\code{event_sim}}{Event indicator (1 = event, 0 = censored).}
#'   \item{\code{t_true}}{Latent true survival time (pre-censoring).}
#'   \item{\code{c_time}}{Effective censoring time (post admin-censoring).}
#'   \item{\code{hrz_flag}}{(Optional) Individual harm-zone indicator.}
#'   \item{\code{rand_order}}{(Optional) Randomisation sequence index.}
#' }
#'
#' @details
#' ## Time-scale consistency
#'
#' All time parameters (\code{analysis_time}, \code{max_entry},
#' \code{time_eos}) must be expressed in the same units as
#' \code{outcome_var} supplied to \code{generate_aft_dgm_flex()}.  A common
#' error is building the DGM on days (e.g. \code{rfstime}) and then passing
#' \code{analysis_time} in months, which causes follow-up windows far shorter
#' than the DGM event-time scale and produces universal administrative
#' censoring (\code{event_sim = 0} for all subjects).
#'
#' Verify with: \code{exp(dgm$model_params$mu)} — the implied median event
#' time should be plausible given your \code{analysis_time}.
#'
#' ## n = NULL path
#'
#' When \code{n = NULL} the entire super population is used as-is, with no
#' staggered entry and no administrative censoring (\code{follow_up = Inf}).
#' Treatment assignments and linear predictors already stored in
#' \code{dgm$df_super} are retained unchanged.
#'
#' ## Censoring adjustment
#'
#' \code{cens_adjust} shifts the log-scale location parameter of the
#' censoring distribution:
#' \itemize{
#'   \item \code{cens_adjust = log(2)} doubles expected censoring times.
#'   \item \code{cens_adjust = log(0.5)} halves expected censoring times.
#' }
#'
#' ## Random-X vs fixed-X designs (\code{baseline})
#'
#' Under \code{baseline = "resample"} each simulated trial is a fresh draw
#' of subjects, so between-trial variability reflects both covariate
#' resampling and outcome generation -- the "what if this trial had enrolled
#' a different sample from the same population?" interpretation. Subgroup
#' sizes fluctuate across trials.
#'
#' Under \code{baseline = "fixed"} the covariate matrix is the observed
#' trial data, identical in every simulated trial: subgroup definitions,
#' memberships, and sizes are exactly those of the source data. Between-trial
#' variability isolates the outcome-generation process (treatment
#' assignment, latent event times, censoring, entry). This is the
#' conditional-on-X (parametric-bootstrap-given-X) design. Note that entry
#' times are still drawn \code{Uniform(0, max_entry)} per trial unless
#' \code{entry_var} names a fixed column, and treatment is still
#' re-randomised per trial unless \code{draw_treatment = FALSE}.
#'
#' @seealso
#' \code{\link{generate_aft_dgm_flex}}, \code{\link{check_censoring_dgm}}
#'
#' @export
#' @importFrom stats rexp runif rnorm rbinom
#' @examples
#' \dontrun{
#' dgm <- setup_gbsg_dgm(model = "null", verbose = FALSE)
#' sim_data <- simulate_from_dgm(dgm, n = 200, seed = 42)
#' dim(sim_data)
#' head(sim_data[, c("y_sim", "event_sim", "treat_sim")])
#' }
simulate_from_dgm <- function(dgm,
                              n              = NULL,
                              rand_ratio     = 1,
                              entry_var      = NULL,
                              max_entry      = 24,
                              analysis_time  = 48,
                              cens_adjust    = 0,
                              draw_treatment = TRUE,
                              seed           = NULL,
                              strata_rand    = NULL,
                              hrz_crit       = NULL,
                              keep_rand      = FALSE,
                              time_eos       = NULL,
                              replace        = TRUE,
                              baseline       = c("resample", "fixed"),
                              entry_delay    = NULL) {

  if (!inherits(dgm, c("aft_dgm_flex", "aft_dgm")))
    stop("dgm must be an object created by generate_aft_dgm_flex()")

  baseline <- match.arg(baseline)

  if (baseline == "fixed") {
    # Fixed-baseline mode requires the source frame stored by the DGM
    # constructor (Step 7b).  Objects saved by older package versions lack
    # it -- fail early with an actionable message rather than downstream.
    if (is.null(dgm$df_source))
      stop("baseline = \"fixed\" requires dgm$df_source, which this DGM ",
           "object does not contain (it was built by an older package ",
           "version). Rebuild it with generate_aft_dgm_flex().")
    if (!is.null(n) && n != nrow(dgm$df_source))
      stop("baseline = \"fixed\" uses every source patient exactly once; ",
           "n must be NULL or nrow(dgm$df_source) = ",
           nrow(dgm$df_source), " (got n = ", n, ").")
  }

  if (!is.null(seed)) set.seed(seed)

  df_super <- dgm$df_super
  params   <- dgm$model_params

  # ===========================================================================
  # Section 1: Sample and initialise follow_up / treat_sim
  #
  # follow_up and treat_sim are set in BOTH branches so all downstream code
  # can reference them unconditionally.  Previously follow_up was defined only
  # inside the else-branch, causing 'object not found' when n = NULL.
  # ===========================================================================

  if (is.null(n) && baseline == "resample") {
    # -------------------------------------------------------------------------
    # n = NULL path: use full super population as-is.
    # No staggered entry => no administrative censoring => follow_up = Inf.
    # Treatment and linear predictors already set in df_super.
    # (baseline = "fixed" never takes this path: it must flow through the
    #  entry / randomisation / censoring machinery below.)
    # -------------------------------------------------------------------------
    df_sim    <- df_super
    n         <- nrow(df_sim)
    follow_up <- rep(Inf, n)                    # no admin censoring

    # treat_sim mirrors the super-population arm assignment
    df_sim$treat_sim <- df_sim$treat

  } else {
    # -------------------------------------------------------------------------
    # Trial-simulation path: choose the baseline frame, then simulate
    # staggered entry, randomisation, and censoring (shared code below).
    # -------------------------------------------------------------------------
    if (baseline == "fixed") {
      # Fixed-X design: every source patient exactly once, in source order.
      # Covariates -- and hence all covariate-defined subgroups -- are
      # identical across simulated trials; only outcomes are re-drawn.
      df_sim <- dgm$df_source
      n      <- nrow(df_sim)
    } else {
      if (!replace && n > nrow(df_super))
        stop("replace = FALSE requires n <= nrow(dgm$df_super) (have ",
             nrow(df_super), ", requested ", n, ").")
      idx_sample <- sample(seq_len(nrow(df_super)), size = n, replace = replace)
      df_sim     <- df_super[idx_sample, ]
    }

    # Staggered entry times
    if (!is.null(entry_var)) {
      entry_time <- df_sim[[entry_var]]
    } else {
      entry_time <- runif(n, min = 0, max = max_entry)
      if (!is.null(entry_delay))
        entry_time <- entry_time + .entry_delay_vector(entry_delay, df_sim, n)
    }
    follow_up <- analysis_time - entry_time     # per-subject follow-up window

    # Initialise treat_sim; overwritten below if draw_treatment = TRUE
    df_sim$treat_sim <- df_sim$treat

    # -------------------------------------------------------------------------
    # Treatment assignment
    # -------------------------------------------------------------------------
    if (draw_treatment) {
      p <- rand_ratio / (1 + rand_ratio)

      if (!is.null(strata_rand) && strata_rand %in% names(df_sim)) {
        # Within-stratum balanced allocation with probabilistic rounding
        strata_vals <- unique(df_sim[[strata_rand]])
        for (sv in strata_vals) {
          idx  <- which(df_sim[[strata_rand]] == sv)
          n_sv <- length(idx)
          base <- floor(n_sv * p)
          n_1  <- base + rbinom(1L, 1L, n_sv * p - base)
          alloc <- sample(c(rep(1L, n_1), rep(0L, n_sv - n_1)))
          df_sim$treat_sim[idx] <- alloc
        }
      } else {
        # Marginal allocation with probabilistic rounding
        base    <- floor(n * p)
        n_treat <- base + rbinom(1L, 1L, n * p - base)
        alloc   <- sample(c(rep(1L, n_treat), rep(0L, n - n_treat)))
        df_sim$treat_sim <- alloc
      }
    }

    if (keep_rand)
      df_sim$rand_order <- seq_len(n)

    # Update linear predictor for assigned treatment
    df_sim$lin_pred_obs <- ifelse(df_sim$treat_sim == 1,
                                  df_sim$lin_pred_1,
                                  df_sim$lin_pred_0)

    # Reset IDs
    df_sim$id <- seq_len(n)
  }

  # ===========================================================================
  # Section 2: Generate latent survival times
  # ===========================================================================
  epsilon  <- log(rexp(n))    # Extreme value (Gumbel) errors
  logT_sim <- params$mu + params$tau * epsilon + df_sim$lin_pred_obs
  T_sim    <- exp(logT_sim)

  # ===========================================================================
  # Section 3: Generate censoring times from DGM censoring model
  # ===========================================================================
  cens_type <- params$censoring$type

  if (cens_type %in% c("weibull", "lognormal")) {

    lin_pred_cens <- ifelse(df_sim$treat_sim == 1,
                            df_sim$lin_pred_cens_1,
                            df_sim$lin_pred_cens_0)

    epsilon_cens <- if (cens_type == "weibull") log(rexp(n)) else rnorm(n)

    logC_sim <- params$censoring$mu + cens_adjust +
                params$censoring$tau * epsilon_cens + lin_pred_cens
    C_sim    <- exp(logC_sim)

  } else if (cens_type == "uniform") {
    C_sim <- runif(n,
                   min = params$censoring$min,
                   max = params$censoring$max)
  } else {
    stop("Unknown censoring type in DGM: '", cens_type, "'")
  }

  # ===========================================================================
  # Section 4: Administrative censoring
  # Primary cap: per-subject follow-up window (analysis_time - entry_time).
  # Secondary cap: end-of-study cutoff (time_eos), if supplied.
  # ===========================================================================
  C_sim <- pmin(C_sim, follow_up)
  if (!is.null(time_eos))
    C_sim <- pmin(C_sim, time_eos)

  # ===========================================================================
  # Section 5: Observed outcome
  # ===========================================================================
  df_sim$y_sim     <- pmin(T_sim, C_sim)
  df_sim$event_sim <- as.integer(T_sim <= C_sim)
  df_sim$t_true    <- T_sim
  df_sim$c_time    <- C_sim

  # ===========================================================================
  # Section 6: Optional columns
  # ===========================================================================
  if (!is.null(hrz_crit)) {
    if (all(c("lin_pred_1", "lin_pred_0") %in% names(df_sim))) {
      df_sim$hrz_flag <- as.integer(
        (df_sim$lin_pred_1 - df_sim$lin_pred_0) >= hrz_crit
      )
    } else {
      warning("hrz_crit supplied but lin_pred_1/lin_pred_0 not found in df_sim")
    }
  }

  # ===========================================================================
  # Section 7: Exclude subjects with zero or negative follow-up
  # ===========================================================================
  df_sim <- df_sim[follow_up > 0, ]

  return(df_sim)
}


# =============================================================================
# check_censoring_dgm()
# =============================================================================

#' Diagnose Censoring Consistency Between DGM Source Data and Simulated Data
#'
#' Compares the censoring distribution observed in the data used to build the
#' DGM against the censoring generated by \code{\link{simulate_from_dgm}}.
#' Reports censoring rates, time quantiles, KM-based median censoring times,
#' and flags substantial discrepancies.
#'
#' @param sim_data A \code{data.frame} returned by
#'   \code{\link{simulate_from_dgm}}.
#' @param dgm An \code{"aft_dgm_flex"} object from
#'   \code{\link{generate_aft_dgm_flex}}. The super population
#'   (\code{dgm$df_super}) provides reference censoring times and event
#'   indicators on the DGM time scale.
#' @param treat_var Character. Name of the treatment column in
#'   \code{sim_data} used for arm-stratified comparisons.
#'   Default \code{"treat_sim"}.
#' @param rate_tol Numeric. Absolute tolerance (proportion scale) for
#'   flagging a censoring-rate discrepancy. Default \code{0.10} (10 pp).
#' @param median_tol Numeric. Relative tolerance for flagging a KM median
#'   censoring-time discrepancy. Default \code{0.25} (25 percent).
#' @param verbose Logical. If \code{TRUE}, prints the full diagnostic table.
#'   Default \code{TRUE}.
#'
#' @return Invisibly returns a named list. Elements are: \code{rates} (data
#'   frame of censoring rates overall and by arm); \code{quantiles} (data
#'   frame of censoring-time quantiles among censored subjects);
#'   \code{km_medians} (data frame of KM-based median censoring times); and
#'   \code{flags} (character vector of triggered warnings, empty if none).
#'
#' @details
#' The reference censoring distribution is derived from \code{dgm$df_super},
#' sampled with replacement from the data passed to
#' \code{generate_aft_dgm_flex()}. Columns \code{y} (observed time) and
#' \code{event} (event indicator) in \code{df_super} reflect the original
#' observed censoring process on the DGM time scale.
#'
#' The KM median censoring time is estimated by reversing the event indicator
#' (\code{1 - event}), treating events as censored and censored observations
#' as the event of interest. This gives a non-parametric estimate of the
#' censoring time distribution unconfounded by event occurrence.
#'
#' Common causes of discrepancy: (1) time-scale mismatch (DGM built on days,
#' \code{analysis_time} in months); check \code{exp(dgm$model_params$mu)}
#' against your \code{analysis_time}. (2) Large \code{cens_adjust} shifting
#' censoring substantially from the fitted model. (3) Short
#' \code{analysis_time} or \code{time_eos} making administrative censoring
#' dominate the censoring process.
#'
#' @seealso \code{\link{simulate_from_dgm}}, \code{\link{generate_aft_dgm_flex}}
#'
#' @export
#' @importFrom survival survfit Surv
#' @importFrom stats quantile
#' @examples
#' \dontrun{
#' dgm <- setup_gbsg_dgm(model = "null", verbose = FALSE)
#' sim_data <- simulate_from_dgm(dgm, n = 200)
#' check_censoring_dgm(sim_data, dgm = dgm)
#' }
check_censoring_dgm <- function(sim_data,
                                dgm,
                                treat_var  = "treat_sim",
                                rate_tol   = 0.10,
                                median_tol = 0.25,
                                verbose    = TRUE) {

  # ---------------------------------------------------------------------------
  # Input validation
  # ---------------------------------------------------------------------------
  if (!inherits(dgm, c("aft_dgm_flex", "aft_dgm")))
    stop("dgm must be an object of class 'aft_dgm_flex'")

  required_sim <- c("y_sim", "event_sim", "c_time", treat_var)
  miss_sim     <- setdiff(required_sim, names(sim_data))
  if (length(miss_sim) > 0)
    stop("sim_data is missing columns: ", paste(miss_sim, collapse = ", "))

  ref      <- dgm$df_super
  miss_ref <- setdiff(c("y", "event", "treat"), names(ref))
  if (length(miss_ref) > 0)
    stop("dgm$df_super is missing columns: ", paste(miss_ref, collapse = ", "))

  flags <- character(0)
  probs <- c(0.25, 0.50, 0.75, 0.90)

  # ---------------------------------------------------------------------------
  # Helper: KM-based median censoring time
  # Reverses event indicator: treats events as censored and censored obs as
  # the "event" of interest, yielding the censoring time distribution.
  # ---------------------------------------------------------------------------
  km_median_cens <- function(time, event) {
    fit <- survfit(Surv(time, 1L - as.integer(event)) ~ 1)
    med <- summary(fit)$table[["median"]]
    if (is.na(med)) max(time, na.rm = TRUE) else unname(med)
  }

  # ---------------------------------------------------------------------------
  # 1. Censoring rates
  # ---------------------------------------------------------------------------
  ref_rate_all <- 1 - mean(as.integer(ref$event),         na.rm = TRUE)
  sim_rate_all <- 1 - mean(as.integer(sim_data$event_sim), na.rm = TRUE)

  ref_rate_arm <- tapply(1L - as.integer(ref$event),
                         as.character(ref$treat), mean, na.rm = TRUE)
  sim_rate_arm <- tapply(1L - as.integer(sim_data$event_sim),
                         as.character(sim_data[[treat_var]]), mean, na.rm = TRUE)

  arm_labs <- c("0", "1")
  rates <- data.frame(
    Group    = c("Overall", "Arm 0", "Arm 1"),
    Ref_rate = c(ref_rate_all,
                 ref_rate_arm[arm_labs[1]], ref_rate_arm[arm_labs[2]]),
    Sim_rate = c(sim_rate_all,
                 sim_rate_arm[arm_labs[1]], sim_rate_arm[arm_labs[2]]),
    stringsAsFactors = FALSE
  )
  rates$Diff     <- rates$Sim_rate - rates$Ref_rate
  rownames(rates) <- NULL

  if (abs(sim_rate_all - ref_rate_all) > rate_tol)
    flags <- c(flags,
               sprintf("Censoring rate: ref = %.1f%%, sim = %.1f%%  [|diff| = %.1f pp > tol %.1f pp]",
                       100 * ref_rate_all, 100 * sim_rate_all,
                       100 * abs(sim_rate_all - ref_rate_all), 100 * rate_tol))

  # ---------------------------------------------------------------------------
  # 2. Censoring-time quantiles (censored subjects only)
  # Ref: y[event == 0]  |  Sim: c_time[event_sim == 0]
  # ---------------------------------------------------------------------------
  ref_ct <- ref$y[ref$event == 0]
  sim_ct <- sim_data$c_time[sim_data$event_sim == 0]

  if (length(ref_ct) == 0 || length(sim_ct) == 0) {
    quant_df <- data.frame(Quantile = paste0(100 * probs, "%"),
                           Ref = NA_real_, Sim = NA_real_, Ratio = NA_real_)
    flags <- c(flags, "Quantile comparison skipped: no censored subjects in one dataset")
  } else {
    rq <- quantile(ref_ct, probs = probs, na.rm = TRUE)
    sq <- quantile(sim_ct, probs = probs, na.rm = TRUE)
    quant_df <- data.frame(
      Quantile = paste0(100 * probs, "%"),
      Ref      = round(unname(rq), 2),
      Sim      = round(unname(sq), 2),
      Ratio    = round(unname(sq) / unname(rq), 3),
      stringsAsFactors = FALSE
    )
  }

  # ---------------------------------------------------------------------------
  # 3. KM-based median censoring time — overall and by arm
  # ---------------------------------------------------------------------------
  safe_km <- function(time, event)
    tryCatch(km_median_cens(time, event), error = function(e) NA_real_)

  ref_km_all <- safe_km(ref$y, ref$event)
  sim_km_all <- safe_km(sim_data$y_sim, sim_data$event_sim)

  ref_km_0 <- safe_km(ref$y[ref$treat == 0],    ref$event[ref$treat == 0])
  ref_km_1 <- safe_km(ref$y[ref$treat == 1],    ref$event[ref$treat == 1])
  sim_km_0 <- safe_km(sim_data$y_sim[sim_data[[treat_var]] == 0],
                      sim_data$event_sim[sim_data[[treat_var]] == 0])
  sim_km_1 <- safe_km(sim_data$y_sim[sim_data[[treat_var]] == 1],
                      sim_data$event_sim[sim_data[[treat_var]] == 1])

  km_medians <- data.frame(
    Group      = c("Overall", "Arm 0", "Arm 1"),
    Ref_median = c(ref_km_all, ref_km_0, ref_km_1),
    Sim_median = c(sim_km_all, sim_km_0, sim_km_1),
    stringsAsFactors = FALSE
  )
  km_medians$Ratio <- round(km_medians$Sim_median / km_medians$Ref_median, 3)
  rownames(km_medians) <- NULL

  if (!is.na(ref_km_all) && !is.na(sim_km_all)) {
    ratio_km <- sim_km_all / ref_km_all
    if (abs(ratio_km - 1) > median_tol)
      flags <- c(flags,
                 sprintf("KM median censoring: ref = %.2f, sim = %.2f  [ratio = %.2f, tol = %.2f]",
                         ref_km_all, sim_km_all, ratio_km, 1 + median_tol))
  }

  # ---------------------------------------------------------------------------
  # 4. DGM censoring model parameters (for context)
  # ---------------------------------------------------------------------------
  cens_params <- dgm$model_params$censoring
  cens_type   <- if (!is.null(cens_params$type)) cens_params$type else "unknown"

  # ---------------------------------------------------------------------------
  # 5. Print report
  # ---------------------------------------------------------------------------
  if (verbose) {
    sep <- paste(rep("=", 57), collapse = "")
    cat("\n", sep, "\n", sep = "")
    cat("  Censoring Diagnostic: DGM Reference vs Simulated\n")
    cat(sep, "\n", sep = "")
    cat(sprintf("  DGM censoring type  : %s\n", cens_type))
    if (!is.null(cens_params$mu))
      cat(sprintf("  DGM mu_cens         : %.4f  [exp = %.2f time units]\n",
                  cens_params$mu, exp(cens_params$mu)))
    if (!is.null(cens_params$tau))
      cat(sprintf("  DGM tau_cens        : %.4f\n", cens_params$tau))
    cat(sprintf("  Reference n (super) : %d\n", nrow(ref)))
    cat(sprintf("  Simulated n         : %d\n", nrow(sim_data)))

    cat("\n--- 1. Censoring Rates ---\n")
    tmp <- rates
    tmp$Ref_rate <- sprintf("%.1f%%", 100 * tmp$Ref_rate)
    tmp$Sim_rate <- sprintf("%.1f%%", 100 * tmp$Sim_rate)
    tmp$Diff     <- sprintf("%+.1f pp", 100 * tmp$Diff)
    print(tmp, row.names = FALSE)

    cat("\n--- 2. Censoring-Time Quantiles (censored subjects only) ---\n")
    cat("    Ref: y[event == 0]  |  Sim: c_time[event_sim == 0]\n")
    print(quant_df, row.names = FALSE)

    cat("\n--- 3. KM Median Censoring Time (reversed event indicator) ---\n")
    print(km_medians, row.names = FALSE)

    cat("\n--- 4. Implied Time-Scale Check ---\n")
    mu_out  <- dgm$model_params$mu
    cat(sprintf("  exp(params$mu)          = %.2f  [median outcome time, DGM scale]\n",
                exp(mu_out)))
    if (!is.null(cens_params$mu))
      cat(sprintf("  exp(params$censoring$mu)= %.2f  [median censoring time, DGM scale]\n",
                  exp(cens_params$mu)))
    cat("  If these values are implausibly large relative to your\n")
    cat("  analysis_time, the DGM was likely built on a different time\n")
    cat("  scale (e.g. days vs months).\n")

    cat("\n")
    if (length(flags) == 0) {
      cat("[OK] No substantial discrepancies detected.\n")
    } else {
      cat("[WARNING] Potential discrepancies detected:\n")
      for (f in flags) cat("  * ", f, "\n", sep = "")
      cat("\nCommon causes:\n")
      cat("  1. Time-scale mismatch: verify exp(dgm$model_params$mu) is\n")
      cat("     plausible relative to analysis_time.\n")
      cat("  2. cens_adjust shifting censoring substantially from fitted model.\n")
      cat("  3. Short analysis_time / time_eos making admin censoring dominant.\n")
    }
    cat(sep, "\n\n", sep = "")
  }

  invisible(list(
    rates      = rates,
    quantiles  = quant_df,
    km_medians = km_medians,
    flags      = flags
  ))
}


#' Calibrate Censoring Adjustment to Match DGM Reference Distribution
#'
#' Uses root-finding to select a value of \code{cens_adjust} for
#' \code{\link{simulate_from_dgm}} such that a chosen censoring summary
#' statistic in the simulated data matches the corresponding statistic from
#' the DGM reference data (\code{dgm$df_super}).
#'
#' Two calibration targets are supported:
#' \describe{
#'   \item{\code{"rate"}}{Overall censoring rate (proportion censored).
#'     Finds \code{cens_adjust} such that
#'     \code{mean(event_sim == 0)} in simulated data equals
#'     \code{mean(event == 0)} in \code{dgm$df_super}.}
#'   \item{\code{"km_median"}}{KM-based median censoring time, estimated by
#'     reversing the event indicator so censored observations become the
#'     "event" of interest. Finds \code{cens_adjust} such that the
#'     simulated KM median matches the reference KM median.}
#' }
#'
#' @param dgm An \code{"aft_dgm_flex"} object from
#'   \code{\link{generate_aft_dgm_flex}}.
#' @param target Character. Calibration target: \code{"rate"} (default) or
#'   \code{"km_median"}.
#' @param n Integer. Sample size passed to \code{\link{simulate_from_dgm}}.
#'   Default \code{1000}.
#' @param rand_ratio Numeric. Randomisation ratio passed to
#'   \code{\link{simulate_from_dgm}}. Default \code{1}.
#' @param analysis_time Numeric. Calendar analysis time passed to
#'   \code{\link{simulate_from_dgm}}. Must be on the DGM time scale.
#'   Default \code{48}.
#' @param max_entry Numeric. Maximum staggered entry time passed to
#'   \code{\link{simulate_from_dgm}}. Default \code{24}.
#' @param seed Integer. Base random seed. Each evaluation of the objective
#'   function uses this seed for reproducibility. Default \code{42}.
#' @param interval Numeric vector of length 2. Search interval for
#'   \code{cens_adjust} on the log scale. Default \code{c(-3, 3)}
#'   (corresponding roughly to a 20-fold decrease/increase in censoring times).
#' @param tol Numeric. Root-finding tolerance. Default \code{1e-4}.
#' @param tol_rel Numeric. Maximum tolerated relative error, in percent; the
#'   call stops if the achieved metric is not within \code{tol_rel} percent of
#'   the reference. Default \code{2.5}.
#' @param n_eval Integer. Sample size used inside the objective function
#'   during root-finding. Smaller values are faster but noisier; increase
#'   for precision. Default \code{2000}.
#' @param verbose Logical. Print search progress and final result.
#'   Default \code{TRUE}.
#' @param ... Additional arguments passed to \code{\link{simulate_from_dgm}}
#'   (e.g. \code{strata_rand}, \code{time_eos}).
#'
#' @return A named list with elements: \describe{
#'   \item{\code{cens_adjust}}{Calibrated \code{cens_adjust} value.}
#'   \item{\code{target}}{Calibration target used.}
#'   \item{\code{ref_value}}{Reference metric value from \code{dgm$df_super}.}
#'   \item{\code{sim_value}}{Achieved metric value in simulated data at the
#'     calibrated \code{cens_adjust}.}
#'   \item{\code{residual}}{Absolute difference between \code{sim_value} and
#'     \code{ref_value}.}
#'   \item{\code{iterations}}{Number of \code{uniroot} iterations.}
#'   \item{\code{diagnostic}}{Output of \code{\link{check_censoring_dgm}} at
#'     the calibrated value (invisibly).}
#' }
#'
#' @details
#' ## How the objective function works
#'
#' At each candidate \code{cens_adjust} value, the objective function:
#' \enumerate{
#'   \item Calls \code{simulate_from_dgm()} with \code{n = n_eval} and
#'     the candidate \code{cens_adjust}.
#'   \item Calls \code{check_censoring_dgm()} with \code{verbose = FALSE}
#'     to extract the target metric.
#'   \item Returns \code{sim_metric - ref_metric}.
#' }
#' \code{uniroot} finds the zero crossing, i.e. the \code{cens_adjust} at
#' which simulated and reference metrics are equal.
#'
#' ## Monotonicity
#'
#' The objective is monotone in \code{cens_adjust} for both targets:
#' \itemize{
#'   \item Larger \code{cens_adjust} → longer censoring times →
#'     lower censoring rate and higher KM median.
#'   \item Smaller \code{cens_adjust} → shorter censoring times →
#'     higher censoring rate and lower KM median.
#' }
#' If \code{uniroot} fails (the target lies outside the search interval),
#' the boundary values are printed and a wider \code{interval} should be
#' tried.
#'
#' ## Stochastic noise
#'
#' Because the objective function involves simulation, there is Monte Carlo
#' noise. Setting a fixed \code{seed} and a sufficiently large \code{n_eval}
#' (>= 2000) reduces noise enough for reliable root-finding. The
#' \code{tol} argument controls the root-finding tolerance on the
#' \code{cens_adjust} scale (not the metric scale).
#'
#' @seealso
#' \code{\link{simulate_from_dgm}}, \code{\link{check_censoring_dgm}},
#' \code{\link{generate_aft_dgm_flex}}
#'
#' @examples
#' \dontrun{
#' library(survival)
#'
#' # Build DGM on months scale
#' gbsg$time_months <- gbsg$rfstime / 30.4375
#'
#' dgm <- generate_aft_dgm_flex(
#'   data            = gbsg,
#'   continuous_vars = c("age", "size", "nodes", "pgr", "er"),
#'   factor_vars     = c("meno", "grade"),
#'   outcome_var     = "time_months",
#'   event_var       = "status",
#'   treatment_var   = "hormon",
#'   subgroup_vars   = c("er", "meno"),
#'   subgroup_cuts   = list(er = 20, meno = 0)
#' )
#'
#' # Calibrate so simulated censoring rate matches reference
#' cal_rate <- calibrate_cens_adjust(
#'   dgm           = dgm,
#'   target        = "rate",
#'   n             = 1000,
#'   analysis_time = 84,
#'   max_entry     = 24
#' )
#' cat("Calibrated cens_adjust (rate):", cal_rate$cens_adjust, "\n")
#'
#' # Calibrate to KM median censoring time instead
#' cal_km <- calibrate_cens_adjust(
#'   dgm           = dgm,
#'   target        = "km_median",
#'   n             = 1000,
#'   analysis_time = 84,
#'   max_entry     = 24
#' )
#' cat("Calibrated cens_adjust (km_median):", cal_km$cens_adjust, "\n")
#'
#' # Use calibrated value in simulation
#' sim <- simulate_from_dgm(
#'   dgm           = dgm,
#'   n             = 1000,
#'   analysis_time = 84,
#'   max_entry     = 24,
#'   cens_adjust   = cal_rate$cens_adjust,
#'   seed          = 123
#' )
#' mean(sim$event_sim)   # event rate
#' mean(sim$event_sim == 0)  # censoring rate — should match ref
#' }
#'
#' @export
#' @importFrom stats uniroot
#' @importFrom survival survfit Surv
calibrate_cens_adjust <- function(dgm,
                                  target        = c("rate", "km_median"),
                                  n             = 1000,
                                  rand_ratio    = 1,
                                  analysis_time = 48,
                                  max_entry     = 24,
                                  seed          = 42,
                                  interval      = c(-3, 3),
                                  tol           = 1e-4,
                                  tol_rel       = 2.5,
                                  n_eval        = 2000,
                                  verbose       = TRUE,
                                  ...) {

  target <- match.arg(target)

  if (!inherits(dgm, c("aft_dgm_flex", "aft_dgm")))
    stop("dgm must be an object of class 'aft_dgm_flex'")

  # ---------------------------------------------------------------------------
  # Extract reference metric from dgm$df_super
  # ---------------------------------------------------------------------------
  ref        <- dgm$df_super
  ref_rate   <- 1 - mean(as.integer(ref$event), na.rm = TRUE)

  km_median_cens <- function(time, event) {
    fit <- survfit(Surv(time, 1L - as.integer(event)) ~ 1)
    med <- summary(fit)$table[["median"]]
    if (is.na(med)) max(time, na.rm = TRUE) else unname(med)
  }

  ref_km_med <- tryCatch(
    km_median_cens(ref$y, ref$event),
    error = function(e) {
      stop("Could not compute KM median censoring time from dgm$df_super: ",
           e$message)
    }
  )

  ref_value <- switch(target,
                      rate      = ref_rate,
                      km_median = ref_km_med
  )

  if (verbose) {
    sep <- paste(rep("-", 55), collapse = "")
    cat("\n", sep, "\n", sep = "")
    cat("  calibrate_cens_adjust()\n")
    cat(sep, "\n", sep = "")
    cat(sprintf("  Target metric    : %s\n", target))
    cat(sprintf("  Reference value  : %.4f\n", ref_value))
    cat(sprintf("  Search interval  : [%.2f, %.2f]\n",
                interval[1], interval[2]))
    cat(sprintf("  n_eval per call  : %d\n", n_eval))
    cat(sprintf("  Tolerance        : %.1e\n", tol))
    cat(sep, "\n", sep = "")
  }

  # ---------------------------------------------------------------------------
  # Simulated metric (censoring rate or KM median) at a candidate cens_adjust.
  # A fixed seed makes each candidate evaluate identically.
  # ---------------------------------------------------------------------------
  sim_metric <- function(adj) {
    sim <- simulate_from_dgm(
      dgm           = dgm,
      n             = n_eval,
      rand_ratio    = rand_ratio,
      analysis_time = analysis_time,
      max_entry     = max_entry,
      cens_adjust   = adj,
      seed          = seed,
      ...
    )
    diag <- check_censoring_dgm(sim, dgm, verbose = FALSE,
                                rate_tol = Inf, median_tol = Inf)
    switch(target,
           rate      = diag$rates$Sim_rate[diag$rates$Group == "Overall"],
           km_median = diag$km_medians$Sim_median[diag$km_medians$Group == "Overall"])
  }

  # ---------------------------------------------------------------------------
  # Root finding: uniroot() with automatic interval extension + a hard relative-
  # tolerance gate, shared with the effect-calibrators via .calibrate_by_root().
  # Replaces the former manual bracket check plus bare uniroot.
  # ---------------------------------------------------------------------------
  if (verbose) cat("  Searching...\n")

  sol <- .calibrate_by_root(
    effect_fun = sim_metric, target = ref_value, interval = interval,
    tol = tol, tol_rel = tol_rel, label = target, param = "cens_adjust",
    verbose = verbose
  )
  cens_adj_cal <- sol$root

  # ---------------------------------------------------------------------------
  # Evaluate final diagnostic at calibrated value
  # ---------------------------------------------------------------------------
  sim_final <- simulate_from_dgm(
    dgm           = dgm,
    n             = n,
    rand_ratio    = rand_ratio,
    analysis_time = analysis_time,
    max_entry     = max_entry,
    cens_adjust   = cens_adj_cal,
    seed          = seed,
    ...
  )

  diag_final <- check_censoring_dgm(
    sim_data  = sim_final,
    dgm       = dgm,
    verbose   = verbose,
    rate_tol  = 0.05,
    median_tol = 0.10
  )

  sim_value_final <- switch(target,
                            rate      = diag_final$rates$Sim_rate[diag_final$rates$Group == "Overall"],
                            km_median = diag_final$km_medians$Sim_median[diag_final$km_medians$Group == "Overall"]
  )

  if (verbose) {
    cat(sprintf("\n  === Calibration Result ===\n"))
    cat(sprintf("  cens_adjust      : %.6f\n", cens_adj_cal))
    cat(sprintf("  Reference %-10s: %.4f\n", target, ref_value))
    cat(sprintf("  Simulated %-10s: %.4f\n", target, sim_value_final))
    cat(sprintf("  Residual         : %.4f\n",
                abs(sim_value_final - ref_value)))
    cat(sprintf("  uniroot iters    : %d\n", sol$iter))
    cat(paste(rep("-", 55), collapse = ""), "\n\n", sep = "")
  }

  invisible(list(
    cens_adjust  = cens_adj_cal,
    target       = target,
    ref_value    = ref_value,
    sim_value    = sim_value_final,
    residual     = abs(sim_value_final - ref_value),
    iterations   = sol$iter,
    diagnostic   = diag_final
  ))
}


#' Per-patient entry delay of simulate_from_dgm()
#'
#' @param entry_delay list(var, delay) or a numeric vector of length n.
#' @param df_sim The sampled trial frame.
#' @param n Number of sampled patients.
#' @return Numeric vector of length n.
#' @noRd
.entry_delay_vector <- function(entry_delay, df_sim, n) {
  if (is.list(entry_delay)) {
    if (!all(c("var", "delay") %in% names(entry_delay)))
      stop("entry_delay must be list(var = <column>, delay = <number>) or a ",
           "numeric vector of length n.", call. = FALSE)
    v <- entry_delay$var; a <- entry_delay$delay
    if (!is.character(v) || length(v) != 1L || !v %in% names(df_sim))
      stop("entry_delay$var must name a column of dgm$df_super.", call. = FALSE)
    if (!is.numeric(a) || length(a) != 1L || !is.finite(a) || a < 0)
      stop("entry_delay$delay must be one non-negative number.", call. = FALSE)
    return(a * as.numeric(df_sim[[v]] == 1))
  }
  if (!is.numeric(entry_delay) || length(entry_delay) != n ||
      any(!is.finite(entry_delay)) || any(entry_delay < 0))
    stop("A numeric entry_delay must have length n = ", n,
         " with finite non-negative values.", call. = FALSE)
  as.numeric(entry_delay)
}

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.