Skip to main content

Kaplan-Meier visual predictive check for a time-to-event model

Description

Simulates the observed design n_sim times and returns, per stratum, the observed Kaplan-Meier curve beside the pointwise band of the replicate Kaplan-Meier curves, for one single-event time-to-event (TTE) endpoint. Everything is computed by ferx-core (vpc_tte(), ferx-core #1886); this function only carries the result into R. It never refits.

Usage

ferx_vpc_tte(
  model,
  data = NULL,
  n_sim = 200L,
  seed = 42L,
  fit = NULL,
  strata = NULL,
  by_dose = FALSE,
  censoring = c("observed", "horizon"),
  cmt = NULL,
  horizon = NULL,
  probs = c(0.05, 0.5, 0.95),
  grid = "auto"
)

Arguments

  • model: Path to a .ferx model file with an [event_model] endpoint.
  • data: Path to a NONMEM-format CSV, or a data.frame, holding the observed TTE records (DV = 1 event, DV = 0 right-censored), one per subject on the endpoint. When omitted, the data fit was fitted to, otherwise the model file’s [data] block.
  • n_sim: Number of simulated replicates; at least 20 for the default probs.
  • seed: Random seed for the replicates and the censoring draws.
  • fit: Optional ferx_fit result. When given, the replicates are simulated at the fitted parameters, as in [ferx_simulate](ferx_simulate.qmd); otherwise at the model file’s initial values.
  • strata: NULL (one stratum, "all") or the name of a covariate: subjects are grouped by its exact value at their first record.
  • by_dose: TRUE to stratify by the amount of each subject’s first dose instead (0 for a subject with no dose). Cannot be combined with strata.
  • censoring: "observed" (default) or "horizon"; see the section above.
  • cmt: The TTE endpoint’s compartment. Required when the model has more than one TTE endpoint; NULL takes the only one.
  • horizon: The time the replicates are simulated to. NULL (default) is the latest time recorded on the endpoint.
  • probs: Three band probabilities, strictly increasing inside (0, 1): the lower bound, the middle line and the upper bound.
  • grid: The times the band is evaluated at: "auto" (0, the stratum’s observed times and 101 evenly spaced points up to H), "all_steps" (also every step of every replicate curve: exact step ribbons, on a large grid), or a numeric vector of times.

The curve and the band

The observed curve uses survival::survfit’s tie convention (at a tied time, events count before censorings), so x$observed matches survfit(Surv(time, event) ~ 1) row for row, with the Nelson-Aalen cumulative hazard in cumhaz. The band at each grid time is R’s default (type 7) quantile over the replicate curves still under follow-up there. A replicate past its last follow-up time is left out rather than counted as 0 or 1, and a grid time with fewer than ceiling(1 / min(p, 1 - p)) - 1 replicates left (19 for a 5) has an NA band: its tail quantile would be an interpolation between the two most extreme curves. So n_sim must be at least one more than that, 20 for the default band.

Censoring in the replicates

The replicates are simulated to the horizon H (horizon, or the latest time recorded on the endpoint). Under the default censoring = "observed" each subject then gets a censoring time, and a replicate event after it becomes a censoring there: a subject observed censored keeps its own time, and a subject observed with an event draws one from the reverse Kaplan-Meier curve of the observed censorings in its own stratum, given that it exceeds the event time. The replicates are then censored like the data, which is what makes the observed curve comparable with the band. censoring = "horizon" censors every replicate at H only, which gives too narrow a band when the data are censored before H. The draws are seeded by seed.

What it refuses

An input the curve or the band would be wrong on is an R error of class ferx_engine_error with e$code == "E_VPC_TTE_INPUT": a model without a TTE endpoint; several TTE endpoints and no cmt (under competing risks one minus the Kaplan-Meier curve of one cause is not its cumulative incidence; with cmt set, the curve is that cause’s survival with the other causes as censoring); a cmt that is not a TTE endpoint; a repeated-events endpoint; left truncation (delayed entry); an interval-censored record; more than one record per subject on the endpoint; a subject id that appears in two separate runs of rows; no record on the endpoint at all; band probabilities not strictly increasing inside (0, 1), or too few replicates for them; a grid time that is not finite and non-negative; and a stratification covariate a subject lacks, or with more than 10 values (bin it into a categorical covariate first).

Seealso

[plot.ferx_vpc_tte](plot.ferx_vpc_tte.qmd), [ferx_predict_survival](ferx_predict_survival.qmd)Other simulation: [ferx_calc_npde](ferx_calc_npde.qmd), [ferx_contrast_vpc](ferx_contrast_vpc.qmd), [ferx_predict](ferx_predict.qmd), [ferx_predict_survival](ferx_predict_survival.qmd), [ferx_sim_parameters](ferx_sim_parameters.qmd), [ferx_simulate](ferx_simulate.qmd), [ferx_simulate_adaptive](ferx_simulate_adaptive.qmd), [ferx_simulate_with_uncertainty](ferx_simulate_with_uncertainty.qmd)

Concept

simulation

Value

An object of class ferx_vpc_tte, a list with:

  • observed: The observed Kaplan-Meier curve, one row per distinct time per stratum: STRATUM, time, n_risk, n_event, n_censor, surv and the Nelson-Aalen cumhaz.
  • band: The replicate band, one row per grid time per stratum: STRATUM, time, obs (the observed curve read at time; NA past its last time unless it reached 0), lo, med, hi (the band at probs; NA where too few replicates are still under follow-up) and n_used, the number of replicate curves defined there.
  • strata: One row per stratum: STRATUM (its label: "all", "NAME=value" or "dose=value"), value (the covariate or dose value; NA without strata) and n_subjects.
  • cmt, horizon, n_sim, probs, censoring: The endpoint checked, the horizon H the replicates were simulated to, and the settings used.
  • warnings: The simulator’s diagnostics and the data reader’s, also raised as an R warning.

STRATUM is a factor whose levels are in the engine’s stratum order (ascending value).

Examples

ex <- ferx_example("tte_weibull")
vpc <- ferx_vpc_tte(ex$model, ex$data, n_sim = 50L, seed = 1L)
vpc
plot(vpc)