Speaking NM-TRAN

Published

October 2, 2025

Under construction

Modeling: Writing the control stream

One hint on control files: never write one from scratch. Instead, find a control file that does something similar to what you want to do, and modify it as necessary.

Model structure templates with NONMEM code

For a great resource on model templates, see https://pmxrepo.com. On the website you’ll find example code for various absorption models including:

Dual absorption
Saturable absorption
Weibull
Transit compartments
Linear clearance models
Non-linear clearance models
Time varying clearance models
Various interaction models

There are also multiple residual error models for each model.

General pointers

$ERROR has almost nothing to do with error. It is used to calculate the result. It should really be called $RESULT instead.

When you use F, CMT matters (Credit: Maria Kjellsson)
ETADER=3: Get out of a local minima (Credit: Rikard Nordgren)
Use $COVARIANCE MATRIX=R for consistency between statistical software.
Use EXIT(1) instead of p=0 /+1E-15 (Credit: Gunnar Yngman)
Always code with MU-modeling if possible.
Always add an ETA, even if you don’t intend to use it; then FIX it to 0. This allows for easy estimation of the variability in case you need it, without changing the code.
Avoid temporary variables in the $DES-block. The more code you have there, the slower your model will run.
Proportional RUV is usually only needed if your measurement covers more than 3 orders of magnitude.
- PD biomarkers usually only cover 1–2 orders of magnitude, so only additive RUV is needed.

Protection code

Protection code need not be inserted for every LOG(), EXP(), or SQRT(), but only if your analysis fails frequently or tends to be sensitive to initial values.

Monte Carlo methods create samples of etas from multivariate normal or t-distributions
Extreme eta values may sometimes be selected
Usually extreme ETAs are rejected by MC algorithm
Occasionally, analysis fails because of
- Floating point overflows
- Divide by zero
- Domain errors
Result in failure of the analysis.
EXIT statement allows NONMEM to reject the present set of ETAs
If NOABORT is selected as a $EST setting, NONMEM will attempt to recover and continue.
The EXIT statement causes an error condition index to be set, which is detected by the MLE as well as the EM algorithms.

As of NONMEM 7.4, you can use “protection” functions that avoid the numerical difficulties. For example:

PLOG(X) returns a large negative value when X<=0.0
PEXP(X) returns EXP(40.0) when X>40.0
PSQRT(X) returns 0.0 when X<0.0

Or, simply set at beginning of control stream file: $ABBR PROTECT and all functions will be converted to protected form.

Specific pointers

AUC > MIC

$DES
CONC = A(1) / V ; mass/volume
MIC = 8 ; mass/volume
RT = 0

IF (CONC > MIC) RT=1

DADT(2) = RT ; Time above MIC
DADT(3) = RT * (CONC - MIC) ; AUC > MIC

$ERROR

CP = A(1) / V
TAM = A(2) ; Time Above MIC
AUC = A(3) ; AUC: AUC above MIC

MTIME

Parameter	Description
`MTIME(i)`	The i^th model event time
`MNEXT(i)`	1 if `TIME < MTIME(i)`, otherwise 0
`MPAST(i)`	1 if `TIME > MTIME(i)`, otherwise 0
`MTDIFF`	If `MTDIFF=1` is in $PK, the reset of `MTIME(i)` is indicated

Examples

Example 1: Changing absorption time


$PK 
MTIME(1) = THETA(5) ; change point for KA 

XKA1 = THETA(3) * EXP(ETA(3)) 
XKA2 = THETA(4) * EXP(ETA(4)) 

KA = XKA1 * (1 - MPAST(1)) + XKA2 * MPAST(1)

Example 2: Changing a model time (same as adding event times in the input dataset)


IF (TIME == 0) TEMP = 0 
TEMP = TEMP+1 
MTIME(1) = TEMP 
MTDIFF = 1

MTIME coding increases Tmax precision but increases running time.

$PK

IF (EVID == 1 .OR. EVID == 4) TEMP = 0
TEMP = TEMP + DT
MTIME(1) = TEMP
MTDIFF = 1

$DES

IF (T == TDOS) THEN
  CMAXM =  0
  TMAXM = 0
ENDIF

IF (CP > CMAXM) THEN
  CMAXM = CP
  TMAX = T - TDOS
ENDIF

	Total CPU time(s)
NO MTIME	0.085
DT=5	0.132
DT=2	0.175
DT=0.5	0.372
DT=0.2	0.638
DT=0.1	1.106

Another example:

[To increase the precision of large TTE trial without huge input dataset](https://www.page-meeting.org/pdf_assets/404-Poster_PAGE%20_2014_tte_sim_joakim_nyberg_with_code.pdf)

Time-to-event models

Non-parametric analysis: Log-rank test
Semi-parametric analysis: Cox PH (does not assume a distribution)
Parametric: Weibull, Gompertz, etc (fit a distribution)

Weibull*COV forces proportional hazard (Credit: Andrew Hooker)

TTE simulations can be done either with a dataset containing all possible event times, or using MTIME (Credit: Joakim Nyberg)
logistic=expit=inverse logit
- logit≈probit(scaled)

; This is a comment.

$PROBLEM Example ; Declare a problem called Example

$INPUT
  ID ; We need a variable that uniquely defines a subject
  TIME ; (Independent variable) We need a non-decreasing (within ID) TIME variable
  DV ; (Dependent variable), our observation values
  EVID ; Event ID
  COV=DROP ; Exclude variables with the DROP alias

$DATA dataset.csv IGNORE=@

$SUBROUTINES ADVAN13 TRANS1

$PK

; Assignment & Arithmetic
; =======================

  Z = 1 ; Assign to variable z
  j = 10 + 2 - 3
  a = 11.54 / (2.3 * 3.1)
  b = 2**3 ; Exponentiation

  ; Control Flow Statements & Operators
  ; ===================================

  ; Single-line if statement
  IF (z == a) b = 4 ; Conditions always need parentheses

  IF (z /= a) THEN ; z not equal to a
    ; Other symbolic comparisons are < > <= >= == /=
    b = 4
  ELSEIF (z .GT. a) THEN ; z greater than a
    ; Text equivalents to symbol operators are .LT. .GT. .LE. .GE. .EQ. .NE.
    b = 6
  ELSEIF (z < a) THEN ; "THEN" must be on this line
    b = 5 ; Execution block must be on a new line
  ELSE
    b = 10
  ENDIF

  IF ((x < c .AND. v >= a .OR. z == z)) THEN ; Boolean operators
    IF (.TRUE.) b = 1
  ENDIF

; Built-in Functions
    ; ==================

    ; NMTRAN has many functions/subroutines intrinsic to the language
    ; Examples -
    v = LOG(x) ; log base e

$DES ; "Differential Equation System"

$ERROR ; Should really be called "$RESULT"

  Y = IPRED + EPS(1)

$THETA (0, 1, 10)

$OMEGA 0 FIX

$SIGMA 09

$ESTIMATION METHOD=0 POSTHOC

$COVARIANCE MATRIX=S

$TABLE ID DV TIME

Modeling: Writing the control stream

Model structure templates with NONMEM code

General pointers

Protection code

Specific pointers

AUC > MIC

MTIME

Examples

Time-to-event models

References