NONMEM template control file syntax

There are some important syntax rules to following in the NONMEM template control file that make Pirana/PsN/Xpose4 work best together. These involve tags, parameters, and naming rules for output tables.

Users of PsN and Xpose4 likely follow the ‘Uppsala convention’ of having model files named like run1.mod, run2.mod, etc. This is recommended for Pirana users as well, although Pirana is flexible in this respect. Note that Pirana removes the run from the model file name in the model overview.

Use the default file extensions to ensure that the programs recognize the necessary files. For example: .mod for NONMEM model files, .tab for NONMEM $TABLE data, .mmdl for NLME metamodel files, .mdl for NLME model files.

Pirana looks for a description of the model in the first part of the control file. It adheres to PsN’s run record standards. If the PsN run record is not used, Pirana searches for the words “$PROBLEM” or “Model desc:” to extract the model description.

If you want to use the hierarchy functionality for models, you should specify the reference model in the first few lines of the control file. Again, it is best to use PsN’s run record specification, but Pirana is flexible and also compatible with Census, and understands the following syntaxes:

      ;; 1. Based on: 001.mod
      ; Ref. model:001.mod
      ; Ref:001.mod
      ; Parent=001.mod

Model parameter descriptions need to be specified after a semi-colon, e.g.,

      $THETA
      (3, 5, 11) ; CL/F
      (10, 50, 100) ; V/F

Note that Pirana reads these descriptions from the control file (and not from the output file). To be read correctly, covariance block need to be specified as:

      $OMEGA BLOCK(2) 0.1 ; IIV CL/F
      0.05 ; COV CL~V 0.1 ; IIV V/F

or as:

      $OMEGA BLOCK(3)
      0.1           ; IIV CL/F
      0.05 0.1      ; IIV V/F
      0.01 0.05 0.1 ; IIV KA

When models are to be executed in a separate directory, files needed for compilation (e.g., additional Fortran routines in .FOR files), are copied automatically by Pirana. These files should be specified in the OTHER and CONTR entries on the $DATA record. If additional files are needed, you can instruct Pirana to copy these by adding this line to your control stream:

      ; INCLUDE=file1_to_be_copied.ext,file2_to_be_copied.ext, …

Note that PsN has its own functionality for doing this.

In general, Xpose4 needs four table files to be specified to support most of its diagnostic plotting capabilities:

sdtab: Standard output table that includes all time records, e.g.,

         $TABLE ID TIME IPRED IWRES CWRES EVID MDV NPD NPDE NOPRINT 
             ONEHEADER FILE=sdtab1 

(Note the “1” affixed to the “FILE=sdtab1” — this corresponds to the run number for the file.)

patab: Parameter table for model parameters, one record per parameter set per individual, e.g.,

         $TABLE ID CL V KA TVCL TVV TVKA ETA1 ETA2 ETA3 NOPRINT ONEHEADER 
             FILE=patab1 

cotab: Continuous covariate table for continuous covariate variables, e.g.,

         $TABLE ID WT AGE CLCR NOPRINT ONEHEADER FILE=cotab1 

catab: Categorical covariate table for categorical covariates, e.g.,

         $TABLE ID SEX RACE FOOD NOPRINT ONEHEADER FILE=catab1 

NONMEM template control files, when planning to use the Results > Run records > Run record (PsN) function, are considered to be full templates, as they contain the model and all of the additional information that will become part of the run record output. The short template has the model information only.