-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy path_UserManual.Rmd
3633 lines (3005 loc) · 180 KB
/
_UserManual.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
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: "Pmetrics User Manual"
output:
html_document:
theme: spacelab
toc: true
toc_float: true
toc_depth: 3
highlight: tango
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
options(knitr.kable.NA = ".")
```
```{css echo=F}
h1 {
color:#446e9b
}
```
# Introduction
Thank you for your interest in Pmetrics! This guide provides
instructions and examples to assist users of the Pmetrics R package, by
the Laboratory of Applied Pharmacokinetics and Bioinformatics at the
Saban Research Institute, Children's Hospital Los Angeles, and the
Department of Pediatrics, Keck School of Medicine, University of
Southern California. Please see our website at
[[http://www.lapk.org]{.underline}](http://www.lapk.org) for more
information.
As of *v. 2.0*, Pmetrics is shifting to an architecture less dependent on
reading and writing files. Data files are unchanged and described later in
this manual.
Model files can now be defined as an R object, instead of in a text file.
Pmetrics can suppoort legacy runs with the old-style text file models, but
users are encouraged to change to the new methods. Throughout this manual we
will indicate the new style with the **R6** designation to reflect the
object-oriented R6 style of programming available in R that makes it more
consistent with object-oriented languages such as Python. We will indicate
old-style approaches with **Legacy**.
**Here are some tips for using this guide.**
* The table of contents to the left is expandable and navigable.
* Items that are hyperlinked can be selected to cross reference
within this manual or link to external sites.
* `Items` correspond to inline examples of R code, which are not evaluted
in this document, but serve as templates for what may be typed into your
R console or script. They may not necessarily be executable if typed verbatim.
## Citing Pmetrics
Please help us maintain our funding to provide Pmetrics as a free
research tool to the pharmacometric community. If you use Pmetrics in a
publication, you can cite it as below.
```{r}
citation("Pmetrics")
```
## Disclaimer
You, the user, assume all responsibility for acting on the results
obtained from Pmetrics. The Laboratory of Applied Pharmacokinetics and
Bioinformatics (LAPKB), members and consultants to LAPKB, and Children's
Hospital Los Angeles and the University of Southern California and their
employees assume no liability whatsoever. Your use of the package
constitutes your agreement to this provision.
## System Requirements and Installation
Pmetrics and all required components will run under Mac (Unix), Windows,
and Linux. There are three *required* software components
which must be installed on your system **in this order**:
1. The statistical programming language and environment "**R**"
+ After installing R, we highly recommended that you also install
**Rstudio**, a user-friendly environment for R.
2. The **Pmetrics** package for R
3. The **gfortran** Fortran compiler.
All components have versions for Mac, Windows, and Linux environments,
and 64- bit processors. Systems with 32-bit processors are no longer
supported. All are free of charge.
#### R
R is a free software environment for statistical computing and graphics,
which can be obtained from
[[http://www.R-project.org]{.underline}](http://www.R-project.org)/.
Pmetrics is a library for R.
#### Rstudio
We strongly recommend using [Rstudio](http://rstudio.org/) rather than any
other R interface.
#### Pmetrics
If you are reading this manual, then you have likely visited our website
at [[http://www.lapk.org]{.underline}](http://www.lapk.org), where you
can select the software tab to access instructions.
As of version 1.9, Pmetrics is distributed on github and is a self-contained
package that will install gfortran with your permission, if it is not
already installed on your computer. Installing from github will also install
all packages upon which Pmetrics depends.
#### Gfortran
In order to run Pmetrics, a Fortran compiler compiler is required.
Pmetrics is designed to work with gfortran, a free compiler. After you
have installed Pmetrics, it will check your system for an active
gfortran installation. If it doesn't find one, it will offer to download
and install it. From there, installation should proceed automatically.
This is by far the easiest and most reliable way to complete
installation. Rest assured that no files are installed without your
permission.
If you do not wish to do this, you will have to get components manually,
and the first command to run is `PMbuild()`. You can get detailed
instructions on how to obtain and install gfortran appropriate for your
system on our [LAPKB website](http://www.lapk.org/Pmetrics_install_manual.php).
## What This Manual Is Not
We assume that the user has familiarity with population modeling and R,
and thus this manual is not a tutorial for basic concepts and techniques
in either domain. We have tried to make the R code simple, regular and
well documented. A very good free online resource for learning the
basics of R can be found at [Stat Methods](http://www.statmethods.net/index.html).
We recognize that initial use of a new software package can be complex,
so please feel free to contact us at any time, preferably through the
[Pmetrics forum](http:/www.lapk.org) or directly by [email](mailto:[email protected]).
This manual is also not intended to be a theoretical treatise on the
algorithms used in IT2B or NPAG. For that, the user is directed to our
[website](http://www.lapk.org).
## Getting Help and Updates
<!--There is an active [LAPK forum](http://www.lapk.org) with all kinds
of useful tips and help with Pmetrics. Register and feel free to post!
-->
Within R, you can use
`help("command")` or `?command` in the R console to see detailed help files
for any Pmetrics command. Many commands have examples included in this
documentation and you can execute the examples with `example(command)`.
<!--You can also type `PMmanual()` to launch this manual from within Pmetrics
as well as a catalogue of all Pmetrics functions. Finally,
`PMnews()` will display the Pmetrics change log.
-->
Pmetrics will check for updates automatically every time you load it
with `library(Pmetrics)` and you are connected to the internet.
If an update is available, it will provide a
brief message to inform you. You can then reinstall the package from github.
<!--When bugs arise in Pmetrics, you may see a start up message to inform you of
the bug and a patch can be installed by the command `PMpatch()` if available.
Note that patches must be reinstalled with this command every time you launch
Pmetrics, until the bug is corrected in the next version.
-->
<!--As of version 1.0.0 Pmetrics has graphical user interface (GUI)
capability for many functions. Using `PMcode("function")` will launch the
GUI in your default browser. While you are interacting with the GUI, R
is "listening" and no other activity is possible. The GUI is designed to
generate Pmetrics R code in response to your input in a friendly,
intuitive environment. That code can be copied and pasted into your
Pmetrics R script. You can also see live plot previews with the GUI. All
this is made possible with the 'shiny' package for R.
Currently, the following GUIs are available: `PMcode("run")` and
`PMcode("plot")`.
-->
## Customizing Pmetrics Options
You can change global options in Pmetrics with
`setPMoptions(sep, dec,server\_address)`.
Currently you can change three options: `sep` and `dec` will allow Pmetrics
to read data files whose field separators are semicolons and decimal
separators are commas, e.g. `setPMoptions(sep=";", dec=",")`. These
options will persist from session to session until changed. The third
option, `server\_address`, allows you to specify the address of a remote
server with Pmetrics installed, to allow remote runs.
`getPMoptions()` will return the current options.
# Pmetrics Components
## Software engines
There are three main software engines that Pmetrics controls.
* **IT2B** is the ITerative 2-stage Bayesian parametric population PK modeling
program. It is generally used to estimate parameter ranges to pass to
NPAG. It will estimate values for population model parameters under the
assumption that the underlying distributions of those values are normal
or transformed to normal.
* **NPAG** is the Non-parametric Adaptive Grid software. It will create a
non-parametric population model consisting of discrete support points,
each with a set of estimates for all parameters in the model plus an
associated probability (weight) of that set of estimates. There can be
at most one point for each subject in the study population. There is no
need for any assumption about the underlying distribution of model
parameter values.
* The **simulator** is a semi-parametric Monte Carlo simulation software
program that can use the output of IT2B or NPAG to build randomly
generated response profiles (e.g. time-concentration curves) for a given
population model, parameter estimates, and data input. Simulation from a
non-parametric joint density model, i.e. NPAG output, is possible, with
each point serving as the mean of a multivariate normal distribution,
weighted according to the weight of the point. The covariance matrix of
the entire set of support points is divided equally among the points for
the purposes of simulation.
## Pmetrics control functions
Pmetrics has groups of R functions named logically to run each of these
programs and to extract the output. Again, these are extensively
documented within R by using the `help(command)` or `?command syntax`.
* `ITrun`, `ITparse`, `ERRrun`
* `NPrun`, `NPparse`
* `PMload`, `PMsave`, `PMreport`
* `SIMrun`, `SIMparse`
### Run functions
For IT2B and NPAG, the "run" functions generate batch files, which when
executed, launch the software programs to do the analysis. ERRrun is a
special implementation of IT2B designed to estimate the assay error
polynomial coefficients from the data, when they cannot be calculated
from assay validation data (using `makeErrorPoly()`) supplied by the
analytical laboratory. The batch files contain all the information
necessary to complete a run, tidy the output into a date/time stamped
directory with meaningful subdirectories, extract the information,
generate a report, and a saved Rdata file of parsed output which can be
quickly and easily loaded into R. On Mac (Unix) and Linux systems,
the batch file automatically launches in a Terminal window.
Prior to v1.9, on Windows systems, the batch file was launched manually,
but as of v1.9, this manual step is no longer necessary. The execution of
the program to do the actual model parameter estimation is independent
of R, so that the user is free to use R for other purposes.
For the Simulator, the `SIMrun` function will execute the program
directly within R.
### Parse functions
For all programs, the "parse" functions will extract the primary output
from the program into meaningful R data objects. For IT2B and NPAG, this
is done automatically at the end of a successful run, and the objects
are saved in the output subdirectory as IT2Bout.Rdata or NPAGout.Rdata,
respectively.
### Saving and loading functions
For IT2B and NPAG, the `PMload` function can be used to load the either
of the above .Rdata files after a successful run. `PMsave` is the
companion to `PMload` and can re-save modified objects to the .Rdata file.
### Report generation
The `PMreport` function is automatically run at the end of a successful
NPAG and IT2B run, and it will generate an HTML page with summaries of
the run, as well as the .Rdata files and other objects. The default
browser will be automatically launched for viewing of the HTML report
page. It will also generate a .tex file suitable for processing by a
LATEX engine to generate a pdf report. See the [Pmetrics
Outputs](#outputs) section.
## Data manipulation functions
Within Pmetrics there are also functions to manipulate data .csv files
and process and plot extracted data.
* Manipulate data .csv files: `PMreadMatrix`, `PMcheck`, `PMwriteMatrix`,
`PMmatrixRelTime`, `PMwrk2csv`, `NM2PM`, `PMmb2csv`
* Process data: `makeAUC`, `makeCov`, `makeCycle`, `makeFinal`, `makeOP`, `makePTA`,
`makeErrorPoly`
* Plot data: `plot.PMcov`, `plot.PMcycle`, `plot.PMfinal`, `plot.PMmatrix`,
`plot.PMop`,`plot.PMsim`, `plot.PMvalid`, `plot.PMpta`
* Model selection and diagnostics: `PMcompare`, `plot.PMop` (with residual
option), `makeValid`, `plot.PMvalid`, `PMstep`
* Pmetrics function defaults: `setPMoptions`, `getPMoptions`
Again, all functions have extensive help files and examples which can be
examined in R by using the `help(command)` or `?command` syntax.
# General Workflow
The general Pmetrics workflow for IT2B and NPAG is shown in the
following diagram.
R is used to specify the working directory containing the data .csv and
model .txt files. Through the batch file generated by R, the preparation
program is compiled and executed. The instruction file is generated
automatically by the contents of the data and model files, and by
arguments to the `NPrun()`, `ITrun()` or `ERRrun()` commands. The batch file
will then compile and execute the engine file according to the
instructions, which will generate several output files upon completion.
Finally, the batch file will call the R script to generate the summary
report and several data objects, including the IT2Bout.Rdata or
NPAGout.Rdata files which can be loaded into R subsequently using
`PMload()`. Objects that are modified can be saved back to the .Rdata
files with `PMsave()`.
Both input files (data, model) are text files which can be edited
directly.
# Pmetrics Input Files
## Data.csv Files
Pmetrics accepts input as a spreadsheet "matrix" format. It is designed
for input of multiple records in a concise way. **Please keep the number
of characters in the file name ≤ 8.**
### Data file format
Files are in comma-separated-values (.csv) format. Examples of programs
that can save .csv files are any text editor (e.g. TextEdit on Mac,
Notepad on Windows) or spreadsheet program (e.g. Excel). Click on
hyperlinked items to see an explanation.
**IMPORTANT**: The order, capitalization and names of the header and the
first 12 columns are fixed. All entries must be numeric, with the
exception of ID and "." for non-required placeholder entries.
***POPDATA DEC\_11***
```{r echo=F, results='asis'}
library(knitr)
tab <- read.csv("Data/mdata.csv",na.strings=".")
names(tab)[1] <- "#ID"
tab$OUT <- as.character(tab$OUT)
kable(tab)
```
* ***POPDATA DEC\_11*** This is the fixed header for the file and must be
in the first line. It identifies the version. It is not the date of your
data file.
* ***\#ID*** This field must be preceded by the "\#" symbol to confirm
that this is the header row. It can be numeric or character and
identifies each individual. All rows must contain an ID, and all
records from one individual must be contiguous. Any subsequent row
that begins with "\#" will be ignored, which is helpful if you want to
exclude data from the analysis, but preserve the integrity of the
original dataset, or to add comment lines. IDs should be 11 characters
or less but may be any alphanumeric combination. **There can be at
most 800 subjects per run.**
* ***EVID*** This is the event ID field. It can be 0, 1, or 4. Every row
must have an entry.
+ 0 = observation
+ 1 = input (e.g. dose)
+ 2, 3 are currently unused
+ 4 = reset, where all compartment values are set to 0 and the time
counter is reset to 0. This is useful when an individual has multiple
sampling episodes that are widely spaced in time with no new
information gathered. This is a dose event, so dose information needs
to be complete.
* ***TIME*** This is the elapsed time in decimal hours since the first
event. It is not clock time (e.g. 09:30), although the `PMmatrixRelTime`
function can convert dates and clock times to decimal hours.
Every row must have an entry, and within a given ID, rows
must be sorted chronologically, earliest to latest.
* ***DUR*** This is the duration of an infusion in hours. If EVID=1,
there must be an entry, otherwise it is ignored. For a bolus (i.e. an
oral dose), set the value equal to 0.
* ***DOSE*** This is the dose amount. If EVID=1, there must be an entry,
otherwise it is ignored.
* ***ADDL*** This specifies the number of additional doses to give at
interval II. It may be missing for dose events (EVID=1 or 4), in which
case it is assumed to be 0. It is ignored for observation (EVID=0)
events. Be sure to adjust the time entry for the subsequent row, if
necessary, to account for the extra doses. If set to -1, the dose is
assumed to be given under steady-state conditions. ADDL=-1 can only be
used for the first dose event for a given subject, or an EVID=4 event,
as you cannot suddenly be at steady state in the middle of dosing
record, unless all compartments/times are reset to 0 (as for an EVID=4
event). To clarify further, when ADDL=-1, all compartments in the
model will contain the predicted amounts of drug at the end of the
100th II interval.
* ***II*** This is the interdose interval and is only relevant if ADDL
is not equal to 0, in which case it cannot be missing. If ADDL=0 or is
missing, II is ignored.
* ***INPUT*** This defines which input (i.e. drug) the DOSE corresponds
to. Inputs are defined in the model file.
* ***OUT*** This is the observation, or output value. If EVID=0, there
must be an entry; if missing, this must be coded as -99. It will be
ignored for any other EVID and therefore can be ".". There can be at
most 150 observations for a given subject.
* ***OUTEQ*** This is the output equation number that corresponds to the
OUT value. Output equations are defined in the model file.
* ***C0, C1, C2, C3*** These are the coefficients for the assay error
polynomial for that observation. Each subject may have up to one set
of coefficients per output equation. If more than one set is detected
for a given subject and output equation, the last set will be used. If
there are no available coefficients, these cells may be left blank or
filled with "." as a placeholder.
* ***COV***\... Any column after the assay error coefficients is assumed
to be a covariate, one column per covariate. The first row for any subject
must have a value for all covariates, since the first row is always a dose.
Covariate values are applied at the time of doses.
### Manipulation of CSV files
There are several functions in Pmetrics which are useful for either
converting other formats into Pmetrics data files, or checking Pmetrics
data files for errors and fixing some of them automatically.
* `PMreadMatrix(filename,...)` This function simply reads *filename* and
creates a PMmatrix object in memory which can be plotted (see
`?plot.PMmatrix`) or otherwise analyzed.
* `PMcheck(filename / PMmatrix, model,...)` This function will check a .csv
file named *filename* or a PMmatrix data frame containing a previously
loaded .csv file (the output of `PMreadMatrix`) for errors which would
cause the analysis to fail. If a model file is provided, and the data
file has no errors, it will also check the model file for errors. If it
finds errors, it will generate a new errors.xlsx file with all errors
highlighted and commented so that you can find and correct them easily.
See `?PMcheck` for details in R.
* `PMwriteMatrix(data.frame, filename,...)` This function writes an
appropriate data.frame as a new .csv file. It will first check the
data.frame for errors via the `PMcheck()` function above, and writing will
fail if errors are detected. This can be overridden with `override=T`.
* `PMmatrixRelTime()` This function converts dates and clock times of
specified formats into relative times for use in the NPAG, IT2B and
Simulator engines. See `?PMmatrixRelTime` for details.
* `PMwrk2csv()` This function will convert old-style, single-drug USC\*PACK
.wrk formatted files into Pmetrics data .csv files. Details are
available with `?PMwrk2csv` in R.
* `PMmb2csv()` This function will convert USC\*PACK .mb files into Pmetrics
data .csv files. Details are available with `?PMmb2csv` in R.
* `NM2PM()` Although the structure of Pmetrics data files are similar to
NONMEM, there are some differences. This function attempts to
automatically convert to Pmetrics format. It has been tested on several
examples, but there are probably NONMEM files which will cause it to
crash. Running `PMcheck()` afterwards is a good idea. Details can be found
with `?NM2PM` in R.
Model Files
-----------
Model files for Pmetrics are ultimately Fortran text files with a header
version of TSMULT\... As of Pmetrics version 0.30, we have adopted a
very simple user format that Pmetrics will use to generate the Fortran
code automatically for you. Version 0.4 additionally eliminates the
previously separate instruction file. A model library is available on
our website at
[[http://www.lapk.org/pmetrics.php]{.underline}](http://www.lapk.org/pmetrics.php).
**Naming your model files.** The default model file name is "model.txt,"
but you can call them whatever you wish. However, **please keep the
number of characters in the model file name ≤ 8**. When you use a model
file in NPrun(), ITrun(), ERRrun(), or SIMrun(), Pmetrics will make a
Fortran model file of the same name, temporarily renaming your file. At
the end of the run, your original model file will be in the /inputs
subfolder of the run folder, and the generated Fortran model file will
be called "model.for" and moved to the /etc subfolder of the run folder.
If your model is called "mymodel.txt", then the Fortran file will be
"mymodel.for".
You can still use appropriate Fortran model files directly, but we
suggest you keep the .for extension for all Fortran files to avoid
confusion with the new format. If you use a .for file as your model, you
will have to specify its name explicitly in the NPrun(), ITrun,
ERRrun(), or SIMrun() command, since the default model name again is
"model.txt." If you use a .for file directly, it will be in the /inputs
subfolder of the run folder, not in /etc, since you did not use the
simpler template as your model file.
**Structure of model files.** The new model file is a text file with 11
blocks, each marked by \"\#\" followed by a header tag.
[[\#PRImary variables]{.underline}](\l)
[[\#COVariates]{.underline}](\l)
[[\#SECcondary variables]{.underline}](\l)
[[\#BOLus inputs]{.underline}](\l)
[[\#INItial conditions]{.underline}](\l)
[[\#F (bioavailability)]{.underline}](\l)
[[\#LAG time]{.underline}](\l)
[[\#DIFferential equations]{.underline}](\l)
[[\#OUTputs]{.underline}](\l)
[[\#ERRor]{.underline}](\l)
[[\#EXTra]{.underline}](\l)
For each header, only the capital letters are required for recognition
by Pmetrics. The blocks can be in any order, and header names are
case-insensitive (i.e. the capitalization here is just to show which
letters are required). Fortran is also case-insensitive, so in variable
names and expressions case is ignored. Details of each block are next,
followed by a [[complete example]{.underline}](\l).
#### Important: Sometimes it is important to preserve spacing and formatting in Fortran code that you might insert into blocks, particularly the \#EXTRA block. If you wish to do this, insert \[format\] and \[/format\] before and after any code that you wish to reproduce verbatim with spacing in the fortran model file.
#### Comments: You can insert comments into your model text file by starting a line with a capital "C" followed by a space. These lines will be removed/ignored in the final fortran code.
#### Primary variables
Primary variables are the model parameters that are to be estimated by
Pmetrics or are designated as fixed parameters with user specified
values. It should be a list of variable names, one name to a line.
Variable names should be 11 characters or fewer. Some variable names are
[[reserved]{.underline}](\l) for use by Pmetrics and cannot be used as
primary variable names. **The number of primary variables must be
between 2 and 32, with at most 30 random or 20 fixed.**
On each row, following the variable name, include the range for the
parameter that defines the search space. These ranges behave slightly
differently for NPAG, IT2B, and the simulator.
- For all engines, the format of the limits is *min, max*. A single
value will indicate that the parameter is to be fixed but unknown in
the population, i.e. the value is taken as the starting point for
the optimization, but the final value will depend on the model and
data and will be the same across the population. A single value
followed by an "!" will indicate that this value is to be held
constant (i.e. fixed and known) across the population, and not to be
estimated.
- For **NPAG**, when *min/max* limits are specified, they are
absolute, i.e. the algorithm will not search outside this range.
- For **IT2B**, the range defines the Bayesian prior distribution of
the parameter values for cycle 1. For each parameter, the mean of
the Bayesian prior distribution is taken as the middle of the range,
and the standard deviation is *xsig*\*range (see [[IT2B
runs]{.underline}](\l)). Adding a plus sign (+) to a line will
prevent that parameter from being assigned negative values. NPAG and
the simulator will ignore the pluses as the ranges are absolute for
these engines. Note that prior to version 1.5.0, this used to be an
exclamation point (!) but to be consistent throughout the model
file, the exclamation point is now used when fixed values are
desired.
- The **simulator** will ignore the ranges with the default value of
NULL for the *limits* argument. If the simulator *limits* argument
is set to NA, which will mean that these ranges will be used as the
limits to truncate the simulation (see [[Simulator
Runs]{.underline}](\l)).
Example:
\#Pri\
KE, +0, 5\
V, 0.01, 100\
KA, 0, 5\
KCP, 5\
KPC, 0 , 5\
Tlag1, 0, 2\
IC3, 0, 10000\
FA1, 0.5!
####
#### Covariates
Covariates are subject specific data, such as body weight, contained in
the data .csv file. The covariate names, which are the column names in
the data file, can be included here for use in secondary variable
equations. The order should be the same as in the data file and although
the names do not have to be the same, we strongly encourage you to make
them the same to avoid confusion.
Covariates are applied at each dose event. The first dose event for each
subject must have a value for every covariate in the data file. By
default, missing covariate values for subsequent dose events are
linearly interpolated between existing values, or carried forward if the
first value is the only non-missing entry. To suppress interpolation and
carry forward the previous value in a piece-wise constant fashion,
include an exclamation point (!) in any declaration line.
**Note** that any covariate relationship to any parameter may be
described as the user wishes by mathematical equations and Fortran code,
allowing for exploration of complex, non-linear, time-dependent, and/or
conditional relationships.
Example:
\#Cov\
wt\
cyp\
IC!
where IC will be piece-wise constant and the other two will be linearly
interpolated for missing values.
####
#### Secondary variables
Secondary variables are those that are defined by equations that are
combinations of primary, covariates, and other secondary variables. If
using other secondary variables, define them first within this block.
Equation syntax must be Fortran. It is permissible to have conditional
statements, but because expressions in this block are translated into
variable declarations in Fortran, expressions other than of the form \"X
= function(Y)\" must be prefixed by a \"&\" and contain only variables
which have been previously defined in the Primary, Covariate, or
Secondary blocks. Note that prior to version 1.5.0, the continuation
symbol was "+" before each line, but to avoid confusion with the use of
"+" in the Primary block for IT2B models, and to be consistent with
Fortran notation, the "&" is used henceforth.
Example:
\#Sec\
CL = Ke \* V \* wt\*\*0.75\
& IF(cyp .GT. 1) CL = CL \* cyp
####
#### Bolus inputs
By default, inputs with DUR (duration) of 0 in the data .csv file are
\"delivered\" instantaneously to the model compartment equal to the
input number, i.e. input 1 goes to compartment 1, input 2 goes to
compartment 2, etc. This can be overridden with NBOLUS(input number) =
compartment number.
Example:
\#Bol\
NBCOMP(1) = 2
####
#### Initial conditions
By default, all model compartments have zero amounts at time 0. This can
be changed by specifying the compartment amount as X(.) = expression,
where \".\" is the compartment number. Primary and secondary variables
and covariates may be used in the expression, as can conditional
statements in Fortran code. An \"&\" continuation prefix is not
necessary in this block for any statement, although if present, will be
ignored.
Example:
\#Ini\
X(2) = IC\*V (i.e. IC is a covariate with the measured trough
concentration prior to an observed dose)\
X(3) = IC3 (i.e. IC3 is a fitted amount in this unobserved compartment)
In the first case, the initial condition for compartment 2 becomes the
value of the IC covariate (defined in \#Covariate block) multiplied by
the current estimate of V during each iteration. This is useful when a
subject has been taking a drug as an outpatient, and comes in to the lab
for PK sampling, with measurement of a concentration immediately prior
to a witnessed dose, which is in turn followed by more sampling. In this
case, IC or any other covariate can be set to the initial measured
concentration, and if V is the volume of compartment 2, the initial
condition (amount) in compartment 2 will now be set to the measured
concentration of drug multiplied by the estimated volume for each
iteration until convergence.
In the second case, the initial condition for compartment 3 becomes
another variable, IC3 defined in the \#Primary block, to fit in the
model, given the observed data.
####
#### F (bioavailability)
Specify the bioavailability term, if present. Use the form FA(.) =
expression, where \".\" is the input number. Primary and secondary
variables and covariates may be used in the expression, as can
conditional statements in Fortran code. An \"&\" continuation prefix is
not necessary in this block for any statement, although if present, will
be ignored.
Example:
\#F\
FA(1) = FA1
####
#### Lag time
Specify the lag term, if present, which is the delay after an absorbed
dose before observed concentrations. Use the form TLAG(.) = expression,
where \".\" is the input number. Primary and secondary variables and
covariates may be used in the expression, as can conditional statements
in Fortran code. An \"&\" continuation prefix is not necessary in this
block for any statement, although if present, will be ignored.
Example:
\#Lag\
TLAG(1) = Tlag1
#### Differential equations
Specify a model in terms of ordinary differential equations, in Fortran
format. XP(.) is the notation for dX(.)/dt, where \".\" is the
compartment number. X(.) is the amount in the compartment. **There can
be a maximum of 20 such equations.**
Example:
\#Dif\
XP(1) = -KA\*X(1)\
XP(2) = RATEIV(1) + KA\*X(1) - (KE+KCP)\*X(2) + KPC\*X(3)\
XP(3) = KCP\*X(2) - KPC\*X(3)
RATEIV(1) is the notation to indicate an infusion of input 1 (typically
drug 1). The duration of the infusion and total dose is defined in the
[[data .csv]{.underline}](\l) file. **Up to 7 inputs are currently
allowed.** These can be used in the model file as RATEIV(1), RATEIV(2),
etc. The compartments for receiving the inputs of oral (bolus) doses are
defined in the \#Bolus block.
####
#### Outputs
Output equations, in Fortran format. Outputs are of the form Y(.) =
expression, where \".\" is the output equation number. Primary and
secondary variables and covariates may be used in the expression, as can
conditional statements in Fortran code. An \"&\" continuation prefix is
not necessary in this block for any statement, although if present, will
be ignored. **There can be a maximum of 6 outputs.** They are referred
to as Y(1), Y(2), etc. These equations may also define a model
explicitly as a function of primary and secondary variables and
covariates.
Examples:
\#Out\
Y(1) = X(2)/V
\#OUT
RES = B(1) \* KIN/(KIN-KOUT) \* (EXP(-KOUT\*TPD)-EXP(-KIN\*TPD))
Y(1) = RES/VD
This second example is known as the Bateman equation for a model with
linear absorption (KIN) into and elimination (KOUT) from a central
compartment, and a time post-dose (TPD) or lag time. Here B(1) is the
oral bolus dosing vector for drug 1, and VD is the volume of the central
compartment.
#### Error
This block contains all the information Pmetrics requires for the
structure of the error model. In Pmetrics, each observation is weighted
by 1/error^2^. There are two choices for the error term:
1. error = SD \* gamma
2. error = (SD^2^ + lamda^2^)^0.5^ (Note that lambda is only available
in NPAG currently).
where SD is the standard deviation (SD) of each observation \[obs\], and
gamma and lambda are terms to capture extra process noise related to the
observation, including mis-specified dosing and observation times.
SD is modeled by a polynomial equation with up to four terms: C~0~ +
C~1~\*\[obs\] + C~2~\*\[obs\]^2^ + C~3~\*\[obs\]^3^. The values for the
coefficients should ideally come from the analytic lab in the form of
inter-run standard deviations or coefficients of variation at standard
concentrations. You can use the Pmetrics function makeErrorPoly() to
choose the best set of coefficients that fit the data from the
laboratory. Alternatively, if you have no information about the assay,
you can use the Pmetrics function ERRrun() to estimate the coefficients
from the data. Finally, you can use a generic set of coefficients. We
recommend that as a start, C~0~ be set to half of the lowest
concentration in the dataset and C~1~ be set to 0.15. C~2~ and C~3~ can
be 0.
In the multiplicative model, gamma is a scalar on SD. In general,
well-designed and executed studies will have data with gamma values
approaching 1. Poor quality, noisy data will result in gammas of 5 or
more. Lambda is an additive model to capture process noise, rather than
the multiplicative gamma model.
To specify the model in this block, the first line needs to be either
L=\[number\] or G=\[number\] for a lambda or gamma error model. The
\[number\] term is the starting value for lambda or gamma. Good starting
values for lambda are 1 times C~0~ for good quality data, 3 times C~0~
for medium, and 5 or 10 times C~0~ for poor quality. Note, that C~0~
should generally not be 0, as it represents machine noise (e.g. HPLC or
mass spectrometer) that is always present. For gamma, good starting
values are 1 for high-quality data, 3 for medium, and 5 or 10 for poor
quality. If you include an exclamation point (!) in the declaration,
then lambda or gamma will be fixed and not estimated. Note that you can
only fix lambda currently to zero.
The next line(s) contain the values for C~0~, C~1~, C~2~, and C~3~,
separated by commas. There should be one line of coefficients for each
output equation. By default Pmetrics will use values for these
coefficients found in the data file. If none are present or if the model
declaration line contains an exclamation point (!) the values here will
be used.
Example 1: estimated lambda, starting at 0.4, one output, use data file
coefficients but if missing, use 0.1,0.1,0,0
\#Err\
L=0.4
0.1,0.1,0,0
Example 2: fixed gamma of 2, two outputs, use data file coefficients but
if missing, use 0.1,0.1,0,0 for the first output, but use 0.3, 0.1, 0, 0
for output 2 regardless of what is in the data file.
\#Err\
G=2!
0.1,0.1,0,0
0.3,0.1,0,0!
####
####
#### Extra
This block is for advanced Fortran programmers only. Occasionally, for
very complex models, additional Fortran subroutines are required. They
can be placed here. The code must specify complete Fortran subroutines
which can be called from other blocks with appropriate call functions.
As stated earlier, sometimes it is important to preserve spacing and
formatting in Fortran code that you might insert into blocks,
particularly the \#EXTRA block. If you wish to do this, insert
\[format\] and \[/format\] before and after any code that you wish to
reproduce verbatim with spacing in the fortran model file.
#### Reserved Names
The following cannot be used as primary, covariate, or secondary
variable names. They can be used in equations, however.
----------------------- --------------------------------------------------------
**Reserved Variable** **Function in Pmetrics**
ndim internal
t time
x array of compartment amounts
xp array of first derivative of compartment amounts
rpar internal
ipar internal
p array of primary parameters
r input rates
b input boluses
npl internal
numeqt output equation number
ndrug input number
nadd covariate number
rateiv intravenous input for inputs when DUR\>0 in data files
cv covariate values array
n number of compartments
nd internal
ni internal
nup internal
nuic internal
np number of primary parameters
nbcomp bolus compartment array
psym names of primary parameters
fa biovailability
tlag lag time
tin internal
tout internal
----------------------- --------------------------------------------------------
####
#### Complete Example
Here is a complete example of a model file, as of Pmetrics version 0.40
and higher:
\#Pri\
KE, 0, 5\
V0, 0.1, 100\
KA, 0, 5\
Tlag1, 0, 3\
\#Cov\
wt\
C this weight is in kg\
\#Sec\
V = V0*wt\
\#Lag\
TLAG(1) = Tlag1\
\#Out\
Y(1) = X(2)/V\
\#Err\
L=0.4\
0.1,0.1,0,0\
*Notes*:
By omitting a \#Diffeq block with ODEs, Pmetrics understands that you
are specifying the model to be solved algebraically. In this case, at
least KE and V must be in the Primary or Secondary variables. KA, KCP,
and KPC are optional and specify absorption, and transfer to and from
the central to a peripheral compartment, respectively.
The comment line "C this weight is in kg" will be ignored.
### Brief Fortran Tutorial
Much more detailed help is available from
[[http://www.cs.mtu.edu/\~shene/COURSES/cs201/NOTES/fortran.html]{.underline}](http://www.cs.mtu.edu/~shene/COURSES/cs201/NOTES/fortran.html).
------------------------- ----------------
**Arithmetic Operator** **Meaning**
\+ addition
\- subtraction
\* multiplication
/ division
\*\* exponentiation
------------------------- ----------------
------------------------- ----------------- -----------------------
**Relational Operator** **Alternative** **Meaning**
\< .LT. less than
\<= .LE. less than or equal
\> .GT. greater than
\>= .GE. greater than or equal
== .EQ. equal
/= .NE. not equal
------------------------- ----------------- -----------------------
+---------------------------------------+------------------------+
| **Selective Execution** | **Example** |
+---------------------------------------+------------------------+