Ctrl+K

Using the NONMEM plugin#

This page will cover different topics relevant to users who are using Pharmpy for a NONMEM model.

Names of parameters and random variables#

When Pharmpy parses a model, it recognizes and stores etas, thetas etc. as parameters and random variables. You can configure which names Pharmpy uses when parsing the model file, i.e. what they are called when you want to access them using transformation functions etc. You can also configure how etas are written once you have added new etas. The naming system can be divided into three parts: how the names are parsed from NONMEM code, how new names are added to the model object, and how new names are written into NONMEM code.

Reading in a model#

When Pharmpy parses the NONMEM model file, depending on your Pharmpy configuration file (see Configuration) it will use different names for the internal representation of parameters. The following naming schemes are supported:

  • Standard NONMEM names (‘basic’)

  • Comments next to $THETA, $OMEGA, and $SIGMA records (‘comment’)

  • Any abbreviated names from $ABBR (‘abbr’)

You can set which naming schemes you want to use, and prioritize between them. For each parameter and random variable, Pharmpy will check which names are available and choose the one that is highest in priority. For example, assume you have the following configuration:

parameter_names=abbr,comment,basic

Where names from abbreviated records are prioritized first, comments next, and finally the basic NONMEM names. Given the following model:

$PROBLEM SIMPLE MODEL
$DATA pheno.dta IGNORE=@
$INPUT ID TIME AMT WGT APGR DV
$SUBROUTINE ADVAN1 TRANS2

$ABBR REPLACE THETA(CL)=THETA(1)
$ABBR REPLACE ETA(CL)=ETA(1)

$PK
CL=THETA(CL)*EXP(ETA(CL))
V=THETA(2)*EXP(ETA(2))
S1=V

$ERROR
Y=F+F*EPS(1)

$THETA (0,0.00469307) ; TVCL
$THETA (0,1.00916) ; TVV
$OMEGA 0.0309626  ; IVCL
$OMEGA 0.031128
$SIGMA 0.1

For the first theta, TVCL, THETA_CL, and THETA(1) are possible names. Since the setting for abbreviated names is prioritized the highest, THETA_CL will be used. Note that THETA(CL) is parsed as THETA_CL. For the second omega record, there is no abbreviated name and no comment, so it will simply be called OMEGA(2,2).

New parameters and random variables#

When performing different transformations or manipulations of the model, the names of the parameters and random variables do not have to follow the previously mentioned name schemes. Let’s say we have a model with no etas, and the model is transformed accordingly:

add_iiv(model, 'CL', 'exp')
model.update_source()

If you add an eta to the parameter clearance (CL), the new eta name will default to ETA_CL and the omega name IIV_CL. When performing subsequent transformations, ETA_CL and IIV_CL are the names you will refer to even if the NONMEM name for them would be ETA(1) and OMEGA(1,1) respectively. Now we want to remove that eta:

remove_iiv(model, ['ETA_CL'])

We still have to refer to the eta as ETA_CL. If you update the NONMEM code, ETA_CL will be replaced with ETA(1) in the code (this does however not affect the Pharmpy name).

Writing a model#

When calling update_source() or write_model(), the NONMEM code will be updated based on your changes. As a default, all parameters will have NONMEM names in the code and their Pharmpy name (if different from NONMEM name) as comments. For example, if you’ve added a new parameter MAT (in a model with no thetas), the resulting theta POP_MAT will look like this in the NONMEM code:

$PK
MAT = THETA(1)
…
$THETA (0,0.1) ; POP_MAT

Note that the internal Pharmpy name still is POP_MAT despite it being called THETA(1) in the code.

The configuration can be set to write eta names as $ABBR records via the setting:

write_etas_in_abbr=True

This setting can be set to True or False (default). Using the example of adding an eta to clearance (CL), the updated code will be:

$ABBR REPLACE ETA(CL)=ETA(1)
$PK
CL=TVCL*EXP(ETA(CL))
…
$OMEGA 0.09 ; IIV_CL
On this page