Speaking NM-TRAN

Published

August 30, 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

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.) THEN
      b = 1
    ENDIF
  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

References