Creating a Nonmem Parameter Table

Sources

NONMEM results end up in many places.

• The list file has the final parameter estimates in a readable form, as well as many diagnostic values, such as standard errors (when available) and shrinkage estimates.

• Various ancillary outputs may be available, such as *.ext, *.cov, *.xml, etc, giving more regular and/or more specific versions of model components.

• Bootstrap estimates of parameter uncertainty are probably in some third-party format, since bootstrapping is usually performed independently of model estimation.

Some of the most important information may not be captured anywhere! You may know that THETA1 is “apparent oral clearance” in your model, and that the units are liters. But to NONMEM it is just THETA1.

When you are making parameter tables by hand, no problem: your memory supplies all the integration, as well as missing details. But manual table generation can be tedious, time-consuming, and error-prone. If, rather, we want to automate the generation of parameter tables, we’re going to have to be more systematic about where and how the data sources are stored.

Conventions

The most fundamental storage convention is the concept of a project. This is a path – preferably a relative path, to a directory where your models live.

A second useful convention is the habit of keeping all the files related to a specific model in a project subdirectory with a unique name: i.e., the name of the model. While not strictly necessary, it really helps with organization and keeps NONMEM models from interfering with eachother while running.

I mentioned relative paths above. Relative to what? A third useful convention is to write all file paths relative to the file in which you are writing them. So if I have a model in home/project/1001/, and I write a script home/script/analysis.R that processes model ouptut, the path to the model directory will be written as ../project/1001.

Challenges

Okay, cut to the chase: we want an R function that creates a NONMEM parameter table. The challenges to be solved are as follows.

• Where can we find the model output?
• What form of the results is required?
• Where will the bootstrap values come from?
• What is the interpretation of the estimates?

Solution

The package nonmemica provides the function partab that creates a parameter table for a single NONMEM model. partab knows where the models live, because you explicitly pass a project argument or (if you are lazy like me) you set an option near the top of your script.

Install and load nonmemica like this:

install.packages(repos=NULL,'../nonmemica_0.1.zip') # supply your path and version
library(nonmemica)

Specify the project directory like this:

partab(1001, project='../model')

Or this:

options(project = '../model')
partab(1001)

A Word about Object Orientation

Users should not have to worry much about object orientation, but knowing something about it can be very helpful.

Briefly, object orientation means that a function does different things to different object types. Preparing a meal is very different from preparing a tax return. And formatting a data.frame is very different from formatting a POSIXlt. Try

methods(format)

to see all ways things get formatted in R. Typically we just say format and R finds the right method, depending on what it is we are formatting.

partab is no different. If you say partab(1001), the software sees that you are trying to create a parameter table from a number, which doesn’t really make sense. So it assumes 1001 is a model name, converts it to character, and goes looking for the function partab.character(). In fact, most of the interesting arguments to partab are actually documented under partab.character for this reason.

A Word about Piping

You’ve probably noticed … R usage is undergoing a revolution. The magrittr package recently gave us a “forward pipe operator” that fundamentally changes how R can be used. Even if you don’t use piping, an awareness will help you understand the occasional example. For instance, the following have the same meaning.

Traditional:

partab(1001)

Piped:

1001 %>% partab

Essentially, the left-hand-side is the first argument to the function on the right-hand-side, and the result can be used as input to yet-another-function in an ongoing chain. That means we can express functionality in a natural order, rather than reverse-nested order. This:

2 %>% sqrt %>% signif(3)

is easier to write and easier to understand (in my opinion) than this:

signif(sqrt(2),digits=3)

but the two are equivalent.

Finding Estimates

partab gets estimates and standard errors from *.xml. Make sure your NONMEM execution procedure calls for this file to be created and returned. It should appear in the model directory as a sibling of *.lst. If your xml file is in an unusual place, you can specify the path explicitly using the xmlfile argument (othewise partab will guess).

partab(1001, xmlfile='..model/1001.xml')

Finding Bootstraps

partab gets bootstrap estimates from bootstrap_dirx/bootstrap_results.csv (in the model directory). This is created using PsN. partab will try to find the latest file if there are more than one. You can specify the path explicitly using the bootcsv argument.

partab(1001, bootcsv='..model/1001/bootstrap_results.csv')

Finding Metadata

Let’s face it. NONMEM does not have integrated metadata. It knows the final estimate of THETA1, but it does not know what THETA1 means in human terms. A really useful parameter table should give a symbolic interpretation of THETA1, such as CL/F, units (if any), and hopefully a short definition.

The bad news is: you have to supply these yourself. The good new is: if you do it systematically, you can save a lot of effort.

partab looks in two places for metadata. First, it looks in the control stream for the items mentioned in the fields argument. It will guess where the control stream is, but you can supply the ctlfile argument. You can also modify the fields argument to change what it seeks.

partab(1001, ctlfile = '../models/1001.ctl',fields = c('symbol','label','unit')).

partab hopes to find each parameter on a line by itself, with semicolon-delimited fields trailing on the same line.

$THETA 
(0,10,50)     ; CL/F; clearance;       L/h
(0,10,100)    ; Vc/F; central volume;  L
(0,0.2,5)     ; Ka;   absorption rate; 1/h

By the way, the same conventions apply to tabled items. You can specify in your control stream how you think about table output.

$TABLE NOPRINT FILE=mod2.tab ONEHEADER 
ID            ; ID;    subject identifier;
TIME          ; TIME;  time;                       h
IPRE          ; IPRED; individual prediction;      ng/mL
CL            ; CLI;   posthoc systemic clearance; L/h
ETA1          ; BSV_CL; clearance variability;

Of course, these won’t show up in a parameter table, but you’ll see them in a list of item definitions if you do this:

library(magrittr)
library(nonmemica)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% definitions %>% head

##       item  symbol                        label unit
## 1 theta_01    CL/F                    clearance  L/h
## 2 theta_02    Vc/F               central volume    L
## 3 theta_03      Ka     absorption rate constant  1/h
## 4 theta_04     Q/F intercompartmental clearance  L/h
## 5 theta_05    Vp/F            peripheral volume    L
## 6 theta_06 MALE_CL     male effect on clearance <NA>

If you like, you can write out the defintions and edit them. You can change the file location or stick with the default. If you didn’t like exactly what was in the control stream, you can ignore it by passing a zero-length argument for ctlfile.

1001 %>% definitions(write=T)
1001 %>% partab(ctlfile = NULL)

The metafile needs to stay comma-separated. White space will be stripped, and blanks, spaces, or dots will be understood as NA.

Customizing Your Parameter Table

By default, the parameter table looks like this (but if bootstraps can’t be found, the ci columm will be missing).

partab(1001)

##      parameter estimate prse                 ci   symbol
## 1     theta_01     9.51 9.82       (7.24, 11.2)     CL/F
## 2     theta_02     22.8 9.56       (19.7, 25.4)     Vc/F
## 3     theta_03   0.0714 7.35   (0.0646, 0.0803)       Ka
## 4     theta_04     3.47 15.4       (3.02, 4.59)      Q/F
## 5     theta_05      113   21        (90.5, 380)     Vp/F
## 6     theta_06     1.02 11.1        (0.88, 1.3)  MALE_CL
## 7     theta_07     1.19 28.3       (0.53, 1.73)    WT_CL
## 8  omega_01_01    0.214 22.8     (0.151, 0.319)   IIV_CL
## 9  omega_02_01    0.121 26.4                        CL_V
## 10 omega_02_02   0.0945 33.2      (0.07, 0.179)   IIV_Vc
## 11 omega_03_01  -0.0116  173                       CL_Ka
## 12 omega_03_02  -0.0372 36.1                       Vc_Ka
## 13 omega_03_03   0.0466 34.7    (0.0475, 0.146)   IIV_Ka
## 14 sigma_01_01   0.0492   11   (-0.039, 0.0165) ERR_PROP
## 15 sigma_02_02    0.202 33.5 (-0.0512, -0.0097)  ERR_ADD
##                                            label unit
## 1                                      clearance  L/h
## 2                                 central volume    L
## 3                       absorption rate constant  1/h
## 4                   intercompartmental clearance  L/h
## 5                              peripheral volume    L
## 6                       male effect on clearance <NA>
## 7                     weight effect on clearance <NA>
## 8       interindividual variability on clearance <NA>
## 9    interindividual clearance-volume covariance <NA>
## 10 interindividual variability on central volume <NA>
## 11       interindividual clearance-Ka covariance <NA>
## 12          interindividual volume-Ka covariance <NA>
## 13             interindividual variability on Ka <NA>
## 14                            proportional error <NA>
## 15                                additive error <NA>

If you want to modify the table, save it first.

x <- partab(1001)

For better debugging information, set verbose = TRUE.

partab(1001, verbose=TRUE)

partab uses global options project and nested to guess where the run directory is, and uses that to guess where the source files are (metafile, xmlfile,ctlfile,bootcsv). You can supply any of these directly.

By default, partab grabs the 5th and 95th percentile of bootstraps as lo and hi, but you can specify other levels using the like-named arguments. partab formats these and other numerics as character(unless you say format = F), first limiting to the number of significant digits you specify (default digits = 3). If ci = TRUE (the default), lo and hi will be combined into a single interval using the default values for open, sep, and close. Also, you can get absolute standard errors by setting relative = FALSE. Let’s compare the default table above with something a bit more “raw”.

1001 %>% partab(
  format = F, 
  ci = F, 
  relative = F, 
  digits = NULL
)

##      parameter     estimate           se          lo            hi
## 1     theta_01   9.50754401  0.933416854  7.23607500  11.165510000
## 2     theta_02  22.79072310  2.178865442 19.68059000  25.360120000
## 3     theta_03   0.07143144  0.005252021  0.06458277   0.080336250
## 4     theta_04   3.47437830  0.535612711  3.01994200   4.586354000
## 5     theta_05 113.26891469 23.792156167 90.54828000 380.010800000
## 6     theta_06   1.02439368  0.114028439  0.88016420   1.301607000
## 7     theta_07   1.19225807  0.337609615  0.52951980   1.733120000
## 8  omega_01_01   0.21381265  0.048842658  0.15135260   0.319490800
## 9  omega_02_01   0.12073868  0.031913007          NA            NA
## 10 omega_02_02   0.09452753  0.031355815  0.06995132   0.179007400
## 11 omega_03_01  -0.01160628  0.020072690          NA            NA
## 12 omega_03_02  -0.03719850  0.013427798          NA            NA
## 13 omega_03_03   0.04656110  0.016178741  0.04754577   0.145969600
## 14 sigma_01_01   0.04916831  0.005383980 -0.03904045   0.016537490
## 15 sigma_02_02   0.20181403  0.067654241 -0.05122678  -0.009697708
##      symbol                                         label unit
## 1      CL/F                                     clearance  L/h
## 2      Vc/F                                central volume    L
## 3        Ka                      absorption rate constant  1/h
## 4       Q/F                  intercompartmental clearance  L/h
## 5      Vp/F                             peripheral volume    L
## 6   MALE_CL                      male effect on clearance <NA>
## 7     WT_CL                    weight effect on clearance <NA>
## 8    IIV_CL      interindividual variability on clearance <NA>
## 9      CL_V   interindividual clearance-volume covariance <NA>
## 10   IIV_Vc interindividual variability on central volume <NA>
## 11    CL_Ka       interindividual clearance-Ka covariance <NA>
## 12    Vc_Ka          interindividual volume-Ka covariance <NA>
## 13   IIV_Ka             interindividual variability on Ka <NA>
## 14 ERR_PROP                            proportional error <NA>
## 15  ERR_ADD                                additive error <NA>

You may want to do other things as well, such as converting error estimates to standard deviation or CV%. In my experience, it is difficult to do this in an automated way, as it depends on hard-to-guess properties, such as whether your distributions are log normal, and whether error has been coded as a sigma or a theta. If your goal is routinely to present random effects next to the corresponding parameter estimate, consider using the same symbol for each, and then “unstacking” the data with something like dplyr:spread(x, parameter, symbol).

Rendering Your Parameter Table

To some extent, the science of creating a parameter table is a separate issue from the aesthetics. How should you render the table for viewing by your audience? nonmemica is deliberately agnostic on this question, since there is no one right answer, and very many good ones. In an rmarkdown environment, consider knitr::kable.

library(knitr)
1001 %>% partab %>% kable

You can also try pander::pander.

library(pander)
1001 %>% partab %>% pander(justify='right')

If your target audience needs a Word doc, try making one using built-in support for ReporteRs. You can also make a FlexTable first, and then make arbitrary modifications.

library(ReporteRs)

## Loading required package: ReporteRsjars

1001 %>% partab %>% as.docx %>% as.file('1001.docx')
x <- as.flextable(partab(1001))
x

Getting Help

If you have the nonmemica package installed, you can find this document using vignette('parameter-table', package = 'nonmemica'). Of course, the usual R help is available as well. Contact the mantainer for bug fixes and feature requests.

Conclusion

Making a NONMEM parameter table can be tedious. The nonmemica package provides partab, a flexible way of assembling the main sources of information and presenting them nicely. A good parameter table should have rich metadata: symbols, labels, and units at least. partab supports several options for encoding metadata systematically.