simulate_from_dgm: Simulate Survival Data from AFT Data Generating Mechanism

View source: R/simulate_from_dgm.R

simulate_from_dgmR Documentation

Simulate Survival Data from AFT Data Generating Mechanism

Description

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.

Usage

simulate_from_dgm(
  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
)

Arguments

dgm

An object of class "aft_dgm_flex" created by generate_aft_dgm_flex.

n

Integer specifying the sample size. If NULL (default), uses the entire super population without sampling.

rand_ratio

Numeric randomisation ratio (treatment:control). Default 1 (1:1 allocation).

entry_var

Character string naming an entry-time variable in the super population. If NULL, entry times are drawn as Uniform(0, max_entry). Default NULL. When supplied it takes precedence over entry_delay, which is then ignored. (mrct_region_sims sets entry_var = "entrytime" whenever dgm$df_super has a column entrytime: one fixed entry time per super-population row, carried with the row into every trial that samples it.)

max_entry

Numeric maximum entry time for staggered entry simulation. Only used when entry_var = NULL. Default 24.

analysis_time

Numeric calendar time of analysis. Follow-up is analysis_time - entry_time. Must be on the same time scale as the DGM (i.e. the same units as outcome_var passed to generate_aft_dgm_flex). Default 48.

cens_adjust

Numeric log-scale adjustment to censoring distribution. Positive values increase censoring times; negative values decrease them. Default 0 (no adjustment).

draw_treatment

Logical. If TRUE (default), reassigns treatment according to rand_ratio. If FALSE, retains original treatment assignments from the super population.

seed

Integer random seed. Default NULL.

strata_rand

Character string naming a column in the sampled data for within-stratum balanced treatment allocation. If NULL, marginal allocation is used. Default NULL.

hrz_crit

Numeric log-HR threshold. If supplied, a column hrz_flag is added marking subjects with lin_pred_1 - lin_pred_0 >= hrz_crit. Default NULL.

keep_rand

Logical. If TRUE, appends a rand_order column preserving the randomisation sequence. Default FALSE.

time_eos

Numeric secondary administrative censoring cutoff (end-of-study time on the DGM scale). Applied after follow_up censoring. Default NULL.

replace

Logical sampling scheme for drawing the n subjects from dgm$df_super. TRUE (default) samples with replacement (the trial-resampling / bootstrap mode used for simulated trials). FALSE samples without replacement and so requires n <= nrow(dgm$df_super); with n = nrow(dgm$df_super) it evaluates every super-population subject exactly once while still applying randomisation and censoring (unlike the n = NULL path, which uses the pool as-is and skips both). Ignored when baseline = "fixed". Default TRUE.

baseline

Character; how baseline covariates are obtained per simulated trial. "resample" (default – the historical behaviour) draws subjects from dgm$df_super, so covariates and therefore subgroup composition and sizes vary across trials. "fixed" uses 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 df_source (rebuild with generate_aft_dgm_flex() if absent). With baseline = "fixed", n must be NULL or equal nrow(dgm$df_source), and replace is ignored.

entry_delay

NULL (default: every patient enters at Uniform(0, max_entry)), or a per-patient delay added to that entry time, in the DGM's time units. Either list(var = <column>, delay = a): patients with var == 1 enter at a + Uniform(0, max_entry), the others at Uniform(0, max_entry) (e.g. list(var = "z_region", delay = 6) for a region enrolling six months later); or a numeric vector of length 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 entry_delay = NULL, so only the delayed patients' entry (and hence follow-up analysis_time - entry) changes. Ignored when entry_var is supplied and on the n = NULL path (no entry). Passed by mrct_region_sims through its sim_args.

Details

Time-scale consistency

All time parameters (analysis_time, max_entry, time_eos) must be expressed in the same units as outcome_var supplied to generate_aft_dgm_flex(). A common error is building the DGM on days (e.g. rfstime) and then passing analysis_time in months, which causes follow-up windows far shorter than the DGM event-time scale and produces universal administrative censoring (event_sim = 0 for all subjects).

Verify with: exp(dgm$model_params$mu) — the implied median event time should be plausible given your analysis_time.

n = NULL path

When n = NULL the entire super population is used as-is, with no staggered entry and no administrative censoring (follow_up = Inf). Treatment assignments and linear predictors already stored in dgm$df_super are retained unchanged.

Censoring adjustment

cens_adjust shifts the log-scale location parameter of the censoring distribution:

  • cens_adjust = log(2) doubles expected censoring times.

  • cens_adjust = log(0.5) halves expected censoring times.

Random-X vs fixed-X designs (baseline)

Under 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 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 Uniform(0, max_entry) per trial unless entry_var names a fixed column, and treatment is still re-randomised per trial unless draw_treatment = FALSE.

Value

A data.frame with columns:

id

Subject identifier.

treat

Original treatment from super population.

treat_sim

Simulated treatment assignment.

flag_harm

Subgroup indicator (1 = all subgroup conditions met).

z_*

Covariate values.

lin_pred_1, lin_pred_0

Counterfactual log-time linear predictors.

y_sim

Observed survival time (min(T, C)).

event_sim

Event indicator (1 = event, 0 = censored).

t_true

Latent true survival time (pre-censoring).

c_time

Effective censoring time (post admin-censoring).

hrz_flag

(Optional) Individual harm-zone indicator.

rand_order

(Optional) Randomisation sequence index.

See Also

generate_aft_dgm_flex, check_censoring_dgm

Examples

## Not run: 
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")])

## End(Not run)

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