NONMEM_template_control_file

NONMEM template control file syntax

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

Model file names: Follow the ‘Uppsala convention’ of naming model files like run1.mod, run2.mod, etc. Users of PsN and Xpose4 typically do this and it 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.

File extensions: 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.

Model description: 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.

Reference model: To use the hierarchy functionality for models, specify the reference model in the first few lines of the control file. It is best to use PsN’s run record specification, but Pirana is flexible, compatible with Census, and understands the following syntaxes:

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

Parameter descriptions: Model parameter descriptions must follow a semi-colon, e.g.,

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

Pirana reads these descriptions from the control file (not from the output file). To be read correctly, covariance blocks 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

Compilation files: Files needed for compilation when models are executed in a separate directory (e.g., additional Fortran routines in .FOR files) should be specified in the OTHER and CONTR entries on the $DATA record. Pirana copies these files automatically.

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, …

Xpose4 files: In general, four table files need to be specified to support most of Xpose4 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
The “1” in “FILE=sdtab1” 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

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