NONMEM model file parser

Source: R/read_nm_model.R

Parse NONMEM model files in R format

read_nm_model(
  runno = NULL,
  prefix = "run",
  ext = ".lst",
  file = NULL,
  dir = NULL,
  check_ext = TRUE
)

Arguments

runno

Run number to be used to generate model file name. Used in combination with prefix and ext.

prefix

Prefix to be used to generate model file name. Used in combination with runno and ext.

ext

Extension to be used to generate model file name. Should be one of '.lst' (default), '.out', '.res', '.mod' or '.ctl' for NONMEM.

file

Model file name (preferably a '.lst' file) containing the file extension. Alternative to prefix, runno and ext arguments.

dir

Location of the model files.

check_ext

Logical, if TRUE will provide an error message if the extension of the NONMEM input file is not one of '.lst', '.out', '.res', '.mod' or '.ctl' for NONMEM. If FALSE any file extension can be used.

Value

A tibble of class model containing the following columns:

  • problem: a numeric identifier for the $PROBLEM associated with the code.

  • level: a unique numeric identifier to each subroutine block associated with the code.

  • subroutine: a character identifier named after the 3 first letters of the subroutine name e.g. '$THETA' and '$TABLE' will become 'the' and 'tab' respectively. In addition all output from the .lst is labeled 'lst', the general nonmem output e.g. NM-TRAN messages are labelled 'oth'. With priors thp, tpv, omp, opd, sip, spd abbreviations are given to the THETAP, THETAPV, OMEGAP, etc.

  • code: the code without comments or subroutine names e.g. '$THETA 0.5 ; TVCL' will return '0.5'.

  • comment: the last comment of a record e.g. '0.5 ; Clearance (L/h) ; TVCL' will return 'TVCL'.

Details

A NONMEM model output file (i.e. .lst, .out or .res) should preferably be provided to read_nm_model to allow for a more extensive xpose summary. However in some cases these output files may not contain the model code, thus preventing xpose from identifying the associated output tables names. In such cases xpose will attempt to read the associated model file (i.e. .mod or .ctl) instead to find the model code. Note: it is important that between the naming convention between the NONMEM output and the model file remains consistent e.g. run001.lst should be associated with run001.mod.

File path generation

The rules for model file names generation are as follow:

  • with runno: the full path is generated as <dir>/<prefix><runno>.<ext> e.g. with dir = 'model/pk', prefix = 'run', runno = '001', ext = '.lst' the resulting path would be model/pk/run001.lst

  • with file: the full path is generated as <dir>/<file> e.g. with dir = 'model/pk', file = 'run001.lst' the resulting path would also be model/pk/run001.lst. Note: in this case the file extension should be provided as part of the `file` argument.

Examples

if (FALSE) {
# Using the `file` argument to import a model file:
nm_model <- read_nm_model(file = 'run001.lst', dir = 'models')

# Using the `runno` argument to import a model file:
nm_model <- read_nm_model(runno = '001', ext = '.lst', dir = 'models')
}