NONMEM cheat sheet

A concise, accurate reference for NM-TRAN control streams — the blocks, ADVAN/TRANS subroutines, estimation methods, error models, and dataset items you use across the course. Every fact here is what the lessons teach and the engine runs.

Control-stream blocks ADVAN / TRANS $PK parameters Estimation methods Error models Random effects Dataset items Dosing & steady state Diagnostics Common gotchas

Control-stream blocks

An NM-TRAN control stream is a sequence of $-records. A minimal PK run needs $PROBLEM, $INPUT, $DATA, a structural model, $THETA/$OMEGA/$SIGMA, and $ESTIMATION.

BlockPurpose
$PROBLEMFree-text title for the run.
$INPUTNames the columns of the data file, in order (e.g. ID TIME AMT DV MDV EVID).
$DATAPath to the dataset; IGNORE=@ skips header/alpha rows.
$SUBROUTINESSelects the structural model, e.g. ADVAN2 TRANS2 (or ADVAN6/8/13 for $DES).
$MODELDefines compartments for general (ADVAN5/6/7/…) models.
$PKComputes PK parameters (CL, V, KA…) from THETA/ETA and covariates.
$DESODE right-hand sides (DADT(i)) for differential models.
$ERRORLinks the prediction F to the observation Y via EPS (residual error).
$THETAFixed-effect initial estimates (typical values), with optional bounds and FIX.
$OMEGAVariance–covariance of the ETAs (between-subject variability).
$SIGMAVariance of the EPSs (residual error).
$ESTIMATIONChooses the method (METHOD=COND, INTER, LAPLACIAN, SAEM…) and controls.
$COVARIANCERequests standard errors / the covariance step.
$TABLEWrites requested columns (PRED, IPRED, CWRES, ETAs…) for diagnostics.

ADVAN / TRANS quick reference

ADVAN picks the structural model; TRANS picks the parameterization it expects. Closed-form ADVANs are fast; ADVAN6/8/13 integrate $DES ODEs numerically.

ADVANModelTypical TRANS & parameters
ADVAN11-cmt, IVTRANS2: CL, V
ADVAN21-cmt, first-order absorptionTRANS2: CL, V, KA (depot = cmt 1)
ADVAN101-cmt, Michaelis–Menten eliminationVM, KM, V
ADVAN32-cmt, IVTRANS4: CL, V1, Q, V2
ADVAN42-cmt, first-order absorptionTRANS4: CL, V2, Q, V3, KA
ADVAN113-cmt, IVTRANS4: CL, V1, Q2, V2, Q3, V3
ADVAN123-cmt, first-order absorptionTRANS4 + KA
ADVAN5 / ADVAN7General linear (any compartment layout)Rate constants K12, K21, … via $MODEL
ADVAN6 / ADVAN8 / ADVAN13General nonlinear ODE$DES with DADT(i); 6 non-stiff (DVERK), 8 stiff (Gear), 13 (LSODA) auto-switches — the robust default

With TRANS1 you supply micro-constants directly (K, K12, K21…) instead of clearances. Scaling: define S1=V (or S2=V2) so concentration = amount ÷ volume.

$PK parameters & a canonical deck

Reserved names

  • CL, V, V1, V2, V3, Q, Q2, Q3, KA — disposition parameters
  • S1, S2, S3 — scaling (amount → concentration) per compartment
  • F1, D1, R1, ALAG1 — bioavailability, infusion duration, rate, lag time for compartment 1
  • KE0 — effect-compartment equilibration rate

Individual-parameter form

  • Log-normal (default): CL = THETA(1)*EXP(ETA(1))
  • Additive: P = THETA(1) + ETA(1)
  • Proportional/CV: P = THETA(1)*(1+ETA(1))
  • Allometric covariate: CL = THETA(1)*(WT/70)**THETA(3)*EXP(ETA(1))
; 1-compartment oral popPK, first-order absorption
$SUBROUTINES ADVAN2 TRANS2
$PK
  CL = THETA(1)*EXP(ETA(1))
  V  = THETA(2)*EXP(ETA(2))
  KA = THETA(3)*EXP(ETA(3))
  S2 = V                     ; central cmt is #2 in ADVAN2
$ERROR
  IPRED = F
  Y = IPRED*(1 + EPS(1)) + EPS(2)   ; combined error

Estimation methods

Set on $ESTIMATION. INTER adds eta–epsilon interaction (turns FOCE into FOCEI) — it is never automatic and matters when the residual variance depends on the prediction.

MethodWhat it isWhen
METHOD=ZERO (FO)First-order; linearizes at ETA=0Fast, rough starting fit
METHOD=COND (FOCE)Conditional; linearizes at each subject's ETAWorkhorse for continuous data
METHOD=COND INTER (FOCEI)FOCE + eta–epsilon interactionProportional/combined error models
METHOD=COND LAPLACIANSecond-order Laplace approximationNon-normal / categorical / count likelihoods
METHOD=SAEMStochastic approximation EM (Monte-Carlo)Complex / multimodal, many random effects
METHOD=IMPImportance samplingObjective refinement, often after SAEM

Residual error models

Written in $ERROR, linking prediction F to observation Y through EPS (whose variance lives in $SIGMA).

Model$ERROR
AdditiveY = F + EPS(1)
ProportionalY = F*(1 + EPS(1))
CombinedY = F*(1 + EPS(1)) + EPS(2)
Log / exponentialY = LOG(F) + EPS(1) (with log-transformed DV)

Noncontinuous & general-likelihood models

Categorical, count and time-to-event data have no residual EPS. Set F_FLAG=1 and make Y the likelihood of the observed record, then fit with $ESTIMATION METHOD=COND LAPLACIAN (the Laplace approximation to the exact likelihood).

Data typeHow Y is built (with F_FLAG=1)
Binary (logistic)P = EXP(LP)/(1+EXP(LP)); Y = DV*P + (1-DV)*(1-P)
Count (Poisson)Y = Poisson probability of DV given mean LAM (e.g. Y = EXP(-LAM)*LAM**DV/EXP(GAMLN(DV+1)))
Ordered categoricalcumulative logits with monotone cut-points; Y = P(observed level) as a difference of cumulative probabilities
Time-to-eventintegrate the hazard to a cumulative hazard CUMHAZ in $DES; SUR=EXP(-CUMHAZ); event record Y = HAZ*SUR, censored record Y = SUR
Below-LOQ (M3)for BLQ=1 records, Y = PHI((LLOQ - IPRED)/W) — the probability the observation is below the limit (censored likelihood)

Random effects: $OMEGA & $SIGMA

$OMEGA (between-subject)

  • Diagonal: $OMEGA 0.09 0.09 — independent ETAs
  • Correlated: $OMEGA BLOCK(2) 0.09 0.01 0.09
  • IOV (inter-occasion): repeat $OMEGA BLOCK(1) 0.09 then $OMEGA BLOCK(1) SAME per occasion — one shared variance across occasions
  • An ETA's variance ≈ CV² for a log-normal parameter at small values

$SIGMA (residual)

  • One EPS per error term: $SIGMA 0.04
  • FIX a value to hold it constant: $SIGMA 1 FIX
  • Interaction (FOCEI) is what makes prediction-dependent SIGMA correct

Dataset items (reserved $INPUT names)

ItemMeaning
IDSubject identifier (groups records into individuals).
TIMETime of the record.
AMTDose amount (on dosing records).
DVDependent variable — the observation.
MDVMissing DV flag: 1 on dose/other non-observation records.
EVIDEvent ID: 0 = observation, 1 = dose, 2 = other, 3 = reset, 4 = reset+dose.
CMTCompartment for the dose or observation.
RATEInfusion rate (or -1/-2 to estimate via R1/D1).
SSSteady-state flag (1 = dose to steady state).
IIInterdose interval (used with SS and ADDL).
ADDLNumber of additional identical doses.

Dosing & steady state

Diagnostics

QuantityMeaning
OFVObjective function value (−2·log-likelihood). Lower is a better fit; a drop of 3.84 for one added parameter is significant at p<0.05 (χ², 1 df).
PRED / IPREDPopulation / individual predictions.
RES / WRES / CWRESResiduals; CWRES (conditional weighted) is the modern standard for continuous data.
NPDENormalized prediction distribution errors — simulation-based, should be N(0,1).
VPCVisual predictive check: simulate from the model, compare observed vs simulated percentiles.
ShrinkageHigh ETA/EPS shrinkage warns that individual estimates are pulled toward the population — read diagnostics with care.

Common gotchas