Time-to-Event Endpoints (`[event_model]`)

Maturity: beta — see Feature Maturity for what this means.

The [event_model] block registers a CMT column as a TTE (time-to-event) endpoint. Observations on that CMT are routed to a parametric survival likelihood rather than the Gaussian residual-error model.

See Time-to-Event Estimation for the full reference including data format, hazard families, and comparison with nlmixr2 / NONMEM.

Syntax

[event_model]
  cmt    = <integer>    # CMT column value in the data file
  family = exponential  # exponential | weibull | gompertz
  scale  = <expression> # theta/eta/covariate expression — Exponential (rate λ) and Weibull
  rate   = <expression> # alias for scale (Exponential only)
  shape  = <expression> # Weibull only (required; error if present for exponential/gompertz)
  alpha  = <expression> # Gompertz only: baseline hazard at t=0
  gamma  = <expression> # Gompertz only: hazard growth rate
  loghr  = <expression> # optional (all families): proportional-hazards covariate term;
                        #   multiplies the full hazard by exp(loghr)

Expression namespace: expressions are evaluated in the theta / eta / covariate namespace, and may also reference names defined in [individual_parameters] (e.g. a hazard driven by an individual CL), including ones defined with a NONMEM-style if (...) { ... } else { ... } block. Those references are resolved per subject at evaluation time; only the individual parameters the hazard actually uses are computed. A referenced individual parameter may not depend on an inter-occasion (IOV/kappa) random effect — the hazard has no occasion context, so that is rejected with an error. Writing the full theta/eta expression directly (e.g. TVLAMBDA * exp(ETA_LAMBDA)) also works.

Named blocks allow multiple TTE endpoints:

[event_model DROPOUT]
  cmt    = 2
  family = exponential
  scale  = TVLAMBDA_DROPOUT * exp(ETA_LAMBDA)

[event_model DEATH]
  cmt    = 3
  family = weibull
  scale  = TVSCALE_DEATH
  shape  = TVSHAPE_DEATH

Joint PK-TTE: ODE-accumulated hazard (`hazard =`)

For a drug-driven hazard — one that depends on the (ODE) PK state — use the hazard key instead of an analytic family:

[event_model]
  cmt    = 3
  hazard = H0 * exp(BETA * (central / V))   # references ODE states + individual parameters

The parser appends a cumulative-hazard accumulator to the model’s ODE system (d/dt(__chz) = <hazard>, starting at 0) and estimates it jointly with the PK; the TTE likelihood reads H(t) from that state and h(t) from its derivative, so the PK and the event model share the same random effects (a common frailty). Notes:

Requires an ODE model (ode(...) in [structural_model] with an [odes] block).
hazard is mutually exclusive with the analytic family / scale / shape / alpha / gamma keys.
The expression compiles in the [odes] RHS namespace — it may reference ODE state names (e.g. central) and [individual_parameters] (e.g. V, H0), but not raw thetas or covariates directly, so declare hazard parameters and any between-subject variability in [individual_parameters].
IOV is not yet supported with an ODE hazard (rejected at parse time).
fit() and predict_survival() work; simulate() is not yet supported for an ODE-accumulated hazard (drug-driven event-time sampling is a later slice — it returns a clear error rather than silently emitting no event rows).

See Joint PK-TTE for a worked example.

TTE-only models

For models with only TTE endpoints and no Gaussian PK data, the [structural_model], [error_model], and [individual_parameters] blocks may all be omitted:

[parameters]
  theta TVLAMBDA(0.05, 0.001, 10.0)
  omega ETA_LAMBDA ~ 0.09

[event_model]
  cmt    = 2
  family = exponential
  scale  = TVLAMBDA * exp(ETA_LAMBDA)

[fit_options]
  method  = focei
  maxiter = 300

See examples/tte_weibull.ferx and examples/tte_gompertz.ferx for complete Weibull and Gompertz examples using this compact syntax.

DV coding

DV	Meaning
`0`	Right-censored
`1`	Exact event at this TIME
`2`	Interval-censored right bound (pair with a preceding DV=0 row on same CMT)

TENTRY column

Add TENTRY to the data file to apply left-truncation (delayed entry): the likelihood conditions on survival past TENTRY.

Time-to-Event Endpoints ([event_model])