/
create-model-library.Rmd
150 lines (117 loc) · 6.45 KB
/
create-model-library.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
---
title: "Creating a model library"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Creating a model library}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r knitr-setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
Model libraries are useful to have consistent high-quality basic models that can
be used as a model itself or as a building block for other models.
# Model library conventions within nlmixr2lib
Compartment and parameter names should be all lower case when on their own and
should use snakeCase when combined in some way.
Compartment and parameter names are selected to align with those used by
`rxode2::linCmt()` which are described in the vignette:
vignette("rxode2-model-types", package = "rxode2").
## Compartment naming
Compartment naming follows compartment names with the `linCmt()` with
augmentation for other compartments:
* `depot`: The extravascular dosing compartment (for example, the gut for oral
dosing or subcutaneous space for subcutaneous dosing)
* `central`: The intravascular compartment used for intravenous dosing or for
typical pharmacokinetic (PK) model sampling of the drug
* `peripheral1`, `peripheral2`: The first and second peripheral compartments for
2- and 3-compartment PK models
* `effect`: The compartment for effect compartment models
* Therapeutic-area-specific models should use consistent compartment and
parameter naming. When adding a new therapeutic area model to the library,
please discuss naming first in a new GitHub issue.
## Estimated parameter naming
To enable more consistent cross-model compatibility, the following conventions should be used unless there is a strong reason for an exception:
* Pharmacokinetic concentrations in the central compartment should be named
`cp`. `cp` should be used even when using a `linCmt()` model (in which case
`cp <- linCmt()` should be used and the residual error should be applied to
the `cp` parameter).
* Therapeutic-area-specific models should use consistent compartment and
parameter naming. When adding a new therapeutic area model to the library,
please discuss naming first in a new GitHub issue.
## Parameter naming
PK models should use the following parameter naming conventions:
* `ka`: absorption rate
* `cl`: clearance
* `q`: intercompartmental clearance (`central` to and from `peripheral1`
compartments)
* `q2`: second intercompartmental clearance (`central` to and from `peripheral2`
compartments)
* `vc`: central volume of distribution
* `vp`, `vp2`: first and second peripheral compartment volumes
When micro-constants are used, they should use the following naming conventions:
* `kel` elimination rate (`cl/vc`)
* `k12`, `k21`, `k13`, `k31`: intercompartmental transit rates (`q/vc`, `q/vp`,
`q2/vc`, and `q2/vp2`, respectively)
## Parameter transforms
Parameters are often estimated on a transformed scale. For instance, a natural
logarithm transform is often used for parameters that must be positive, and a
logit transform is often used when a parameter must remain within a specific
range.
Transformed parameters should be prefixed with an indicator of the
transformation. Preferred transformation prefixes are:
* `l` (lower case L): natural log transform
* `logit`: logit transform
* `probit`: probit transform
* Any other transform should similarly include the full transform as the prefix
Generally, for any transform other than natural logarithm, include the full name
as a prefix. For example, natural logarithm-transformed `ka` would be `lka` and
logit-transformed `emax` would be `logitemax`.
## Random effects
Random effects are estimates as part of a distribution varying by some grouping
factor. The grouping factor is often a subject in a clinical trial. (For
NONMEM users, random effects are often referred to as inter-individual
variability.)
Random effect parameters should prefix the (transformed) parameter name with
`eta`. For example, a random effect on log-transformed clearance would be named
`etalcl`.
## Drug effects
Different drug effects may be investigated during model building. And, multiple
drug effect styles (linear, E~max~, threshold, etc.) may be investigated by the
user.
To enable simpler changes to drug effects and to minimize the chance of
parameter name collisions when combining models, the following rules are
strongly recommended:
* Drug effects should be calculated on a model by themselves to enable changing
the type of drug effect (e.g. linear to E~max~).
* The parameter name for the drug effect should be called `drugEffect` followed
by the name of the part of the model that is most closely associated with the
drug effect. For example, in the Simeoni 2004 model, the drug effect is
called `drugEffectCyclingCells`.
# Model files
Files in a model library should have the following characteristics:
* The first line inside the function should have a description
assignment. That is `description <- "This is the description of the model"`
right inside the `function()` before the `ini({})` block.
* If the model has a literature reference associated with it, then the second
line of inside the function should have the reference, for example,
`reference <- "Richard Hooijmaijers, Matthew Fidler, William S. Denney (2022). nlmixr2lib: A Model Library for 'nlmixr2'. https://nlmixr2.github.io/nlmixr2lib/"`
* If it would be helpful to give the user some information about the model on
load, it can be added as meta-data as a `"message"` attribute to the model.
Note that in that case, you must give the function name as the last line of
the model to ensure that it is the returned value from evaluation of the file.
(See `oncology_xenograft_simeoni_2004.R` for an example of adding a message.)
* The remainder of the file should be an nlmixr2 model in a function with a
typical `ini()` and `model()` block.
* The name of the file should match the name of the model within the file.
If a function to modify, self-start, or otherwise help the user would make
sense, add it as a new file in the `R/` directory with the file name and
function name `updateModelName()` using the word update followed by the model
name in camelCase (e.g. `updateOncologyXenograftSimeoni2004`). If such a
function is added, please add it in the `messages` described above, as well.
Update functions must be able to take in a function, an rxUi object, or an
nlmixr2fitCore object and should usually return an rxUi object.
For examples, see the package installation directory.