---
title: "Creating a Nonmem Parameter Table"
author: "Tim Bergsma"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Creating a Nonmem Parameter Table}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

The impact of a great model depends a lot on how well it is communicated.  A parameter table can help; it brings together critical details of the model in a systematic way.  However, creating parameter tables can be tedious, especially for modeling systems like ```NONMEM``` where information is distributed among numerous text files.  Here we describe a systematic approach for generating parameter tables in ```NONMEM```.

## 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:
```{r eval=FALSE}
install.packages('nonmemica')
library(nonmemica)
```
```{r echo=FALSE, results='hide'}
library(nonmemica)
```

Specify the project directory like this:

```{r eval=FALSE}
partab(1001, project='../model')
```
Or this:
```{r eval=FALSE}
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 
```{r eval=FALSE}
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:
```{r eval=FALSE}
partab(1001)
```
Piped:
```{r eval=FALSE}
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:
```{r eval=FALSE}
2 %>% sqrt %>% signif(3)
```
is easier to write and easier to understand (in my opinion) than this:
```{r eval=FALSE}
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). 
```{r eval=FALSE}
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.
```{r eval=FALSE}
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.
```{r eval=FALSE}
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:
```{r}
library(magrittr)
library(nonmemica)
options(project = system.file('project/model',package='nonmemica'))
1001 %>% definitions %>% head
```

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.
```{r eval = FALSE}
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).
```{r}
partab(1001)
```

If you want to modify the table, save it first.
```{r}
x <- partab(1001)
```
For better debugging information, set ```verbose = TRUE```.
```{r eval=FALSE}
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".
```{r}
1001 %>% partab(
  format = F, 
  ci = F, 
  relative = F, 
  digits = NULL
)
```

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`.
```{r}
library(knitr)
1001 %>% partab %>% kable
```

You can also try `pander::pander`.
```{r}
library(pander)
1001 %>% partab %>% pander(justify='right')
```

## 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.