/
manual_body.tex
1653 lines (1373 loc) · 80.5 KB
/
manual_body.tex
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
%!TEX root = manual_booklet.tex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Introduction} Pirana is a powerful
modeling environment for NONMEM, PsN and Xpose, offering a graphical
user interface and many auxiliary tools to support modeling \& simulation analyses.\\
\noindent Development of Pirana was started in 2007 as an open source
project. As of version 2.4.0, Pirana is released under a commercial
license for non-academic users, while it is released (free of charge)
under a Creative Commons license for academic users. Pirana is
designed to be very flexible, and extendible: it integrates
with many existing software such as R, Excel, and Berkeley Madonna, and it runs on all major operating systems.\\
\vspace{1pt} \noindent We attempt to make Pirana as intuitive as
possible, but reading this manual before or while you start working
with Pirana is recommended. For many
common functionality in Pirana, a Quick Guide is available (from
Pirana's help-menu, or from www.pirana-software.com). Also have a look at our website for more information and an FAQ. If you're still in the dark at some point, please do not hesitate to contact us.
\vspace{20pt}
\noindent \scriptsize{info@pirana-software.com} \normalsize
\pagebreak
\newpage % one page left blank intentially
\thispagestyle{empty}
\mbox{}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Pirana installation}
Software requirements are summarized below, followed by some additional details on the installation procedure.
\section{Required / recommended software}
Although the only real requirement is an installation of NONMEM, some additional software is highly recommended for optimal use of Pirana, while other softwares might be useful as well.
\begin{description}
\item[\textcolor{Red}{NONMEM}] Pirana can use both standard
`from-CD'-installation of NONMEM and NMQual NONMEM
installations. NONMEM doesn't have to be installed on your local PC,
since Pirana can also connect to other PCs or clusters.
\item[\textcolor{Blue}{PsN}] Strictly, Pirana does not require PsN
installed, although the PsN-toolkit is highly recommended. The latest
version of PsN can be obtained from \textcolor{Grey}{http://psn.sourceforge.net/}.
\item[\textcolor{Blue}{Xpose}] This R-package for model diagnostics is
highly recommended and can be obtained from
\textcolor{Grey}{http://xpose.sourceforge.net}. Xpose datasets can
be selected and loaded in R/Xpose, and an Xpose GUI is available
within Pirana.
\item[\textcolor{Blue}{R}] This open-source software can be
obtained from \textcolor{Grey}{http://www.r-project.org/}, and is highly
recommended for optimal use of Pirana. R Studio
(\textcolor{Grey}{http://www.r-studio.org/}) is a powerful GUI for
R that works well with Pirana.
\item[\textcolor{Grey}{WFN}] Not required/recommended. Pirana offers only basic
support for Wings for NONMEM.
\item[\textcolor{Grey}{NMQual}] Recommended for keeping an audit trail of NM
installations and autamatically performing bug-fixes. Pirana
supports the use of NMQual NONMEM installations. NMQual also
requires Perl and the module XML::XPath installed. More details can
be found at the Metrum website
\end{description}
\section{Installation}
\subsection{Installation procedure on Windows} Download the installer
from the Pirana website, and install to any location on your hard-drive. Before exploring
Pirana's functions, you should first check your settings ('File
$\rightarrow$ Settings $\rightarrow$ General...') and software
integration ('File $\rightarrow$ Settings $\rightarrow$ Software
locations...'). If you want to connect to clusters, also update the
`Cluster' settings. Pirana is tested on XP, Vista, 7, and 8. Upon installation,
Windows may complain that installation is not safe, but this warning can be ignored.
\subsection{Installation procedure on Mac OS X} On Mac, you should
first install the Xcode tools, which are
included as optional installs on the (Snow) Leopard install DVDs. In the most recent OSX versions, Xcode can be installed from the App Store. After installing Xcode, make sure you also install the Command Line Tools (From within Xcode, go to `Preferences', and `Downloads'). Secondly you will have to install an X-window manager (either X11 or XQuarts). For old versions of OSX, X11 is most likely already installed. If you are running Lion or later, you will however have to install XQuartz instead of X11, which is downloadable online (google for `XQuartz'). Pirana for Mac is distributed as an executable, so no Perl installation is required, but it is also possible to run from source (see Linux explanation). When opening Pirana for the first time, your system may complain that Pirana is not safe, since it is not installed from the App Store. In this case, you will have to set your security settings in your systems `Preferences' to run apps from `Everywhere', instead of from `App Store only'.
\subsection{Installation procedure on Linux} For Linux, an executable
is made available as well. This executable is compiled on a 32-bit
system. If for some reason this executable doesn't run on your system,
the Perl source-code can be executed directy in Perl. This requires
manual installation of a few additional libraries and modules, see below.
\subsubsection*{Installing Perl and X11 development libraries}
For Pirana to be able to create the GUI, the X11 development libraries
(libX11-dev) should be installed, as well as the Perl/Tk module. In
Ubuntu / Debian, you can use the Synaptic package manager to install
these, or using apt from the shell:
\begin{lstlisting}
sudo apt-get install libX11-dev perl-tk
\end{lstlisting}
\subsubsection*{Installing additional Perl modules}
\noindent Pirana makes use of a number of publicly available
Perl-modules, which should also be installed. Some of these modules
are likely to be already installed with you current Perl distribution,
while others have to be installed manually. Below is a short guidance
on how to install these modules. Further guidance on installing Perl
modules can be found here: \textcolor{Blue}{
http://www.cpan.org/modules/INSTALL.html}). To make a connection to
the Perl module archive (CPAN), type:
\begin{lstlisting}
sudo perl -MCPAN -e shell
\end{lstlisting}
\noindent The following commands may be needed to set up the CPAN
shell to be able to correctly `make' the modules into your Perl distribution.
\begin{lstlisting}
o conf make /usr/bin/make
o conf make_install_make_command 'sudo make'
o conf commit
\end{lstlisting}
\noindent Next, use the `install' command to install required modules
into your Perl distribution (mind the case-sensitivity for the module
names). Look in Some of these may already be installed, which will be reported
as such. If you cannot install some modules from CPAN directly, you
have to download and install these modules (and their
dependencies) manually. Look in the file pirana.pl to see which
modules to install (this may change between Pirana versions).
\begin{lstlisting}
install Tk::PlotDataset
install Tk::JComboBox
install ...
\end{lstlisting}
\noindent Some required modules cannot be installed directly from
CPAN. These modules are supplied with Pirana (in the folder
`/packages') and should be installed manually. From within each of the
two package folders, execute in a shell:
\begin{lstlisting}
perl Makefile.PL
make
sudo make install
\end{lstlisting}
\vspace{8pt}
\noindent\scriptsize{\textcolor{Blue}{Note:} \textcolor{Grey}{Checking
whether Perl modules are installed correctly can be done by executing the
following in the terminal window, e.g.: perl -e 'use Tk' which should
result in no error messages.\\ } } \normalsize
\subsubsection*{Pirana installation}
\noindent After installing these Perl modules, copy the entire pirana
folder contained in the zip-file to e.g. your home folder
(/home/username/) or /opt/pirana/ if you are system
admin. Make sure that all perl files in that folder have
execution rights. To grant these rights to yourself you can execute
the following in the shell from within the Pirana folder:
\begin{lstlisting}
sudo chmod 711 -R *
\end{lstlisting}
\subsubsection*{Pirana execution}
\noindent Pirana can now be started from the command line using
\begin{lstlisting}
perl pirana.pl
\end{lstlisting}
\noindent from within the Pirana folder. Pirana was tested on Ubuntu
(9.04-12.04), OpenSUSE (11.1), and Arch Linux, with Perl
distribution 5.10.0 or lower. Pirana should work on any Linux distribution
with X-windows and Perl/Tk installed.
\section{Installation of license file} License files can be installed by going to `Help' $\rightarrow$ `Import license file'. On Windows, you can also install the license file by dropping it on the Pirana main window.
Upon starting Pirana, the presence of a valid license file (pirana.lic) in Pirana's main installation folder will be checked.
If no valid license file is present there, the following locations will also be checked in succession (later finds will override earlier finds):
\begin{itemize}
\item Pirana settings folder (`\~{}/.pirana/pirana.lic')
\item User home folder (`\~{}/pirana.lic')
\item Metworx persistent user folder (`/data/pirana.lic')
\item specified using environment variable (e.g. `PIRANA\_LIC=/data/pirana.lic')
\item specified using command line argument (e.g. `--pirana\_lic=/data/pirana.lic')
\end{itemize}
If no valid license file is found on any of these locations, a message will be displayed and some functionality of Pirana will be
disabled. Academic, commercial, or trial license files can be obtained on the website.
\section{Configuration} Although many preferences will
be set correctly by default, we recommend to check at least the
settings detailed below. Familiarize yourself with
the other options as well, to get the most out of Pirana. Especially check the correct file extensions
for NONMEM model files and output files.
\begin{description}
\item[File extension of models] NONMEM control streams/model files. Default is .mod. Note that multiple
model file extensions can be specified separated by a comma, e.g. `mod,ctl'.
\item[File extension of results] NONMEM output. Default is .lst
\item[Software settings] Pirana needs to know where other important software is installed,
which is specified under `Software' from the `File' menu. References
to software that you do not have installed, may be disregarded as they
are ignored by Pirana.
\item[Code editor] Preferably an editor syntax-highlighting. We
recommend the use of Emacs (all OS), PSPad (Windows), ConTEXT (Windows), Sublime Text 2 (MacOSX). If none is
entered, or a non-existing program is specified, Pirana will use its
built-in NM-TRAN editor.
\item[R location] The location (folder) of R, e.g. C:/Program
Files/R/R-2.11.0. On Windows, at first start-up of Pirana it will
search for the latest version of R that is installed, and
automatically updates this setting accordingly. If R is installed in
a non-standard location, please update this.
\item[R GUI] The GUI to be used for R-scripts. Recommended for this is
RStudio or Emacs/ESS, but the RGUI supplied with the R distribution
can also be used.
\item[spreadsheet] The location of your spreadsheet application,
e.g. Excel or Gnumeric. Pirana tries to find your spreadsheet
automatically.
\end{description}
\vspace{10pt}
\noindent\scriptsize{\textcolor{Blue}{Note:} \textcolor{Grey} {on Mac OSX you can either specify the application name
(e.g. "Microsoft Excel"), or the actual location of the application
(e.g. "/usr/local/bin/emacsclient").}
\normalsize
\newpage
\section{Configuration for modeling groups}
IT admins that want to distribute Pirana to a modeling group with
pre-specified settings can do so by editing the files in the folder \textit{ini\_defaults}
before distributing Pirana. This will allow users to start with appropriate defaults for Pirana's setting. Also, one
or more clusters can be added by default, so that users do not have to
add these themselves (and only have to update their username and login). Look in
the file /ini\_defaults/clusters/readme.txt for further
information.
\subsubsection{Configuration files location}
If even more control is required, i.e. if the end-user should not be
allowed to change part of the configuration at all, it is possible to
change the location of the configuration files from the user's home
directory to a different, protected shared location. The default location for
Pirana's configuration files can be overriden by using the file
\textit{ini\_locations.ini} located in the folder where you installed
Pirana. Change the central ini-files rights to read-only, to be sure users do
not change the central settings. More information about how to use
this functionality is available in the annotated \textit{ini\_locations.ini}
file itself.
\newpage % one page left blank intentially
\thispagestyle{empty}
\mbox{}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Using Pirana}
\section{Overview}
\subsection{Basic functions} The Pirana window consists of a large
area showing an overview of models in the current folder, and a
smaller area on the right. The main overview acts as an `electronic lab-notebook' for
modeling analyses. The list on the right shows e.g. data files, R-scripts,
Xpose datasets, or all files in the active folder, or alternatively a
list of parameter estimates or reports. Most buttons in Pirana's main
screen are accompanied by a short description which is displayed if
hovered above with the mouse pointer. Some specific functionality is
detailed below. By selecting a model or (data-) file in either lists
and right-clicking the mouse, a menu with actions on models or run
results is shown. Most of Pirana's functionality is available from
this menu, and most options are also available from the toolbar
(\textit{View} $\rightarrow$ \textit{Show toolbar}).
\begin{figure}[H] \centering
\includegraphics[scale=0.25]{images/pirana_main_screen.png}
\caption{Pirana main screen (on Linux)}
\end{figure}
\subsection{Model management} The main model overview is
where all models and subdirectories in the current working directory
are displayed. Only models are displayed that have a file-extension
corresponding to the file extension specified in the
\textit{preferences}. If multiple file extensions were specified, choose the
one you want to use in the current folder by selecting it from the listbox
(the one next to the folder selector, on the right above the main models list).
When models are double-clicked, the control stream is opened in the
code-editor (if specified), or else in Pirana's built-in NM-TRAN
editor.
\subsubsection*{Model views}
By default, the model overview is shown as a list, listing all models
ordered by run number. It is assumed models are named as a number
(e.g. '001.mod'), or prepended with 'run' (e.g. `run1.mod', or 'run001.mod'), see
`Conventions and Methods' for more information. By default, the list is shown in \textit{condensed mode},
meaning that for every model, a single row is used in the table. The
list can however also be shown in \textit{expanded mode}, which allows
for longer model descriptions and notes in the overview. Additionally,
in this mode all estimation methods are shown, while in condensed mode
only the last estimation method and associated OFV is shown.
An alternate view mode is \textit{tree view}, in which model development is
shown as a hierarchical tree. The tree is built using parent/reference
information included in the model files (see `run record' explanation in this manual). When creating models in Pirana, this information is added automatically, and adheres to PsN's run record syntax.
The columns that are shown in the main overview can be activated or de-activated from the \textit{View} $\rightarrow$
\textit{Show columns} menu. Models can be filtered using the `Filter' above the
main overview table, or by colors or flags.
\subsubsection*{Model actions}
\noindent New models can be created from scratch, from a template, by
using the Wizards, or by duplicating an existing model:
\begin{description}
\item[Wizards]\ Models can be created by using the PK model
wizard. Choose the desired model type and estimation method, and a
basic NONMEM model file will be created.
\item[Templates] Many basic template models are included. It is
possible to build your own library with base models that you often
use. Templates can be added by copying a model file to
\ttfamily{/templates }\normalfont in the Pirana directory. The
template models should have the same file extension as your model
files to be recognized as a template.
\item[Duplication] Duplication of models can be performed by
selecting the parent model and clicking `duplicate' from the
context-menu (right click on the model). Optionally, final parameter estimates
from the reference model can be updated in the new model, and also
model-file numbers in \$TABLE and \$EST records. Some basic syntax
rules should be adhered to ensure correct interpretation of final
estimates, see Conventions and Methods at the end of this chapter. A
model can also be \textit{Duplicated for MSF restart}. This means that the
model file is duplicated, but an \$MSFI record is added, parameter
estimate blocks are commented out, and the \$MSFO record is updated.
\begin{figure}[H] \centering
\includegraphics[scale=0.4]{images/duplicate.png}
\caption{Duplicate model}
\end{figure}
\end{description}
\subsubsection*{Notes, flags and colors}
To each model / run in Pirana, notes can be added. Also, flags and
colors can be added, indicating \textit{key runs}, \textit{good runs},
or \textit{bad runs}. Of course the meaning of the flags and
color-coding is all up to the user. The notes and color info are
stored in a database file (\textit{pirana.dir}), which is created
automatically in each folder that holds models. To add notes to a
model, select the model, right click and select \textit{Model}
$\rightarrow$ \textit{Notes and info}, or using the \textit{Ctrl-I} shortcut. Models and results can be given a color by selecting the model, right-clicking, and selecting the desired color/flag from the \textit{Colors \& flags} submenu. Tip: Pirana supports filtering of models/runs by color.
\vspace{8pt}
\noindent
\scriptsize{
\textcolor{Blue}{Note:} \textcolor{Grey}{In each active folder that
is visited with Pirana, a small SQLite database is created
(`pirana.dir') which is able to store information about models. So
if you archive your projects manually, make sure to include these files as
well. }
}
\normalsize
\subsection{Projects} Pirana allows you to save a link to a folder as
a project, which will then be shown in the blue bar (above the active folder
entry). This allows you to quickly switch to the directory that is
linked to that project. To add a project to the list, browse to a
folder by clicking on the folder-icon next to the location bar, or by
clicking through the directory-listing in the model overview. Next,
click on the \textit{disk}-icon next to the project name, give your
project a unique name and press `Save'. Your project is now available
from the listbox. To delete a project from the list, click the trash
icon next to the project list. The green refresh-icon refreshes the
view of the current directory, and should be applied when you make
changes to models or add files outside of Pirana. Also when a run is
finished, you should refresh to gather the results into Pirana.
\subsection{Data files} The list on the right of the screen shows
files in the current folder, if `Files' is selected as the active tab. Pirana can show tab-files, csv-files, R scripts, Xpose files, and other files, which can be selected from the list above. It is also possible to specify your own
filter. Right-clicking on a selected file shows a menu with possible
actions on the file.
\vspace{8pt}
\noindent\scriptsize{\textcolor{Blue}{Note:} \textcolor{Grey}{When the
Xpose option is chosen, only unique run numbers are shown, instead
of all tabualar data files. After selecting an Xpose dataset,
click the `Open in R' the right-click-menu, and R read in the
datasets and create the Xpose object. } \normalsize
\section{Working with NONMEM}
There are several ways in which NONMEM can be used from Pirana. The
first one is to use the nmfe-script supplied with NONMEM. For this,
you have to instruct Pirana where NONMEM is installed. The other
(recommended) way to run NONMEM, is to use PsN. When you run NONMEM
through PsN, you don't have to tell Pirana where NONMEM is located,
since this is already specified in the \textit{psn.conf} file of PsN.
\subsection{Managing NONMEM installations} Existing NONMEM
installations can be added to Pirana via the Settings menu, under the
NONMEM tab. Here, both local (upper) and cluster (lower) installations
can be added for use in Pirana. A \textit{smart search} tool is implemented
for local NONMEM installations, which searches for NONMEM
installations in the most common locations on your local drives. If
you have installed NONMEM in a non-common location, or want to use
NONMEM on a remote cluster, add the paths to NONMEM manually.
\begin{figure}[H] \centering
\includegraphics[scale=0.31]{images/nonmem_settings.png}
\caption{NONMEM settings window}
\end{figure}
\subsection{Setting environment variables}
NONMEM requires a Fortran compiler installed. For
this compiler to function properly, it is important to set the
environment variables correctly. Especially for Intel compilers, this
can be trooublesome, as different environmental variables need to be
defined. For GNU compilers, setting the PATH environment variable is
usually sufficient. There are several ways you have control over the
environment variables when using Pirana:
\begin{enumerate}
\item In the settings menu, under \textit{Environmental variables},
the PATH variable used within the Pirana environment can be defined,
or additional folders can be added to the existing PATH. Also,
additional environmental variables can be defined here.
\item Alerntatively, in the same settings screen for each nmfe-run
that is started, you can specify a command that will be executed
before starting nmfe-type runs, which can be e.g.
\begin{lstlisting}
PATH=%PATH%;C:\gfortran\bin
\end{lstlisting}
\item At startup, Pirana will check for the existence of 2 files in
the Pirana base folder: \textit{set\_env.txt} and
\textit{add\_env.txt}. These files can be used to either set, or add
to the system variables, respectively. The files may look e.g. like
this:
\begin{lstlisting}
PATH=C:\nmvi\run;C:\MinGW\bin
VARX=C:\bladibla;etc
\end{lstlisting}
\end{enumerate}
\clearpage
\subsection{Running models}
As mentioned before, a model can be run using \textit{nmfe} directly, \textit{PsN} or
\textit{WFN} (Windows only). This can be done by selecting a model from the list, and
right-clicking to show the context-menu. From here, you can either
select NONMEM-nmfe, or the PsN or WFN options. The commands are also
available from the toolbar. WFN is disabled by default.
\subsubsection*{Using nmfe}
Execute a model using `Run (nmfe)', or press Control-R. This will open up a
dialog showing two additional options
for running the model, e.g. which NONMEM installation to use, and if
models should be executed in separate folders or on a cluster system.
\begin{figure}[h] \centering
\includegraphics[scale=0.5]{images/nmfe_run.png}
\caption{nmfe run window}
\end{figure}
\noindent Pirana supports the use of the parallelization functionality available
in NONMEM 7.2. When you select a NONMEM 7.2 installation in the nmfe
run window, the available parallization files (\textit{parafiles}) are displayed under the parallelization tab. \textit{Parafiles} can be generated using the Wizard in Pirana. You can also have Pirana generate the \textit{parafile} on-the-fly (select \textit{auto-MPI} or \textit{auto-FPI}). Under Settings $\rightarrow$ Parallelization, the FPI and MPI files that Pirana generates can be specified.
\vspace{5pt}
\noindent Parallization files can be imported from local or remote locations. Local import can be performed through Settings $\rightarrow$ NONMEM. Remote parallelization files can be imported from a cluster location defined under Settings $\rightarrow$ SSH.
\begin{figure}[H] \centering
\includegraphics[scale=0.27]{images/settingsparallization.png}
\caption{Automatic parallelization file}
\end{figure}
\clearpage
\subsubsection{Using PsN}
PsN is an extensive toolkit for advanced modeling \& simulation, and
contains essential tools such as bootstrapping, visual predictive
checks (vpc), stepwise covariate modeling (scm), simulation and
re-estimation (sse), and many more. All PsN-toolkit functions can be
accessed from Pirana using the right-click menu or the toolbar. \textit{Execute} is
also conveniently available using the Ctrl-e keyboard shortcut. The
dialog window is then opened (shown below), which can also shows the
PsN-help info for the selected command. The command line editor can be
used to specify additional parameters to the PsN funtion. Pirana
stores each executed PsN command, which are available from the
'History' button.
\begin{figure}[H] \centering
\includegraphics[scale=0.42]{images/Figure2_4_PsNdialog2.png}
\caption{PsN dialog window}
\end{figure}
\noindent From the PsN tab in the Settings window you can define the default
command line parameters for most PsN functions. Some of PsN's functions are not related to models, but to datasets, such as data\_stats, \textit{create\_subsets} etc. These functions can be invoked from the file list on the right by selecting a file and opening the menu by right-clicking the mouse. A similar interface will be opened
as for PsN's model functions.
Similar to the nmfe dialog window, the PsN dialog also offers the possibility to
easily setup parallel execution. Pirana can be instructed to auto-generate
the MPI/FPI file required for parallel execution. When MPI or FPI, and the number of nodes are selected,
Pirana will automatically add the required PsN arguments ({\tt -parafile} and {\tt -nodes}).
\subsubsection*{Using Wings for NONMEM}
On Windows, Pirana is
capable of invoking the WFN-commands \emph{nmgo} and \emph{nmbs}, for
run execution and bootstrapping respectively. Since
WFN does not support multiple model files to be processed by its
commands, when multiple models are selected, only the first model file
is executed. When the WFN method is selected, two parameter
specification bars will become visible. In the upper entry, run
parameters can be specified, e.g. for the bootstrap: `1 100' to
specify a bootstrap with 100 replicates. The lower parameter bar
specifies command-line parameters used when starting WFN.bat,
e.g. `g77 std' for specifying the compiler and the NONMEM version to
be used.
\vspace{10pt}
\noindent\scriptsize{\textcolor{Blue}{Note:} \textcolor{Grey} {What Pirana actually does when executing runs through WFN, is create a temporary batch-file in the current directory that starts \emph{WFN.bat} to load the necessary environment variables, after which \emph{nmgo} is started with the model-file and parameters specified.}
\normalsize
\clearpage
\section{Analyzing results \& output}
\subsection{Main overview}
After a model has been run/executed, and the folder is refreshed, Pirana will show the main results of the run in the main overview. It will show the OFV, the difference in OFV with the reference model (if specified), the number of significant digits, and some information about the estimation, i.e.:
\begin{description}
\item [S] means a succesful minimization (as reported by NONMEM)
\item [R] means estimation ended with rounding errors
\item [C] means a succesful covariance step
\item [M] means an unsuccesful covariance step due to matrix singularity
\item [B] means a boundary problem was reported by NONMEM
\end{description}
Pirana can also show the AIC and BIC values for the model, although these have to calculated first. See `Miscellaneous functionality' in this manual for more information.
\subsection{Parameter estimates}
A list of parameter estimates is shown in the right section of the Pirana window,
if `Estimates' is selected as the active tab. It also shows the RSE for parameters (between round brackets),
and shrinkage for the random effects (between square brackets). In this overview it is also highlighted if
final gradients for a parameter were zero (red foreground), mean of eta-distribution was significantly different from zero (etabar, red background), boundaries were encountered (blue background), or parameters were fixed (grey background).
A more detailed list is available by selecting \textit{Models $\rightarrow$ Parameter estimates} from the right-click menu, or from the toolbar. If just
one model is selected, Pirana will show all parameter estimates and
associated RSE values, if available. If multiple models/runs are
selected, Pirana will show the parameter estimates of these runs side
by side, facilitating comparison. These results can be easily
converted into CSV, LaTeX or HTML for e.g. reports or further
analysis. The estimates can be exported by R as well, by clicking the
R-icon in the parameter estimates area.
\begin{figure}[H] \centering
\includegraphics[scale=0.3]{images/estimates_window.png}
\caption{Parameter estimates window: Single run}
\end{figure}
\begin{figure}[H] \centering
\includegraphics[scale=0.3]{images/compare_estimates.png}
\caption{Parameter estimates window: Comparing multiple runs}
\end{figure}
\subsection{Run Reports} Run reports with model and run info, and parameter estimates can automatically be generated, and outputted as HTML, \LaTeX \hspace{2pt},
Word, or plain text format. The reports optionally displays basic run
information, run statistics, description and notes, and parameter
estimations, split by implemented estimation methods. The information to
be included in the report can be specified in the menu under `Settings
$\rightarrow$ Run reports'. \LaTeX \hspace{2pt} output is opened in
the specified code editor, but also can be converted automatically to
PDF using pdflatex (if installed).\\
\noindent After a run report is generated it will show up in the list
on the right, under the tab \textit{Reports}. In this tab, also
goodness of fit plots are shown, generated either using the Xpose GUI
in Pirana, or the R scripts library. Double-clicking on any of the
plots or reports will re-open them.\\
\vspace{10pt}
\noindent\scriptsize{\textcolor{Blue}{Note:} \textcolor{Grey} {In the
run reports, Pirana calculates the RSE for population parameters
as $RSE_{\theta_i} = \frac{SD_{cov,\theta}}{\theta_{i}}$, but doesn't take into account
log-transformation of parameters (e.g. when MU-modeling). For
inter-individual and residual variance ($\Omega$ and $\Sigma$),
RSE's are calculated as e.g. $RSE_{\omega_{i,i}^2} =
\frac{SD_{cov,\omega_{i,i}^2}}{\omega_{i,i}^2}$. RSE's given for
$\omega_{i,i}$ and $\sigma_{i,i}$ are calculated as e.g. $RSE_{\omega_{i,i}} =
\frac{SD_{cov,\omega_{i,i}^2}}{2 \cdot \omega_{i,i}^2}$ } \normalsize
\vspace{10pt}
\subsection{Intermediate results} When running models through any of
the available methods (nmfe / PsN / WFN), the intermediate results
(parameter estimates, objective function value, gradients) can be
viewed by clicking on the \textit{hourglass}-icon or from
\textit{Tools $\rightarrow$ Intermediate results}. This will open a
window which shows the models that are currently running. By clicking
on a run in the list, Pirana will parse the intermediate files and show the intermediate parameter estimates in the table and the plot. In the plot, you
can choose to show either the gradients (if a gradient method is
used), the intermediate estimates, or the objective function value
(OFV). Make sure that you specify PRINT=1 and MSFO=xxxxx in the
\$ESTIMATION record, to be able to obtain regularly updated
intermediate estimates. From the right-click menu, signals can be
sent to currently running NONMEM processes, such as \textit{stop} and
\textit{next iteration}.
\begin{figure}[H] \centering
\includegraphics[scale=0.3]{images/intermed.png}
\caption{Intermediate results}
\end{figure}
\subsection{Run Records}
For all models in the current folder, or a selection thereof, a CSV
run record can be compiled by Pirana that includes all
model and run characteristics, such as model description, estimation
method, objective function value, termination result, etc. An abridged
version of the run record can also be created as a plain text or Word
document.
\subsubsection*{Visual Run Record}
Pharmacometric model development most often progresses in a
hierarchical fashion, using the likelihood ratio test to assess
significance of improved fit between nested models. An appropriate
visualization of the model hierarchy will help the modeler gain better
understanding of key stages in model building, and willl aid in
communicating the model development history to others. Such a
visualization can be generated by Pirana, an example of which is shown below.
\begin{figure}[H] \centering
\includegraphics[scale=0.47]{images/vrr.png}
\caption{Visual Run Record}
\end{figure}
\noindent To create the VRR, Pirana produces Javascript code compatible with the Data-Driven
Documents Javascript library (d3.js). The visualization can be
generated as an SVG image in any modern internet browser. Several
options are implemented that allow customization of the visualization,
and both dynamic and static images can be created. In a VRR, the
hierarchy of models is immediately visible, and using the dynamic
collapsable dendrograms, non-relevant model threads can be hidden from
the visualization. The VRR also shows additional model information
when hovered over the nodes. Colors aid in visualizing the improvement
/ worsening of model fit (green / red), and whether the model has
children or not. In each branch, the nodes are ordered by OFV. When a
final model is specified, the modeling path can be made visible as a
blue line, thereby easily identifying the key runs. The visualization
can be implemented as a horizontal or radial tree, the latter of which
can be used when the model tree is very large.
\subsection{Data Inspector} Pirana is able to construct scatter plots
using the built-in \textit{DataInspector}, e.g. for quickly inspecting
goodness-of-fit, covariate relationships, distribution of etas,
performing data checkout etc. The DataInspector shows all the columns
present in the dataset, which can be mapped to the X- or Y-axis
(shown in figure 3.2). DataInspector can either be invoked by
selecting a model (main overview), or a data file (from the list on
the right). If a model is selected and DataInspector is started,
Pirana will gather the dataset specified in \$INPUT and the table
files created in \$TABLE. It will then ask the user which of these
files to open in DataInspector. If only one file is found, it will
open that one automatically.
\begin{figure}[H] \centering
\includegraphics[scale=0.35]{images/plot.png}
\caption{Pirana DataInspector}
\end{figure}
\subsection{Visual run records}
The model building process from initial to final model can be visualized using the visual run record.
This can be done via Results $\rightarrow$ Run records $\rightarrow$ Visual run record.
Here a final model can be selected, and the visual run record will be graphically depicted.
Pirana can parse NONMEM-generated tables, and CSV-files. Multiple Y values
can be plotted by holding the Control- or shift-key and selecting
multiple (up to three) data columns. Inside the plot, regions of
interest may be selected, which are then zoomed. Double-clicking
inside the plot region changes back to the previous view. Plots can
be filtered, which can be useful, e.g. to show only data for one
patient, or groups of patients or covariates.
In the text-box below the plot, code is generated that recreates
the same graph in R, either in \textit{base}, \textit{lattice}, or
\textit{ggplot2}. This code can be used as a starting
point for the generation of plots for manuscripts or
reports. Clicking the `R'-button will invoke the R-GUI or code
editor.
\subsection{R scripting for creating graphs and file processing}
Pirana includes functionality to run custom R-scripts on output from
models-executions such as NONMEM tables. Scripts can be written by the
user, but a considerable collection of scripts is also bundled with
Pirana, which can serve as starting point for your own
implementations. Scripts are located in three locations, one for
group-wide scripts (in the scripts-folder in the location where Pirana
is installed), one for user-scripts (`home/user/.pirana/scripts'
on Linux, `C:$\backslash$Documents and
Settings$\backslash$user$\backslash$Application
data$\backslash$.pirana$\backslash$Scripts' on Windows), and one for project-specific scripts, stored in the subfolder pirana\_scripts in the current folder. The folder
structure underlying the scripts folders is reconstructed within the
scripts menu, and scripts can be edited either by editing them from
outside Pirana, or by choosing them from the `Edit' menu option.
Scripts can be started by selecting a model, and selecting the desired
script from the scripts menu located in tight tab panel. Pirana invokes R and runs the script in the
directory `pirana\_temp' underlying the active folder. However,
before execution, Pirana replaces \textit{\#PIRANA\_IN} with an R
list-object which specifies model and results information, e.g. as:
\begin{lstlisting}
models <- list (
"003" = list (
"modelfile" = "003.mod",
"description" = "PK model digoxin",
"reference_model" = "002",
"data_file" = "nm_pk_001.csv",
"output_file" = "003.lst",
"tables" = c("003.TAB", "sdtab003")
)
)
\end{lstlisting}
\vspace{15pt} \noindent To automatically load PDFs or images that are created by
R after execution of the script, you should include e.g. the following line in
the script:
\begin{lstlisting}
#PIRANA model_output.pdf
\end{lstlisting}
\noindent where model\_output.pdf is the file that you want Pirana
to load. This may either be a PDF, or a common image format such as
PNG, JPG, or GIF. Please have a look at the scripts included with
Pirana for examples this
functionality.
\vspace{10pt}
\noindent\scriptsize \textcolor{Blue}{Note:} \textcolor{Grey} {
By default, R scripts started from Pirana will run in the same \textit{thread} as the main Pirana program. However,
for scripts that require long processing time this can be problematic, since Pirana cannot be used during
the execution of the script. If the following code is added somewhere in the R script, the script
will be run in a separate console instead and not block Pirana itself:}
\begin{lstlisting}
#PIRANA_NEW_CONSOLE
\end{lstlisting}
\normalsize
\subsubsection*{Interactive scripts}
From Pirana 2.6.0 onwards, Pirana has the ability to create
\textit{interactive scripts}, meaning that upon execution of an
R-script, the user will be presented with an
interface that shows plotting and input options. The plotting options can be
specified in the R-script like e.g.:
\begin{lstlisting}
### <arguments>
### <title label="Plot title">DV vs PRED</title>
### <x_var label="X-variable">DV</x_var>
### <xlab label="x-axis label">Dependent variable</xlab>
### <y_var label="y-variable">PRED</y_var>
### <ylab label="y-axis label">Pred. concentration</ylab>
### <subset label="Subset string"></subset>
### <split_id label="by ID" type="bool">FALSE</split_id>
### </arguments>
\end{lstlisting}
\vspace{4pt}
\noindent This will result in the following interface:
\begin{figure}[H] \centering
\includegraphics[scale=0.5]{images/interactive_scripts.png}
\caption{Interactive scripts}
\end{figure}
\noindent In the R-script, the specified options are then available
as the list \textit{arg}, e.g using:
\begin{lstlisting}
ggplot (data=tab, aes (x=get(arg$x_var),
y=get(arg$y_var))) + geom_point()
\end{lstlisting}
\subsection{Xpose support}
After selecting a model, Xpose can be invoked from the scripts menu either by
selecting the integrated Xpose GUI or the calling the (external) Xpose R-menu.
The integrated Xpose GUI allows for execution of Xpose commands. The user can also add
optional arguments to Xpose commands. Plots can be saved as PDF or
PNG files, or Sweave/knitr code can be generated.
\begin{figure}[H] \centering
\includegraphics[scale=0.5]{images/xposewindow.png}
\caption{Xpose window}
\end{figure}
\noindent Besides the commands available in the list, you can also input your
own commands or statements to the list. Lists can be saved for easy
access later on. The general plotting arguments for PDF and PNG
(e.g. {\ttfamily width=10, height=8} can be set in the settings menu
under \textit{R/Xpose})
\subsection{Wizards}
As mentioned earlier, Pirana comes with several wizards, such as a
wizard to create a NONMEM model file, PsN-scm configuration files, and
parallelization files. You can alter these Wizards to your liking, as they are
implemented from wizard-specification files located in
\textit{/wizards} in the Pirana installation folder. Of course, it
is possible to create your own Wizards as well. Just create a
\textit{.pwiz} file in the wizards-folder and follow the instructions
in the template that is provided there. Wizards that are included with
the current version of Pirana are described below:
\subsubsection*{PK model}
This wizard allows stepwise construction of a range of PK models in
NONMEM. It includes all ADVANs in NONMEM, all estimation methods, and
the most commonly used residual error models. Of course, keep in mind
that you have to change the initial estimates and the \$DATA and
\$INPUT records to suit your PK problem.
\subsubsection*{NM parallelization file}
NONMEM 7.2 and higher allow parallization of single runs, which
requires a so-called `parafile', a configuration file for the
parallelization. These files can be created using this wizard.
\subsubsection*{SCM configuration file (PsN)}
The scm command in PsN requires a configuration file. With this wizard
you can create such a file, which includes the most commonly used
options. Please note that more features are available in the scm tool
than are offered as option in the Wizard, so it is advised to acquaint
yourself with the full scm documentation.
\subsubsection*{Dataset template}
This wizard can be used to create an R script that, in turn, generates
a NONMEM simulation data file with specified number of individuals,
doses, observations, dosing times, and covariates. This can be useful
e.g. for quickly setting up simulations in NONMEM.
%%%%
\section{Model translation}
Pirana can translate NM-TRAN models written in any ADVAN routine to
ordinary differential equations (ODEs). The model can be exported to
ADVAN6 (NM-TRAN), to R (using the deSolve library), Berkeley Madonna,
MATLAB and PopED. Also several translators are included that
translate specific parts of NONMEM code to alternate NONMEM code.
\subsubsection*{Translation to other tools}
For R, a multidose simulation is automatically implemented, for the
other converters only single dose simulation is implemented. Pirana
currently does not read in the dataset to extract dosing information.
Pirana extracts the parameter estimates for the structural model
($\theta$), and also the between subject variability matrix
($\Omega$). The latter is however done only when simulating in R or Berkeley Madonna (not available for Matlab at current).
No residual error model is currently implemented in any of the translators, but this can easily be added by the user.
Porting the model structure to PopED allows evaluation of optimal
study designs (OD). Pirana creates the necessary files for PopED execution, however
the user still needs to provider the details of the design and other optimization settings.
\subsubsection*{MU-model conversion}
Pirana can convert standard NONMEM models to MU-model coding. At
current, Pirana can only convert models written using normal- or
log-normal $\eta$s, e.g.
\begin{lstlisting}
CL = THETA(1) * EXP(ETA(1))
\end{lstlisting}
will be converted into:
\begin{lstlisting}
MU_1 = LOG(THETA(1)) ; ** MU-referenced by Pirana
CL = EXP(MU_1+ETA(1))
; Original equation: CL = THETA(1) * EXP(ETA(1))
\end{lstlisting}
\subsubsection*{Difference equations}
For some models written in ODEs, writing some parts of the model in
difference equations can considerably reduce computational burden, while
maintaining parameter precision.\footnote{Petersson KJ et al. J
Pharmacokinet Pharmacodyn. 2010 Oct;37(5):493-506.} Pirana can help
in setting this up: it will transport all code written in \$DES other
than the $\frac{dA}{dt}$ system to \$PK, and adds some required
code (using \textit{MTIME}).
\section{Batch operations}
Pirana offers functionality to perform batch operations on a set of
models, such as search and replace functions.
\begin{description}
\item{\textcolor{Grey}{Search and replace in models}} Replaces
a given search text with another string or block of text in
the selected models.
\item{\textcolor{Grey}{Replace block}} This function enables
you to replace a whole block of code in selected model
files, e.g. the \$DATA block if you want all model files to
use a different data file, or the \$THETA block if you want
to use other initial estimates.
\item{\textcolor{Grey}{Add code to models}} With this
function, lines of code can be added to the beginning or the
end of selected models.
\item{\textcolor{Grey}{Add code to blocks}} With this
function, lines of code can be added to a specific block in
the selected models.
\item{\textcolor{Grey}{Batch duplicate}} Creates multiple
duplicates of one model file, with (optionally) updated
run/table numbers and final parameter estimates.
\item{\textcolor{Grey}{Random simulation seeds}} In all
selected models, the \$SIMULATION block will be updated with
new seeds.
\end{description}
\section{Miscellaneous functionality}
\subsubsection*{NONMEM help files}
Modeling with NONMEM, and construction of NM-TRAN syntax can be
troublesome at times, and therefore it is convenient to have NONMEM's
help files at your fingertips. Pirana provides a user interface to
these help files, allowing you to filter on keyword. Before help file
interface can be used, the NONMEM help files need to be imported as
the files are not supplied with Pirana. For this, go to `Tools'
$\rightarrow$ `NONMEM' $\rightarrow$ `Import / update NONMEM help
files' to perform this. You can import the information from a local
NONMEM installation or from an installation located on a cluster (over
SSH). After succesful import, the NONMEM help interface is availabe
from the `Help' menu.
\subsubsection*{Code differences between models}
Pirana provides a tool to show code differences, similar to the
\textit{diff} functionality on Unix systems. If one model is selected
and the diff tool is activated (Right-click menu $\rightarrow$
`Model' $\rightarrow$ `Code difference between models'), Pirana will
show the difference between that model and the reference mode (if
specified). If two models are selected, Pirana will show the code
differences between these two models.
\begin{figure}[H] \centering
\includegraphics[scale=0.28]{images/diff.png}
\caption{Code difference between models}
\end{figure}
\subsubsection*{Model Archive: Automatic backup of models and results}
When editing and running models, Pirana can automatically backup all
versions of controlstreams and result files. When this feature is
activated (in the settings menu), intermediate versions of models and
results are saved in a separate folder, every time a model is changed,
or when a new results files is found. The archive can be accessed via
the \textit{Tools} menu, under the option \textit{Model
Archive}. Details of the run and (if applicable) parameter estimates
can be reviewed. Also, different versions of models can be compared
and restored. The internal Pirana database files (\textit{pirana.dir})
are also backup up, if it has been more than a week since the previous
backup.
\begin{figure}[H] \centering
\includegraphics[scale=0.35]{images/modelbackup.png}
\caption{Model backup / archiving window}
\end{figure}
\subsubsection*{Matrices}
Pirana can automatically extract the covariance, correlation and
inverse covariance matrices from a NONMEM 7+ run (cor/cov/coi files),
and show them in a spreadsheet-like window. These can then also be
automatically exported to an R object, for instance for simulation
purposes.
\begin{figure}[H] \centering
\includegraphics[scale=0.28]{images/cor.png}
\caption{Correlation matrix}
\end{figure}
\subsubsection*{Miscellaneous tools}
\begin {description}
\item{\textcolor{Grey}{Correlation calculator}} This opens the
built-in `Correlation Calculator', which can be used to re-calculate a
covariance to a correlation on the SD-scale. The formula for
correlation that is used is:
\vspace{10pt}
$ \rho_{i,j} = \frac{{\omega_{i,j}}^2 }{\omega_{i,i} \cdot \omega_{j,j} }
$
\vspace{10pt}
with $\rho$ specifying the correlation between two elements (i,j) in a
matrix, and $\omega$ specifying elements of $\Omega$ or $\Sigma$.