Nothing
# =============================================================================
# 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)
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.