NONMEM#

Note

This section is for NONMEM documentation. The information is intended for non-documented or hard-to-find information that is important for pharmpy developers.

Dataset#

Overview of parsing and translation steps#

Removing commented rows
Splitting a row into data items
IGNORE/ACCEPT of rows
Dropping of columns
Error handling of non valid items
Translating TIMEs and DATEs

NM-TRAN dataset parsing#

Some rules for the parsing of the dataset by NM-TRAN. These were tested with NONMEM 7.4.3

Delimeter between items is comma, space or TAB.
Spaces before or after a comma are ignored
Spaces after a TAB are ignored
Spaces before a TAB gives ERROR (sic!)
Spaces in the beginning or of a row are ignored
Comma in the end or beginning of a row will insert NULL after or before the comma
Each item can only be numeric i.e. no other characters than Ee+-0123456789 are allowed except for TIME, II, DATE, DATx columns
The fortran short form for exponential notation is allowed, i.e. 2-1 means 2e-1 and 2+1 means 2e1
A “D” or “d” instead of “E” or “e” are allowed in exponential notation.
A lone + or - in an item means 0
A . (dot) in an item means NULL
An item can be at most 24 characters long, not counting delimiters and spaces that was eaten by other delimiter
Empty lines in a dataset will give an error if not BLANKOK is set in $DATA then NULLs are inserted
As empty lines are counted empty lines and lines only containing spaces and TABs.
Columns that are DROPed in $INPUT can contain any characters and there is no limit to length of items in such a column
If any line has more columns than $INPUT all extra columns are considered to be DROPed

Comment lines (IGNORE=c)#

Lines starting with the comment regex will be removed from the dataset.

If no IGNORE=c has been provided the default regex is ^#
If IGNORE=c where c is not @ the rexex is ^c
If IGNORE=@ the regex is ^\s*[a-zA-Z#]

NULL items in datasets#

A NULL item is an item in a dataset that is either a ., surrounded by two TABS or two commas. By default NM-TRAN translates a NULL item to a blank field in FDATA which will be interpreted by NONMEM as 0. Using the NULL option to $DATA the default can be changed. However the NULL option is limited to one character and the only legal ones are [0-9-+] since these are numbers. All other values on $DATA will be met with ERROR from NM-TRAN. A double comma or tab at the end of a row will insert a value at the end after giving a big warning. If the number of columns in $INPUT is larger than the length of some row, NM-TRAN will warn and pad with NULLs. NULL items are inserted after the IGNORE filtering so comment characterscannot be inserted using NULL neither can the IGNORE/ACCEPT filter on NULL.

IGNORE/ACCEPT#

Some rules for the IGNORE/ACCEPT option in $DATA:

IGNOREs are performed one at a time in the order given. Order is critical in cases where an illegal item gets ignored before it needs to be parsed (i.e. because of a later numeric comparison)
It is possible to IGNORE on a dropped column
IGNORE is done before the error check for .EQ. and .NE., i.e. rows with text can be ignored, otherwise the column will be parsed before ignore and give errors appropriately
Text IGNORE (i.e. .EQ. and .NE.) can contain letter + alphanum/underscore or a real number (no special fortran format), + or - (meaning 0), no digit at start, no ., = has to be enclosed in ‘ or “. Other special characters are ok with or w/o “’.
With others .EQN, .GE. etc can only use numbers
A text/number to IGNORE can be enclosed in ‘ or “.
A value for comparison can maximum have 12 characters (not counting spaces or ‘,” at start or end)
IGNORE is performed before translating TIME and DATE

TIME#

Time must be non-decreasing for all data records within an individual.

DATE#

The DATE, DAT1, DAT2 and DAT3 are special in that they will affect the TIME column. Even if DATE is DROP it will still affect TIME, but cannot be tabled. If DATE and TIME cannot both be tabled and reentered as datasets.

ID checking#

NM-TRAN will give warnings if it thinks there is a risk of an ID being truncated because NONMEM will encode IDs as doubles. Here is a (possibly partial) list of the rules that NM-TRAN use to decide whether to put up a warning:

If the number is written using scientific notation and has 14 or more digits for the mantissa (in decimal) not counting starting zeroes
If the number is written using non-scientific notation and has 14 digits or more not counting starting zeroes or trailing zeroes after the decimal point.

table files#

This section describes output tables generated by $TABLE

cov, cor and coi files#

These are the output of the NONMEM covariance step and will only contain one table for the final estimation (as opposed to phi and ext that will have one table per $EST). The first column called NAME will have contain the parameter names starting in the order THETA, SIGMA, OMEGA. FIX parameters will have all values 0. All offdiagonals for omegas and sigmas will be in the table. The ones that was not used will have all values 0.

phi files#

File format#

The default format (could this be changed?) of the table part (except the TABLE NO. lines) of a phi-file (probably the same for other types, but for now only phi has been investigated) is as follows: First the column header line that is formatted like this:

One space
All the column names, except the last one, left justified with a field size of 13 characters
The final column name

The column names are

SUBJECT_ID
ID
One column per ETA of the model named ETA(n) where n is the number of the ETA starting from 1.
A flattened triangular correlation matrix with columns ETC(1,1), ETC(2,1) up to ETC(n,n) with same n as above and all off diagonals given.
OBJ

The data is right justified with a field size of 13 characters (padded with spaces). Except for the final OBJ column that is also right justified, but with a field size of 22 characters.

The number format is integer for the first two columns, scientific with 5 decimals and 2 digits exponent for the ETA and ETC columns. The number in the OBJ column is written in regular decimal format and will always take up 19 characters with first character being space for positive numbers or “-” for negative numbers. For numbers having an integer part of zero will take up 20 characters.

In case of non-integer IDs in the dataset the value in the ID-column will be truncated.

All zero individuals#

Individuals with no observations will have zeroes in all columns except the SUBJECT_ID and the ID columns

PHI/PHC#

For EM-algorithms the phi file will have PHI insead of ETA and PHC instead of ETC. PHI and PHC can be used to calculate ETA and ETC.

$\phi_1 = \mu_1 + \eta_1$

PHI(1) = MU_1 + ETA(1)

In case of no mu-referencing MU_i is implicitly 0.

PHC and ETC are equivalent if MU_i is non-random.

PHC(i,i) = $\operatorname{Var}(\phi_i) = \operatorname{Var}(\mu_i + \eta_i) = \operatorname{Var}(\eta_i)$ = ETC(i,i)

PHC(i,j) = $\operatorname{Cov}(\phi_i, \phi_j) = \operatorname{Cov}(\mu_i + \eta_i, \mu_j + \eta_j) = \operatorname{Cov}(\eta_i, \eta_j)$ = ETC(i,j)

control stream#

general#

NULL bytes are allowed in the control stream and evidence points towards it being tokenized as whitespace

options parsing#

Option values that must be enclosed in parentheses can be split over multiple lines as long as the opening parentheses is on the same line as the keyword and that each token is kept on one line. For example

$DATA file.csv IGNORE=(
   WGT
   .EQ.23
   ,
   WGT.EQ.22
   )

$PROBLEM#

Title text is only allowed on the same line as the $PROBLEM. Putting it on other lines will crash NMTRAN. Whitespace before the first text is not part of the title. There can be no comments on the title line, i.e. comments will be part of the title. The title can maximum be 72 characters including space. Characters coming after the 72 will be ignored.

$DATA#

If filename represents a relative path it is relative to the working directory when invoking nmfe. Multiple $DATA records are allowed in one $PROBLEM. All contents are simply seen as part of one and the same $DATA record.

$ETAS#

The filename (not the path) for the FILE option in $ETAS can have a maximum of 54 characters (tested with NONMEM 7.4.3). The provided phi-file does not need to have the ETC or OBJ columns.

Code records#

NM-TRAN allows multiple $PK, $PRED and $ERROR in a model. They simple get merged into one big record in the order they have in the control stream. As long as the first $PK/$PRED/$ERROR follows the regular placement rules the others can be placed at any position after that.

Code lines#

NONMEM 7.4 does not seem to have a restriction of the line length as NM-TRAN automatically creates continuation lines. Limiting factor is then the number of continuation lines allowed by the compiler. A 11138 characters long line was tested, which generated 445 continuation lines. Even though outside the fortran standards this worked with gfortran 8.3.

Derivatives#

In verbatim code in $ERROR HH(n,j*neps+i) (in $PRED it is called H) will be the second partial derivative of F(n) with respect to EPS(i) and ETA(j)

Abbreviated and verbatim code#

NM-TRAN sets

IMPLICIT REAL(KIND=DPSIZE) (A-Z)

for the main functions in FSUBS (checked $PK and $ERROR) so variables starting with letters from A-Z doesn’t need to be declared, not even in abbreviated code. However if a variable only used in verbatim code is to be used in $TABLE it must be assigned a value in abbreviated code.

Results file format#

Sparse matrix format#

Lines:

Empty line
Name line
Value line
…
Stop line

The name and value lines will have 7 entries each, except for the final lines. The name line will have abbreviated symbols for the parameters separated by ‘ | ‘. The abbreviated symbols will be THnn for THETA where nn will be the number or ‘ n’ if only one digit, ‘OMaabb’ or ‘SGaabb’ for OMEGA or SIGMA, where aa and bb are zero padded matrix indices. Fixed parameters will not be added to the sparse matrix. The value line will be space separated values in scientific notation. For NONMEM 7.4.3 only x.xxE-xx are possible, but NONMEM 7.5 $FORMAT can change the number of digits here. The stop line contains only the string ‘1’.

NONMEM#

Dataset#

Overview of parsing and translation steps#

NM-TRAN dataset parsing#

Comment lines (IGNORE=c)#

NULL items in datasets#

IGNORE/ACCEPT#

TIME#

DATE#

ID checking#

table files#

Header#

cov, cor and coi files#

phi files#

File format#

All zero individuals#

PHI/PHC#

control stream#

general#

options parsing#

$PROBLEM#

$DATA#

$ETAS#

Code records#

Code lines#

Derivatives#

Abbreviated and verbatim code#

Results file format#

Sparse matrix format#