-
Notifications
You must be signed in to change notification settings - Fork 1
/
NMsim-config.Rmd
194 lines (143 loc) · 9.21 KB
/
NMsim-config.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
---
title: "Requirements and Configuration"
output:
rmarkdown::html_vignette:
toc: true
Suggests: markdown
VignetteBuilder: knitr
vignette: >
%\VignetteIndexEntry{Configuration}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
header-includes:
- \usepackage{ae}
---
```{r,include = FALSE}
##knitr::opts_chunk$set(dev = "cairo_pdf")
knitr::opts_chunk$set(
collapse = TRUE
,comment = "#>"
,fig.width=7
,cache=FALSE
)
## this changes data.table syntax. I think we can do without.
## knitr::opts_chunk$set(tidy.opts=list(width.cutoff=60), tidy=TRUE)
```
## Objectives
This vignettes aims at enabling you to
* Understand requirements for using NMsim
* Configure `NMsim` to use `PSN` or methods provided by `NMsim` to
update Nonmem control stream initial values and to run Nonmem
* Understand pros and cons of using `PSN` vs. methods provided by
`NMsim`.
* Configure `NMsim` to store results in desired locations and separate
storage of temporary files and storage of selected and efficiently
stored key result data.
## Requirements
`NMsim` itself and many features will work in any newer R installation. Integration with Nonmem for a seamless simulation experience within R, Nonmem installations on linux, Windows and Mac are supported. Multi-threaded execution may currently not work on Windows.
`NMsim` relies on Nonmem for running simulations. The most important requirement for a fully seamless simulation experience within R, NMsim must be able to execute Nonmem. The simplest example where this is easily achieved, is when R and Nonmem run on the same system. If they are on separate system, the questions are: Do R and Nonmem share access to a data structure where the relevant files can be stored and executed? And can R login to that other system to run Nonmem, for instance through SSH? In case these two criteria are met, the fully seamless experience should still be possible.
If your system does
not meet these requirements in this document, it does not mean
that NMsim can't work. It can still put together your Nonmem
simulation control streams and data and make everything ready for Nonmem to execute. Once
you have run Nonmem, you can then use `NMsim::NMreadSim()` to
collect the results.
## Configuration of NMsim
Below this section, some background discussion is provided to
understand which methods to choose. No matter what you prefer to use,
the best is to set up `NMsim` to be able to use both Nonmem and (if
available) PSN. Then you have the flexibility to switch between
methods as preferred.
### Specify the Nonmem paths
For `NMsim` to run Nonmem, it needs to know where to find the Nonmem
executable. This step is recommended.
The easiest way to configure this is through NMdata's configuration
function. Say you want to run Nonmem with `/opt/NONMEM/nm75/run/nmfe`,
insert this after loading `NMdata` in the beginning of your script
```{r,eval=FALSE}
NMdataConf(path.nonmem="/opt/NONMEM/nm75/run/nmfe75")
```
On Windows, the executable has a `.bat` extension. The path could look be
```{r,eval=FALSE}
NMdataConf(path.nonmem ="C:/nm75g64/run/nmfe75.bat")
```
If you normally use PSN as your Nonmem interface, and you therefore do
not know where Nonmem is installed, you can check this using PSN. The
following command should give you the Nonmem installation paths that
PSN is configured with. However, you likely still need to add the last
piece of the path from the installation directory to the nonmem
binary.
```
psn -nm_versions
```
### Specify the PSN installation path
If PSN is available, and you can run `execute` and `update_inits` in a
terminal, you don't need to configure how NMsim finds PSN. If you have PSN
installed, but you have to provide the paths to those two executables
when running them (something like `/opt/PSN/execute run1.mod`), you
will have to tell NMsim where to find them. In this case, the easiest
is loading NMdata and then running:
```{r,eval=FALSE}
NMdataConf(dir.psn="/opt/PSN")
```
Notice `dir.psn` refers to a directory while `path.nonmem`
refers to a file.
### Configure the directories `NMsim` writes to
`NMsim` creates two main directories for its output.
#### `dir.sims`
- simulation control streams and other data created by NMsim
- output written by Nonmem
- By far, the largest directory
These files are not necessarily needed for further storage.
#### `dir.res`
Selected and efficiently stored simulation output data.
- `_paths.rds` which contains an index table for `NMreadSim()1. It does not contain any simulated data and is of insignificant size.
- `.fst` is the full simulation output data set. `NMreadSim()` will automatically create this file the first time it reads `_paths.rds`. The user does not need to know about the `fst` format as they will keep reading the simulation results via `NMreadSim()` on `_paths.rds`.
You must make sure to preserve this directory in case you will need to re-analyze or further analyze the simulation output without re-running the simulations.
## PSN or not?
### PSN or not for Nonmem execution
NMsim can call Nonmem using PSN's `execute` or through similar
functionality included in NMsim. We will refer to those methods by
the way they are referred to in the `NMsim()` function argument that
controls which one is used, i.e. `method.execute="psn"` and
`method.execute="nmsim"`. While `PSN` users will be familiar with what `PSN`'s `execute` does, `method.execute="nmsim"` needs a few words of explanation. It is essentially an R-based method similar to `PSN`'s `execute`, meaning it creates a temporary folder containing necessary files for running Nonmem, then runs `nmfe` (as specified using `path.nonmem`) and then copies the desired result files back to the location of the input control stream. `NMsim` can control the behavior of this function better than it can `PSN`'s execute which enables NMsim to do additional things with `method.execute="nmsim"`.
For simulations, `method.execute="psn"` does not provide advantages
over `method.execute="nmsim"`. In contrast, there are simulation types
that will only work with `method.execute="nmsim"`. You need to tell
NMsim where to find Nonmem (by setting `path.nonmem`) for this to work.
Nonmem execution with `NMexec()` (typically, for estimation and not
simulation) is a slightly different discussion. See `?NMexec` for
that.
### PSN or not for updating initial values
NMsim needs to update initial values using the model estimate prior to
running a simulation. PSN provides the `update_inits` function to do
this, and if available, this is the default method in NMsim. Again, we
refer to this by the argument name, `method.update.inits="psn"`.
NMsim also provides a similar functionality internally, referred to as
`method.update.inits="NMsim"`. This will be used if PSN is not found -
or if you ask for it.
`method.update.inits="psn"` has two advantages over the NMsim-provided
method. It is widely used, and it keeps comments in affected control
stream sections (`$THETA`, `$OMEGA`,
`$SIGMA`). `method.update.inits="nmsim"` will drop all comments in
affected sections. I have in the past seen issues with some methods to
update `$OMEGA` sections with off-diagonal elements
(`BLOCK`). `method.update.inits="nmsim"` takes a very simple
approach. Reading the `OMEGA` matrix from the `.ext` file, this is not
relying on interpreting Nonmem code at all. The support of systems
without `PSN` would be the main reason one would choose
`method.update.inits="nmsim"` over `method.update.inits="psn"`.
In order to make use of `method.update.inits="psn"`, you need to make
sure NMsim can find PSN.
### Input model file name extensions
The following requirements to file name and their contents concerns
the "input model". It does not concern files generated by `NMsim`.
There is no requirement to the file name extension of the input control stream.
`NMsim` function documentation and their argument `file.mod` refer to input control
streams by `.mod`. However, the input control stream can have any extension (e.g., `.ctl` or `.txt`).
If your input control streams are named differently than `.mod`, avoid setting `file.mod` using `NMdata::NMdataConf(file.mod)`.
The estimate files (`.ext`, `.phi`
if known subjects simulated, `.cov` if simulating parameters from the covariance step) are by default expected to carry
the same file name but with those file name extension. See arguments like `file.ext` and `file.phi` to specify other paths. Currently, the default behavior cannot be customized and the two arguments will have to be provided at each NMsim() call to the extend relevant for the simulation.
Output table files from input model may be needed. This is the case using `NMsim_known` on models estimated using Bayesian `$ESTIMATION` methods like `SAEM` and/or `$IMP`. In this case `NMsim` will need to find all the `ETA` values for all subjects, even if spread across the output tables. This is because these estimation methods leave `PHI` instead of `ETA` in the `.phi` file. For emperical Bayes estimates, `NMsim` needs the `ETA`s.
There are no limitations to the file names of the output tables. If needed, file names will be automatically identified and read using `NMdata::NMscanData`. For `$TABLE` options, subsetting is supported using `FIRSTONLY` and `LASTONLY`.