Nonmem

NONMEM

A working skill for editing and reasoning about NONMEM control streams, datasets, and outputs. Assume the user knows pharmacometrics; the value here is consolidating the rules that frequently bite people — dataset events, MU referencing, estimation-method choice, and output-file structure.

What's in this skill

• This file: the daily-driver reference. Workflow, control-stream skeleton, dataset rules, MU referencing, method choice, output files.
• references/control-records.md: detailed syntax of common $-records.
• references/advan-trans.md: when to pick which ADVAN/TRANS and what parameters they require.
• references/diagnostics-vpc.md: VPC and pcVPC workflow, residual diagnostics, shrinkage.
• references/common-errors.md: the error messages that come up over and over and how to fix them.

Read this file first. Pull in references only when the task needs that depth (e.g. picking ADVAN for a stiff ODE system → advan-trans.md).

Workflow

When the user asks for help with a NONMEM task, work in this order:

1. Read what they have. If a .ctl (or .mod/.nm) file is mentioned or pasted, look at it before suggesting changes. The structure of the existing model tells you what ADVAN/TRANS is in play, what's MU-referenced, what error model is being used, and which estimation method is set. Don't propose changes that conflict silently with what's already there.
2. Read the data layout. A control stream cannot be evaluated without the $INPUT line and ideally a sample of the dataset. Dose/observation interleaving, EVID values, RATE vs II/ADDL — these change what the model is actually doing.
3. Identify the goal. "Add a covariate", "switch to SAEM", "fix the round-off error in $COV", "set up a VPC" — each has a standard playbook below or in references.
4. Make minimal, syntactically valid edits. NM-TRAN is strict. Trailing characters, the wrong record order, a comment that exceeds the column limit — any of these can break a run silently or with a cryptic error. When editing, preserve indentation and comments.
5. Sanity-check the change. Before declaring done: do the THETA/ETA/EPS indices still line up? Do $OMEGA and $SIGMA have the right dimension for the references in $PK/$ERROR? Is the data file readable with the new $INPUT?

Control-stream skeleton

A minimal population PK control stream looks like this. The record order shown is conventional and safe:

$PROBLEM Two-compartment IV, FOCE-I
$INPUT   ID TIME AMT RATE EVID MDV CMT DV WT
$DATA    data.csv IGNORE=@
$SUBROUTINES ADVAN3 TRANS4

$PK
  TVCL = THETA(1) * (WT/70)**0.75
  TVV1 = THETA(2) * (WT/70)
  TVQ  = THETA(3) * (WT/70)**0.75
  TVV2 = THETA(4) * (WT/70)

  CL = TVCL * EXP(ETA(1))
  V1 = TVV1 * EXP(ETA(2))
  Q  = TVQ  * EXP(ETA(3))
  V2 = TVV2 * EXP(ETA(4))

  S1 = V1   ; scale central compartment so A(1)/V1 has concentration units

$ERROR
  IPRED = F
  Y     = IPRED * (1 + EPS(1)) + EPS(2)   ; combined proportional + additive

$THETA
  (0, 5)    ; [1] CL  (L/h)
  (0, 30)   ; [2] V1  (L)
  (0, 10)   ; [3] Q   (L/h)
  (0, 50)   ; [4] V2  (L)

$OMEGA
  0.1       ; [1] IIV CL
  0.1       ; [2] IIV V1
  0.1       ; [3] IIV Q
  0.1       ; [4] IIV V2

$SIGMA
  0.04      ; [1] proportional
  0.01      ; [2] additive

$ESTIMATION METHOD=COND INTERACTION MAXEVAL=9999 PRINT=5 NOABORT
$COVARIANCE UNCONDITIONAL MATRIX=R PRINT=E
$TABLE ID TIME DV PRED IPRED CWRES IWRES NPDE CL V1 Q V2 ETA1 ETA2 ETA3 ETA4
       NOPRINT NOAPPEND ONEHEADER FILE=run001.tab

Things people get wrong about this skeleton:

• $INPUT labels are positional: NM-TRAN reads the dataset columns in this order and assigns them these names. Reserved labels (ID, TIME, AMT, RATE, EVID, MDV, CMT, DV, SS, II, ADDL, L1, L2, PCMT, CONT, DATE, DAT1–DAT3, CALL) trigger special behavior in PREDPP. Non-reserved labels are just column names. To rename, use X=Y (e.g. CONC=DV). To drop, use X=DROP.
• $DATA file.csv IGNORE=@ skips records starting with any letter — the most common idiom for skipping a header row. IGNORE=C skips records starting with C, which pairs with putting C in the first column on $INPUT for comment lines.
• The order matters: $INPUT must come before any record referring to data items by name. $SUBROUTINES must precede $PK/$ERROR. $THETA/$OMEGA/$SIGMA come after $PK/$ERROR so NM-TRAN can index the references.
• THETA references in $PK/$ERROR are 1-indexed and must match the number of entries in $THETA. Same for ETA ↔ $OMEGA and EPS ↔ $SIGMA.
• S1 = V1 is the scaling for compartment 1. With TRANS4 (ADVAN3) the central compartment is #1; the predicted amount A(1) is divided by S1 to give concentration. Forgetting Sn is one of the most common causes of "values look 1000× off".
• Comments after ; are ignored. Keep parameter labels in comments (; [1] CL) — they survive into the .lst and make debugging much faster.

Dataset conventions — the part that breaks most often

NONMEM datasets are event-record-oriented, not subject-row-oriented. Each row is one event for one subject at one time. The interpretation of the row depends on EVID:

Rules that consistently trip people up:

• A dose row and an observation row cannot share the same TIME and same record. They must be separate rows. A common pattern is dose at t=0 (EVID=1, AMT>0, DV=0) followed by an observation at t=0 (EVID=0, AMT=0, DV=observed_value).
• Bolus dose: AMT > 0, RATE = 0 (or omit RATE), EVID = 1.
• Zero-order infusion (rate-specified): AMT > 0, RATE > 0. NONMEM computes duration as AMT*F1/RATE.
• Zero-order infusion (duration-specified): RATE = -2 and duration is modeled in $PK via D1, D2, etc.
• Model-derived rate: RATE = -1 and R1 etc. modeled in $PK.
• Steady state: SS = 1 (steady-state dose at this row, prior history cleared), SS = 2 (steady-state superimposed on prior history), with II = dosing interval. For an IV infusion to steady state, use SS=1, II=tau, and the appropriate AMT/RATE.
• Additional doses: ADDL = n (n additional doses), II = interval. NONMEM will generate the n implicit additional events at t, t+II, t+2*II, … without needing rows for them.
• MDV: Missing Dependent Variable. MDV = 1 means "ignore DV on this row". NONMEM appends MDV automatically if absent, but if it's present, it's authoritative. MDV = 1 is required on any non-observation row (doses, resets, covariate events) when DV happens to be populated. As of NONMEM 7, if MDV is in $INPUT but EVID is not, NM-TRAN sets EVID=2 (other event) on non-dose, MDV=1 rows — not EVID=0.
• CMT: which compartment the event acts on. For ADVAN3 (two-comp IV), the central compartment is #1, peripheral is #2, output is #3. For ADVAN4 (oral two-comp), depot is #1, central is #2. Get this wrong and dose goes into the wrong place silently.
• ID: must group all rows for one subject contiguously. Same ID value separated by a different ID is treated as two different subjects (this is occasionally useful but usually a bug).
• Sort order within an ID: monotonically increasing TIME, except where a reset (EVID=3 or 4) explicitly resets time.

For multi-occasion designs where each subject has multiple administration episodes that should share ETAs but reset compartments, use EVID=4 at the start of each occasion (reset + dose) and define a composite ID like BIO_ID*100 + OCC with a bio_map to share inter-individual variability across occasions.

MU referencing — required for EM/Bayes, optional for FOCE

The new estimation methods (ITS, SAEM, IMP, BAYES, NUTS) need to know which THETAs define the population mean of each ETA. The convention is:

  PHI(j) = MU_j(THETA) + ETA(j)
  CL = EXP(MU_3 + ETA(3))     ; if log-normal IIV

To MU-reference a parameter, define MU_j as a function of THETAs only (no ETAs, no record-varying covariates that don't map cleanly to a single THETA), then write the individual parameter as EXP(MU_j + ETA(j)) for log-normal IIV. Example:

  MU_1 = LOG(THETA(1)) + THETA(5)*LOG(WT/70)
  MU_2 = LOG(THETA(2)) + THETA(6)*LOG(WT/70)
  CL   = EXP(MU_1 + ETA(1))
  V1   = EXP(MU_2 + ETA(2))

Linear MU referencing is preferred. If you write MU_1 = THETA(1) + THETA(5)*LOG(WT/70) (THETAs entering linearly), the EM update step becomes a one-step linear regression and is much more robust. To keep this linear form while still entering THETA(1) on the natural (un-logged) scale, log-transform the initial value rather than wrapping LOG() inside the MU equation.

Rules and gotchas:

• Each MU_j corresponds to exactly one ETA(j). If you have IIV on CL via ETA(3), you write MU_3, not MU_1.
• A THETA that has no ETA associated with it is not MU-referenced — that's fine, EM still works, just less efficiently for that parameter.
• Covariates that change within a subject (record-varying WT for time-varying BSA, for example) generally cannot live inside a MU equation. Pull the covariate effect outside: CL = WT**THETA(5) * EXP(MU_1 + ETA(1)) with MU_1 = LOG(THETA(1)).
• NM-TRAN catches some MU-referencing errors but not all. If an EM run is slow or unstable, the first suspect is broken MU referencing.
• FOCE/FOCEI/Laplace ignore MU references — they're harmless to include and useful for keeping a single control stream compatible with multiple methods.
• In PyMC/HMC the non-centered parameterization (eta_raw ~ N(0, 1), eta = omega * eta_raw) is the structural analog: NUTS benefits from decoupled posterior geometry, NONMEM's EM benefits from linear update steps. They're aimed at the same problem (hierarchical posterior geometry) but exploit it differently.

Estimation methods — choosing the right one

Common idioms:

• SAEM then IMP for final OFV: SAEM converges fast but doesn't give the true OFV directly. Follow it with an IMP step that uses EONLY=1 (expectation only, no maximization) to compute the marginal likelihood OFV at the SAEM-converged parameters.
• MSFO/MSFI for restart: MSFO=run001.msf writes a model specification file at the end of estimation; the next problem can MSFI=run001.msf to pick up exactly where it left off. Useful for SAEM → IMP chains.
• Multiple $EST records: Each subsequent $EST uses the previous one's final estimates as starting values. So $EST METHOD=ITS NITER=100 followed by $EST METHOD=SAEM NBURN=500 NITER=500 followed by $EST METHOD=IMP EONLY=1 NITER=10 ISAMPLE=3000 is a typical EM workflow.
• Convergence tests during exploration: Disable them. EM convergence tests can keep running excessively or end prematurely; better to fix NITER during initial development.

Initial settings to start with for unfamiliar problems:

$EST METHOD=ITS  NITER=100
$EST METHOD=SAEM NBURN=500 NITER=500
$EST METHOD=IMP  NITER=100 ISAMPLE=300

If a 3+ compartment ODE model takes hours under FOCE, it's almost always worth porting it to MU-referenced IMP or SAEM — speedups of 5–10× are common.

Output files

After a successful run, the following files appear (root = control-stream name without extension):

• root.lst (or .res) — the human-readable report. Final estimates, OFV, standard errors, covariance matrices, run statistics.
• root.ext — raw output table: every iteration's parameter values plus the final line. Easy to parse for trace plots.
• root.phi — individual parameter estimates: PHI(i) = MU(i) + ETA(i), and their variances. One row per subject (or per occasion if L2 is used).
• root.cov — full variance-covariance matrix of THETA/SIGMA/OMEGA estimates.
• root.cor — correlation matrix; diagonals are standard errors, off-diagonals are correlations.
• root.coi — inverse covariance (Fisher information) matrix.
• root.tab (and any other $TABLE FILE= outputs) — predictions, residuals, individual parameters at each event.
• root.shk — eta/eps shrinkage.
• root.xml — XML summary of the run, useful for programmatic post-processing.
• root.msf — model specification file (only if MSFO= was set).

Quick interpretation cues from .lst:

• "MINIMIZATION SUCCESSFUL" — FOCE found a local optimum. No guarantee it's global.
• "ROUNDING ERRORS" — gradient evaluation hit precision limits. Often genuine convergence but with caveats. Try SIGL= lower, or switch to EM.
• "DUE TO PROXIMITY OF NEXT ITERATION EST. TO A VALUE AT WHICH THE OBJ. FUNC. IS INFINITE" — usually a boundary issue. Check that initial estimates aren't at the lower bound of THETA.
• "$COV step aborted" — R or S matrix is singular or non-positive-definite. Often a sign of over-parameterization or correlation near 1 between two parameters. Inspect root.cor.
• Condition number (in .lst near the bottom of $COV): >1000 is concerning, >10000 suggests serious identifiability issues.

For details on each file's format and how to use them, see references/output-files.md.

VPC and pcVPC

For a Visual Predictive Check, the standard workflow is:

1. Run the estimation to convergence.
2. Build a simulation control stream using $SIMULATION SUBPROBLEMS=n ONLYSIM with NSUB= typically 200–1000 replicates of the original dataset. Same $PK, $ERROR, $THETA, $OMEGA, $SIGMA fixed at the estimated values. Output DV, IPRED, PRED, TIME, ID, and any binning/stratification variables to $TABLE.
3. For each time bin, compute the 5th/50th/95th percentile of simulated DV. Plot these as ribbons/lines, with observed percentiles overlaid.
4. If dose adjustments or adaptive designs are present, use prediction-corrected VPC (pcVPC): divide each observation by the typical population prediction at that bin's median time, and do the same for simulations. This removes the variability from binning across heterogeneous dose/covariate values and is essential when there's a posteriori dose adaptation (TDM) or wide variation in the dosing regimen.

Holford/Bergstrand conventions for the figure: bins narrow enough that within-bin variability is small but wide enough that each bin has ≥10 observations; show observed 5/50/95 as lines and simulated 5/50/95 as shaded confidence intervals (typically the 95% CI of each percentile across simulation replicates).

See references/diagnostics-vpc.md for the worked formulas and tips on BQL handling, dose-adaptive corrections, and stratification.

Common errors and recovery

A short list; the full table is in references/common-errors.md.

• "FILE RECORD MISSING" — almost always means NONMEM was handed an NM-TRAN control stream ($PROBLEM ...) instead of the FCON file that NM-TRAN produces. Run NM-TRAN first (typically nmfe74 run001.ctl run001.lst).
• "TOO MANY OBSERVATIONS PER INDIVIDUAL" — bump LIM6 in $SIZES or split the subject.
• PRED EXIT CODE 1 — fatal error in $PK or $DES. Almost always division by zero, log of a non-positive number, or an EXP overflow. Add guards.
• OFV is "INF" or NaN — usually a SIGMA combined model with both proportional and additive going to zero. Or IPRED ≤ 0 getting fed into a proportional residual. Add W = SQRT(SIGMA(1,1)*IPRED**2 + SIGMA(2,2)) style guards.
• Convergence "failed" but parameters look reasonable — for EM/Bayes, this often just means the stochastic test couldn't certify convergence within the iterations given. Re-run with MASSRESET=1 or more iterations. Inspect the .ext trace.

Cross-references within this skill

• For exhaustive $-record syntax: references/control-records.md.
• For "which ADVAN/TRANS should I use for a 3-compartment IV with depot": references/advan-trans.md.
• For VPC computation, NPDE, shrinkage interpretation: references/diagnostics-vpc.md.
• For error messages and recovery: references/common-errors.md.

External references the user already has in the project

• intro7.pdf — NONMEM 7.6.0 introduction (comprehensive feature list, MU referencing details, new method options).
• NONMEM7_Technical_Guide.pdf — algorithmic details for FOCE, Laplace, EM methods.
• Bauer 2019 CPT-PSP Tutorial Parts I and II — the most accessible reference for control-stream construction and method selection.
• User Guides I (Basic), II (Supplemental), III (Detailed Methods Guide), IV (NM-TRAN), V (Introductory Guide), VI (PREDPP), VII (Conditional Estimation), VIII (Help Guide / detailed record descriptions).
• pcvpc.pdf (Bergstrand 2011) and A_stepbystep_guide_to_prediction_corrected_visual_predictive_checks_VPC_of_NONMEM_models___PMX_Solutions.pdf — pcVPC theory and worked R example.

Prefer pointing to these for material this skill summarizes briefly. The user guides are the authoritative reference for any record-level question.