-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathDocSrc.texi
2059 lines (1589 loc) · 159 KB
/
DocSrc.texi
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
\input texinfo @c -*-texinfo-*-
@c %**start of header
@c ver 55.0 26-Aug-2014 Jacob Barhak - Previously University of Michichan: Aidan Feldman, Jacob Barhak, Morton Brown, Michael Kylman
@setfilename Documentation.info
@settitle MIcroSimulation Tool (MIST)
@c @setcontentfsaftertitlepage
@c @setshortcontentsaftertitlepage
@c %**end of header
@copying
Copyright @copyright{} 2013-2018 Jacob Barhak
Copyright @copyright{} 2009-2012 The Regents of the University of Michigan
This file is part of the MIcroSimulation Tool (MIST). The MIcroSimulation Tool (MIST) is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
The MIcroSimulation Tool (MIST) is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
@subheading Additional Clarification
The MIcroSimulation Tool (MIST) is distributed in the hope that it will be useful, but "as is" and WITHOUT ANY WARRANTY of any kind, including any warranty that it will not infringe on any property rights of another party or the IMPLIED WARRANTIES OF MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. THE AUTHORS assume no responsibilities with respect to the use of the MIcroSimulation Tool (MIST).
The MIcroSimulation Tool (MIST) was derived from the Indirect Estimation and Simulation Tool (IEST) and uses code distributed under the IEST name. The change of the name signifies a split from the original design that focuses on microsimulation. For the sake of completeness, the copyright statement from the original tool developed by the University of Michigan is provided below and is also mentioned above.
@subheading ORIGINAL COPYRIGHT
Copyright @copyright{} 2009-2012 The Regents of the University of Michigan. Initially developed by Deanna Isaman, Jacob Barhak, Morton Brown, Wen Ye.
Additional coding by Donghee Lee, Ray Lillywhite, Aidan Feldman.
Videos by Michael Kylman.
This documentation and software are part of the Indirect Estimation and Simulation Tool (IEST). The Indirect Estimation and Simulation Tool (IEST) is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
The Indirect Estimation and Simulation Tool (IEST) is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
@subheading Additional Clarification
The Indirect Estimation and Simulation Tool (IEST) is distributed in the hope that it will be useful, but "as is" and WITHOUT ANY WARRANTY of any kind, including any warranty that it will not infringe on any property rights of another party or the IMPLIED WARRANTIES OF MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. THE UNIVERSITY OF MICHIGAN assumes no responsibilities with respect to the use of the Indirect Estimation and Simulation Tool (IEST).
@end copying
@shorttitlepage
@titlepage
@title Indirect Estimation and Simulation Tool
@insertcopying
@end titlepage
@ifnottex
@node Top
@top About this Document
The MIcroSimulation Tool (MIST). Additional and updated information regarding the software and the project can be found online at the following web sites:
@html
<a href='https://github.com/Jacob-Barhak/MIST' target="_blank"> https://github.com/Jacob-Barhak/MIST</a>
@end html
@html
<a href="https://simtk.org/home/mist" target="_blank"> https://simtk.org/home/mist</a>
@end html
First is a short menu of links associated with the system. Below it you will find the table of contents.
@menu
* Overview:: Overview of the software.
* License:: Software usage and distribution agreement.
* About This Version:: Important information on the capabilities and limitations of this version of the system.
* Setup:: Instructions for installation and setup.
* Getting Started with MIST:: A quick guide for modeling a disease with MIST.
* Simulation:: Prediction of disease outcomes for a given population set according to the model.
* States:: States are the stages of a disease process.
* Model:: The representation of hypothesis of disease progression.
* Transitions:: The probability of progressing from one state to another.
* Populations:: Subjects and their characteristics.
* Parameters:: Parameters used by the system.
* Expressions:: Expression syntax.
* Reports:: Reports provided by the system.
* Utilities:: A set of useful utility programs.
* MIST over the Cloud:: running MIST in High Performance Computing environment and specifically over the Amazon Compute Cloud.
* Contact Information and Support:: Links for contact information and additional support.
@end menu
@contents
@end ifnottex
@node Overview
@chapter Overview
@heading Purpose:
To facilitate modeling of the progression of chronic disease such as diabetes so that investigators can evaluate the cost/utility of a proposed method of prevention, early diagnosis or intervention.
@heading Purpose:
Provide software infrastructure to support micro-simulation to support chronic disease modeling activities.
@heading Goal - Provide modeling framework to support Monte Carlo micro-simulation with the following capabilities:
@itemize @bullet
@item
Modeling language and compiler
@item
Graphic User Interface
@item
Programmer Interfaces
@item
Report Generator
@item
Repeatability and Traceability mechanism
@item
Archiving and documentation.
@item
High Performance Computing (HPC) ready for computing environment such as the cloud.
@item
Simulations Repeatability and Traceability support
@end itemize
@heading Significance:
The progression of chronic diseases, such as diabetes, is typically studied through Clinical Trials. Such trials typically a long and difficult process that take time and resources and produce a lot of information about observed phenomena.
Computational disease models attempt to explain those phenomena using mathematical formulas and computer programs. Such disease models are used to estimate burden of disease in future including Cost/Quality of Life. These models also allow to hypothesize and test what if scenarios virtually without need for human subjects.
Micro-simulation models are particularly useful since they allow running simulations at the individual level and showing the results for the entire population. Typically Monte-Carlo simulation is employed were random numbers are generated and simulations repeated many time to converge. This is computationally demanding and sometimes requires substantial computing power.
The MIcro Simulation Tool (MIST) addresses this need by providing an open source free modeling tool that allows running Monte-Carlo Simulations. It supports scaling simulations to High Performance Computing (HPC) environment. More specifically, MIST can runs over the cloud.
Additional and updated information regarding the software and the project can be found online at the following web site:
@html
<a href='https://github.com/Jacob-Barhak/MIST' target="_blank"> https://github.com/Jacob-Barhak/MIST </a>
@end html
For a video introductions and examples of use, please visit the following links:
@html
<a href='http://www.youtube.com/watch?v=AD896WakR94' target="_blank"> http://www.youtube.com/watch?v=AD896WakR94 </a>
<a href='https://www.youtube.com/watch?v=vyvxiljc5vA' target="_blank"> https://www.youtube.com/watch?v=vyvxiljc5vA </a>
@end html
@node License
@chapter License
@insertcopying
@node About This Version
@chapter About This Version
@section New in This Version
The main focus of this version was on compatibility and eazy deployment. Here are further details on changes:
@itemize @bullet
@item
Installation simplified
@item
SimTK repository and mailing list
@item
Linux compatibility improved
@end itemize
@section Notable Components from Previous Versions
The MIcro Simulation Tool (MIST) is a split from Indirect Estimation and Simulation Tool (IEST).
MIST only deals with Monte-Carlo Micro-Simulation and does not offer Markov Estimation capabilities, this simplifies the system significantly and facilitates the following improvements:
@itemize @bullet
@item
Improved population generation with genetic algorithm optimization towards objectives
@item
MIST runs over the cloud and on Sun Grid Engine clusters
@item
Reproducibility and traceability were improved and tested
@item
Simplification/improvement of Parameters / Models / Simulation Rules
@item
Redefinition of Table function to improve speed and remove previous issues
@end itemize
See the README.txt file supplied with the software for further information on changes and capabilities.
@node Setup
@chapter Setup
@section Environment
@itemize @bullet
@item
Microsoft Windows 7 or Linux - Ubuntu 12.04LTS recommended. Note that other environments may work, yet were not fully tested. Linux installation is for experts. Windows environment is recommended for novice users.
@item
The system needs scientific Python environment which supports Python 2.7 and includes numpy, matplotlib, and nose. It is recommended to use Anaconda:
@html
<a href='https://www.anaconda.com/download/' target="_blank"> https://www.anaconda.com/download/ </a>
@end html
@item
The system requires the library Inspyred: Bio-inspired Algorithms in Python version 1.0:
@html
<a href='https://pythonhosted.org/inspyred/overview.html' target="_blank"> https://pythonhosted.org/inspyred/overview.html </a>
@end html
@item
The system requires the WxPython library to use a Graphic User Interface:
@html
<a href='http://www.wxpython.org/index.php' target="_blank"> http://www.wxpython.org/index.php </a>
@end html
@item
The system can also run simulations in High Performance Computing (HPC) environment using Sun Grid Engine or the Amazon Elastic Compute Cloud. This is highly specialized and requires experts for the setup.
@end itemize
@section Software Installation
The system can be installed in several fashions in different platforms. There are even expert installations for High Performance Computing (HPC) for advanced and expert users.
For novice users it is recommended that you use Windows since it is the simplest to install and the Graphic User Interface (GUI) was developed there. For HPC features you will need to use a Linux installation.
@subheading Simple Installation Instructions:
@enumerate
@item
Download and Install Anaconda 2.7 from
@html
<a href='https://www.anaconda.com/download/' target="_blank"> https://www.anaconda.com/download/ </a>
@end html
@item
Install MIST into your anaconda directory by typing the following text in a command terminal: @code{conda install mist -c jacob-barhak}
@end enumerate
This installation should work on Windows and on Ubuntu Linux. Your working directory in this case would be MIST under the anaconda directory you chose during anaconda installation.
@subheading Alternative Expert Installation Instructions:
@enumerate
@item
Download and Install Anaconda 2.7 from
@html
<a href='https://www.anaconda.com/download/' target="_blank"> https://www.anaconda.com/download/ </a>
@end html
@item
Install the Inspyred library by typing the following text in a command terminal: @code{pip install inspyred} . For additional details see:
@html
<a href='https://pythonhosted.org/inspyred/overview.html#installation' target="_blank"> https://pythonhosted.org/inspyred/overview.html#installation </a>
@end html
@item
Install WxPython library by typing the following text in a command terminal: @code{conda install wxpython} . This library is needed for GUI only. For additional details and other ways to install WxPython see:
@html
<a href='http://www.wxpython.org/download.php#stable' target="_blank"> http://www.wxpython.org/download.php#stable </a>
@end html
@item
Download the file MIST-master.zip from github by typing the following URL in a web browser:
@html
<a href='https://github.com/Jacob-Barhak/MIST/archive/master.zip' target="_blank"> https://github.com/Jacob-Barhak/MIST/archive/master.zip </a>
@end html
@item
Unzip the file MIST-master.zip in a directory of your choice. This will be your working directory.
@end enumerate
@subheading To Test the Above Installations:
@enumerate
@item
Open a command line prompt/terminal and change the directory to your working directory using the command @code{cd <working directory>} - with a simple installation your working directory would be MIST subdirectory under your anaconda installation directory - for example @file{c:\Anaconda\MIST} on windows, yet this can be changed by the user, so be attentive.
@item
From the command line run the file TestCode.py. It will test the data definitions and algorithms and should take a few minutes. If you got an all caps "OK" at the end, then you installed the python environment correctly.
@item
Run MISTGUI.py to see the Graphic User Interface. If the main window shows up, then the WxPython part is installed correctly. You can try to file->load the file @file{Testing.zip} in the @file{InData} sub directory to see the examples.
@end enumerate
If you are an expert you can install and setup MIST to work in HPC environment. These expert installations may require professional support. Please feel free to use
@ref{Contact Information and Support}.
@subheading To run MIST Over the Cloud a More Complicated Setup is Needed:
@enumerate
@item
Install StarCluster
@html
<a href='http://star.mit.edu/cluster/docs/latest/installation.html' target="_blank"> http://star.mit.edu/cluster/docs/latest/installation.html </a>
@end html
@item
Follow the instructions on
@html
<a href='http://continuum.io/blog/starcluster-anaconda' target="_blank"> http://continuum.io/blog/starcluster-anaconda </a>
@end html
@item
If you have not done so already follow the Simple Installation Instructions from above on your machine
@item
Install the nfsshare.py plugin by copying the file
@html
<a href='https://github.com/scrappythekangaroo/StarClusterPlugins/commit/775500618279f2fd83e2b7365b5c86cf07e11975' target="_blank"> https://github.com/scrappythekangaroo/StarClusterPlugins/commit/775500618279f2fd83e2b7365b5c86cf07e11975</a>
@end html
to the StarCluster plugins directory.
@item
Change the config file to include all plugins of interest and add plugin parameters. At the end of setup the "Configuring StarCluster Plugins" section in the config file should have the following lines: @*
@code{
@*[plugin anaconda_plugin]
@*SETUP_CLASS = anaconda_plugin.ConfigAnaconda
@*
@*[plugin nfsshare]
@*SETUP_CLASS = nfsshare.NFSSharePlugin
@*SERVER_PATH = /mnt/vol0
@*CLIENT_PATH = /mnt/vol0
@*EXPORT_NFS_SETTINGS = sync,no_root_squash,no_subtree_check,rw
@*MOUNT_NFS_SETTINGS = vers=3,user,rw,exec,noauto
@*
@*[plugin webapp-packages-installer]
@*setup_class = starcluster.plugins.pypkginstaller.PyPkgInstaller
@*packages = inspyred
}
Also, the plugins should be declatred under the scection that has your cluster name using the following line:
@*@code{PLUGINS = anaconda_plugin , nfsshare , webapp-packages-installer}
For additional information see the following links:
@*@html
<a href='http://continuum.io/blog/starcluster-anaconda' target="_blank"> http://continuum.io/blog/starcluster-anaconda </a>
@end html
@*@html
<a href='http://star.mit.edu/cluster/docs/latest/plugins/pypkginstaller.html' target="_blank"> http://star.mit.edu/cluster/docs/latest/plugins/pypkginstaller.html </a>
@end html
@*@html
<a href='https://github.com/scrappythekangaroo/StarClusterPlugins/commit/775500618279f2fd83e2b7365b5c86cf07e11975' target="_blank"> https://github.com/scrappythekangaroo/StarClusterPlugins/commit/775500618279f2fd83e2b7365b5c86cf07e11975</a>
@end html
@item
Use the StarCluster put command to transfer MIST to the @file{/mnt/vol0} directory on the cluster
@end enumerate
@subheading It is also possible to run MIST simulations in Multi-core environment using Sun Grid Engine. If you wish to install Sun-Grid-Engine on a single machine for testing purposes:
@enumerate
@item
Follow the instructions on
@html
<a href='http://scidom.wordpress.com/2012/01/18/sge-on-single-pc/' target="_blank"> http://scidom.wordpress.com/2012/01/18/sge-on-single-pc/ </a>
@end html
@item
Follow the Quick Installation for Linux from above
@end enumerate
@section Running the Software - Simple Start
Open a command terminal and navigate to your working directory using the @code{cd <working directory>} - with a simple installation your working directory would be MIST subdirectory under your anaconda installation directory - for example @file{c:\Anaconda\MIST} on windows, yet this can be changed by the user, so be attentive. Then type @code{python MISTGUI.py}. The main form of the system, titled 'MIcroSimulation Tool', will open. This is further described in the next section, @ref{Getting Started with MIST}.
In some systems you can alternatively open the folder created during installation in a window and double-click @file{MISTGUI.py}.
After you get familiar with the system and use it for a while you may expand to expert use where you can run @ref{MIST over the Cloud}.
@node Getting Started with MIST
@chapter Getting Started with MIST
@section Running the Software
Open a command terminal and navigate to your working directory using the @code{cd <working directory>} command then type @code{python MISTGUI.py}. The main form of the system, titled 'MIcroSimulation Tool', will open.
@html
<br><img src='Images/mainform.jpg'><br>
@end html
Using this form the user can load and save data and access all system parameters. Here is a short description of the basic operations that one can perform with this form:
@subsection Handling Data Files
The system holds its data in files in a @file{zip} archive. Each file can contain many Projects / Models / Populations using the same or different terminology. The system can load this information and at the end of work the user can save the modified information back to a file. Note that while working with the system the information is never saved to a file until the user specifies the save in this form.
@subheading Loading a Data File
@enumerate
@item
From the menu bar at the top of the main form, select @strong{File}.
@item
From the @strong{File} menu select @strong{Open}.
@item
Select the requested filename/path of the data file from the new window that appeared and press the Open Button.
@item
The label at the top of the windows should show the path of the file and the project list (A) should show projects held within the loaded file.
@end enumerate
@subheading Saving a Data File
@enumerate
@item
From the menu bar at the top of the main form, select @strong{File}.
@item
From the @strong{File} menu select @strong{Save} to save under a default file name. Select @strong{Save As} to modify filename/path.
@item
The label at the top of the windows should show the updated path of the file if this was changed. Note that if a system overwrites an existing file it will maintain a copy of the old file under a file name with an extension of a numerical timestamp representing the time/date of the new file created. This backup file can be loaded into the system.
@end enumerate
In the event the system does not close properly any modifications made will be lost. A proper exit of the system will ask the user to save the information to file. The automatic backup mechanism during file saving helps track back changes in data and helps maintain integrity.
Note that the system does not lock files after loading them during work. Also note that saving records in the system is not the same as saving the file. Records and entities in other forms are saved to memory rather than to a file. The only way to save to a file is through the main form menu.
@subsection Projects
A project is the main entity defined in the system. Projects define the @ref{Simulation} that the system will run and can share information such as models or parameters.
All the projects currently loaded in the system are listed in the main form in the project list (A).
To view a project, double click its entry in the list (A) in the main form. The appropriate form will open.
To add a new project to the system, double click the text Add New Project at the top of the list (A). Then select the type of the project from the window that will open. The appropriate form will open.
@subsection The First Time Running the System
One way to familiarize yourself with the system is to load the test examples file @file{Testing.Zip} created by the system during installation. This file provides an implementation of all the simulation examples provided in the test example document @file{SimulationExamples.pdf} that is also created by the installation.
Each project is an example from this document. Double clicking on projects listed in (A) will open the project clicked upon. Clicking the buttons marked as (B,C,D,E,F) will allow exploring the underlying data that created these projects.
@section Work Flow with the System
Before working with the computer system, some preparation is required. This page describes the preparation stages and the workflow with the system from a more abstract view.
@subsection Literature Review
When developing a new model or modifying an existing model, it is essential to perform an extensive literature review and to consult with clinical experts who can describe the progression of the disease. During the literature review, it is important to identify studies that provide estimates of the transition probabilities for the progression of the disease through time.
@subsection Building the Disease Model
@subheading Understanding the Disease Structure
The information from the literature review must be translated into system terminology. This involves identification of important keywords that describe disease progression; these are then used in different categories defined by the computer system:
@itemize @bullet
@item
@ref{States} - define the condition of the individual
@item
Sub-process - a collection of states that describe a condition and may consistent of a sequence of several states. Subprocesses may occur in parallel to each other, or may be nested within a different subprocess.
@item
@ref{Parameters} - characteristics such as age, blood pressure, costs, and other parameters that affect the progression of the disease or change due to its progression.
@item
Rules - Logic statements that describe changes in the disease or in associated parameters
@end itemize
@subheading Building the Model Diagram
The identified states and sub-processes should be depicted as boxes in a diagram; the boxes should be connected with arrows to signify transitions between states. The output of this may look like:
@html
<br><img src='Images/modeldiagram.jpg'><br>
@end html
Also, the user should collect all known rules that describe parameter change such as Age increase and write those down.
@subsection Simulating Disease Progression
@subheading Define a Simulation Population Set
It is necessary to specify the population of individuals to whom the simulation should apply. The population should contain information about the initial states of each individual. Also, parameters to be used in the simulation should be defined in this set. Populations can be defined as data table or as formulas describing distributions.
@subheading Update and Enhance the Model
The model can be enhanced by adding rules for updating parameters used in the simulation. Examples of rules include:
@itemize @bullet
@item
Increase age every time period
@item
Update blood pressure value
@item
Calculate Quality of Life according to current health state
@item
Calculate cost of treatment
@item
Decide if treatment is applied
@end itemize
@subheading Run the Simulation
The simulation can then be performed to predict outcomes of disease progression over the defined population set. After analyzing the results, the simulation can be repeated after changing parameters or using a different population set to reflect different model conditions. Each change in the simulation may require creating a new simulation project. This can be easily done by copying the existing project.
For further details, please see @ref{Simulation} for details.
@node Simulation
@chapter Simulation
MIST uses Monte Carlo to simulate a disease process where subjects are defined by the user and followed each simulation step until death or until the end of the simulation.
A simulation is a process where each individual in the population progresses through the states of a model, based on a random distribution. The active states for each individual at each step in time are given in the results.
@section Creating a Simulation
A simulation is created by defining a new simulation project. Within this project the user can define the @ref{Model}, the model that guides the simulation, and the @ref{Populations, Population Set} as well as some other simulation parameters and additional simulation rules. The steps to create such a simulation project are:
@enumerate
@item
Define @ref{States} to be used in simulation.
@item
Set up @ref{Parameters} to be used during simulation.
@item
Set up the @ref{Model}.
@item
Set up Model @ref{Transitions}.
@item
Set up the @ref{Populations, Population Set}.
@item
Double click 'Add New Project' in the main window.
@item
In the 'Create New Project' window, select 'Simulation', and click OK.
@html
<br><br><img src='Images/simulation.jpg'><br><br>
@end html
@item
In the Project Definition form, give the Simulation a name (A).
@item
Select a Primary Model in the drop-down box (B). Note that you can drill down into the model and make changes by double clicking on the model or pressing the ... button near the name.
@item
Select a Population Set in the drop-down box (C). Note that you can drill down into the population set and make changes by double clicking on the population set or pressing the ... button near the name.
@item
Specify the number of Simulation Steps and Repetitions (D and E). Note that the number of repetitions for distribution based population defines the population size to be generated. Otherwise it defines the number or times the simulation should be repeated for each individual in the population data table.
@item
To add modification rules for parameters, follow instructions below.
@item
Click Save. The form can now be closed, or the simulation can be run. This will trigger validity checking of the data entered and if no error message is displayed, then the data has been saved to memory. Note that the information is not yet saved to a file.
@end enumerate
@section Simulation Rules
From within the Simulation Project form, select the appropriate tab. The tabs are ordered according to different stages in the simulation. Rules are defined from the bottom of the Simulation Project form (F,G,H,I).
Note that rules fall into the following categories that are represented in different tabs in the form:
@itemize @bullet
@item
Stage 0 - Initialization : This stage in simulation is applied once at the beginning of simulation. This is a good place to initialize parameters that are not defined in a population set, or to override the population set data. It is also a location where system parameters that affect the simulation can be overridden.
@item
Stage 1 - Pre-State Transition Rules : This stage in simulation is applied every simulation step before running the model. It is typically used to update parameter values before calculating transitions.
@item
Stage 2 - Execute State Transitions : This stage does not involve rules - instead it applies the transitions defined in the model.
@item
Stage 3 - Post-State Transition Rules : This stage in simulation is applied every simulation step after running the model. It is typically used to update parameters that are related to the new state defined by the model, for example costs associated with a new state.
@end itemize
After choosing a tab, it is possible to view the rules it contains in the rules table (L) and manipulate them as explained below.
@itemize @bullet
@item
@strong{Parameter} (F) - parameter to be modified by the rule and get the formula value. Double clicking opens the @ref{Parameters} form to allow adding new parameters.
@item
@strong{Occurrence Probability} (G) - probability that the function will be assigned to the parameter. This can also be used as an if statement by assigning a Boolean expression that evaluates to 0 or 1. Double clicking opens a larger box.
@item
@strong{Function} (H) - computational expression, which can use parameters as variables. This expression is calculated at simulation runtime and the value evaluated will be assigned as the new value of the parameter defined in (F). Double clicking opens a larger box and for CostWizard it opens a wizard.
@item
@strong{Notes} (I) - not used in computation - simply for reference. Double clicking opens a larger box.
@end itemize
To add a rule to the Simulation, click the upward arrow (J). It will then be added to the table of rules (L).
To remove a rule, highlight the entry in the rules table (L) and click the downwards arrow (K).
To modify a rule, click the downwards arrow (H) to move its contents to the lower row (F), perform modifications and then click the upward arrow (J) to return the modified rule to the rules table. When the rule is moved down, the next record is highlighted. The rule will be added just before the highlighted record; i.e., back into the same position unless you choose to modify the highlighted record. The return position of the rule can be changed by highlighting a different record or it can be added at the end of the rules table if no item is highlighted.
Note that it is possible to change the order of rules by highlighting different rules and using the (J),(K) arrow buttons, and this also allows copying rules.
@section Cost/Quality of Life (QoL) Wizard
When the Function (H) is CostWizard and the user double clicks the box, then the Cost/Quality of Life (QoL) Wizard is invoked. It visually shows the Cost / Quality of Life values and parameters in table that is easier to visualize and manipulate.
The cost wizard uses the formulas described in the paper:
Zhou H, Isaman DJ, Messinger S, Brown MB, Klein R, Brandle M, Herman WH. A computer simulation model of diabetes progression, quality of life, and cost. Diabetes Care. 2005;28(12):2856-63.
@subheading Adding a Parameter to the Cost/QoL Expression
@enumerate
@item
From within the Simulation Project form write a valid CostWizard expression such as CostWizard(0,1,[1],[1]) in the Function (H) then double click to lauch the CostWizard form:
@html
<br><br><img src='Images/costwizard.jpg'><br><br>
@end html
@item
First, select whether the wizard will be used to calculate Cost or Quality of Life by selecting one of those options in the drop-down (A).
@item
Enter an initial value for this Cost or Quality of Life in the box (B).
@item
Select a Parameter from the drop-down in the lower left (D) and enter a value in the box on the lower right (E). Finally, click the up arrow (F) to add the rule.
@end enumerate
@subheading Removing a Parameter to the Cost/QoL Expression
Within the Cost/QoL Wizard, highlight the row to be removed In (C), and click the down arrow (G).
@section Running a Simulation
In the main window, double-click the Simulation Project to be used. This opens the Simulation form. Verify the information and, when ready, click 'Run Simulation'.
Note that a simulation is influenced by several system option parameters associated with simulation and in some case also with system option parameters associated with population generation from distributions. See @ref{Parameters} for a complete list of these system option parameters.
@section Simulation Results
The results can be viewed within the Simulation form by clicking 'View Result'. This opens the Simulation Result form.
@html
<br><br><img src='Images/resultviewer.jpg'><br><br>
@end html
Every time a Simulation is run, it creates a new Simulation ID for the results; therefore, it is necessary to select the appropriate result ID from the drop-down field (A) at the top of the form. The default is the most recent result.
The columns of the result table report results for all the parameters associated with the simulation including, yet not limited, to the parameters defined in the population set. Within the table, the results are sorted by the Individual sort order in the population (Individual ID), then by the repetition number, then by time. In other words, the first block of result records will describe the first individual; within it the first block will describe the first repetition of the simulation; within it the first record will describe the initial condition as described by the population set. The record afterwards will describe the result of the first simulation step.
Note that a Project with results is considered locked. It is impossible to modify the project and any entity associated with the project such as the Model, or the population set it uses. This protects from ambiguity between project definitions and results. To modify a project with results, you will need to create a copy of it and possibly a copy of its model/population set and possibly other parameters.
@subsection Exporting Simulation Results
Within the Simulation Result form, click the 'Export To File' (B) button. This saves the table as a CSV file, which can be opened by another spreadsheet program.
@subsection Removing Results
NOTE: these actions CANNOT BE REVERSED. Use at your own risk.
To eliminate one set of results, make sure the appropriate Simulation ID is selected from the drop-down, and click the 'Delete' button (C).
To remove all results, click the 'Delete All' button (D).
Removing all results from a project will unlock it and will allow modification of some of its parameters.
@section Copying a Project
To copy a project, either click on the copy button at the top of the form or right click the mouse and select the copy record option from the pop up menu. This will create a new copy of the project that does not contain results and can be modified by the user. Note that the copied project name will have an extension with a number. This can be changed by the user.
To remove all results, click the 'Delete All' button.
@node States
@chapter States
@section Overview of States:
States are representations of either discrete stages of a disease or of processes.
@html
<br><img src='Images/modeldiagram.jpg'><br>
@end html
@subsection State Classifications:
States can be classified according to several types
@itemize @bullet
@item
@strong{Normal State} - a state in which a subject can remain or can progress into. Normal states are marked in the model above by black boxes (rectangles).
@item
@strong{Event State} - an instantaneous state; a subject entering this state will exit it in the same simulation step. Therefore all transition probabilities from an event state must sum to 1. Event states are marked in the model above by a diamond.
@item
@strong{Splitter States} - a division of one state into two or more parallel sub-processes. A splitter state requires a matching Joiner State in a valid model. A splitter state is represented in the diagram above by the black dot to the left of two or more arrows.
@item
@strong{Joiner State} - a union of two or more parallel sub-processes into one state, essentially 'canceling out' a splitter state. A Joiner state is always linked with a specific Splitter state. A joiner state is represented in the diagram above by the black dot to the right of two or more arrows.
@item
@strong{Terminal State} - when a terminal state is reached, the individual cannot progress into any other state and the simulation terminates for this individual. The terminal state is marked by a red box in the diagram above.
@item
@strong{Process} - a set of states that represent an entire disease process; it may contain other sub-processes within itself. Processes are marked as dashed boxes in the diagram above.
@end itemize
There must be one Main Process for each model, containing all the other states. The states can be thought of as a tree structure, where a Main Process can contain states and/or sub-processes, and a sub-process contains states and/or other sub-processes, and so on. During simulation a subject can be in several sub-processes in parallel simultaneously.
The probability for progressing from a state to another during a simulation step is set by the user in @ref{Transitions}. The probability of staying is a state in a simulation step is one minus the sum of probabilities to progress from that state into the following states.
@section Creating States
To set up a new state:
@enumerate
@item
From the main form, click the 'States' button on the left navigation pane.
@c modify image to have reference letters
@html
<br><br><img src='Images/states.jpg'><br><br>
@end html
@item
This form shows all states in the project. To add a new state, press the 'Add' button (A) on the top right of the form, and a new blank row will appear.
@item
Enter the title of the state in the 'Name' box (B).
@item
To define a state of type:
@itemize @minus
@item
@strong{Normal State}: continue to next step.
@item
@strong{Event State}: check box 'Is Event' (D).
@item
@strong{Splitter State}: check box 'Is Split' (C).
@item
@strong{Joiner State}: in drop-down box 'Joiner of Splitter' (K), select the name of the Splitter to be joined.
@item
@strong{Terminal State}: check box 'Is Terminal' (E).
@end itemize
@item
If the state is a process/pooling state, meaning that it contains other states, make sure all the "child states" within the process have been created first (repeat from step 2). Next, select a "child state" from the drop-down box (G), and click the up arrow button (I). Repeat for all nested states. Remember, when a child state is a sub-process, all of its children are automatically included.
It is important to note that the order in which the child states of a sub-process are defined determine the sort order by which transitions are displayed to the user. So they should be defined sequentially. Note that once a sub-process has been referenced, it is difficult to make changes in the system since changes in a referenced sub-processes will be blocked by the system.
@noindent
@item
When finished, close the States form to save the states. This will trigger validity checking of the data entered; if no error message is displayed, then the data has been saved to memory. Note that the information is not yet saved to a file.
@end enumerate
@section Removing States from a Process
To remove a state from a process:
@enumerate
@item
In the States form, identify the process that you wish to modify.
@item
Highlight the state you wish to remove in the Included States box (F) of that process.
@item
Click the down arrow (J) to remove the state. Note: the state will not be completely deleted, it will only be deleted from the process.
@end enumerate
@heading To permanently delete a state:
@enumerate
@item
Remove the state from any processes, using steps above. If the state is itself a process, delete all reference to it from studies that use it as a main process. This may require deletion of other entities and may be difficult if the deletion candidate was extensively used.
@item
In the States form, identify the state that you wish to delete, and click the 'X' (delete) button at the left of that row. This may require deletion of other entities and may be difficult if the deletion candidate was extensively used.
@end enumerate
@section State Indicator Parameters
Each State or Process has two state indicators associated with it. These state indicators are parameters that are set/reset during a simulation.
@itemize @bullet
@item
@strong{Actual State Indicator} - Uses the state name with spaces replaced by an underscore '_'. This state indicator will be set to 1 during simulation if the subject is present at this state at this simulation step.
@item
@strong{Entered State Indicator} - Uses the state name with spaces replaced by an underscore '_' followed by the suffix @emph{_Entered}. This state indicator will be set to 1 during simulation if the subject is entered into this state at this simulation step. This state indicator is set to 1 only if the state was entered in this simulation step and will be reset if the individual stays in this state or leaves it.
@end itemize
Sub-Process state indicators will be set to 1 if the user is in any state / sub-process within this sub-process. This means, for example, that the state indicator of the main process of a model used is simulation is always set to 1. States will generally behave the same with the exception of a simulation step where several sub-processes are joined by a joiner state. In this case, the sub-process indicators will be reset, while the state indicators will remain set until the next simulation step. This behavior allows cost calculations in this simulation step according to the states before the collapsing joiner state was reached.
@node Model
@chapter Model
@section Definitions of a Model
@strong{Model:} A specification of the disease progression created by the user within the system. The progression is defined as a set of states and processes, and of transitions between these states. Transitions hold transition probabilities that describe transition from one state to another.
@section Working with Models
@subsection Creating a Model
@enumerate
@item
From the main window, click the 'Models' on the left navigation pane.
@html
<br><br><img src='Images/model.jpg'><br><br>
@end html
@item
This form shows all of the studies and models in the project. To add a new study or model, press the 'Add' button (A), and a new row will appear in the table.
@item
Give the model a name (B).
@item
Click on the @ref{Transitions} button to define transitions related to the Model. Transitions of a model will hold probabilities.
@item
Close the form or move to the next record to save the entry. This will trigger validity checking of the data entered and if no error message is displayed, then the data has been saved to memory. Note that the information is not yet saved to a file.
@end enumerate
@subsection Removing a Model
Open the Model form. Identify the row to be removed, and click the 'X' (delete) button for that row. This may require deletion of other entities and may be difficult if the deletion candidate was extensively used.
@node Transitions
@chapter Transitions
Transitions connect states/processes within a model. Below, they are indicated by solid arrows and indicate the paths that subjects can take through the model and the probabilities to take a path in a certain time step.
@html
<br><br><img src='Images/modeldiagram.jpg'><br><br>
@end html
@section Creating Transitions
@enumerate
@item
From the main window, click 'Transitions' on the left navigation pane. This form can also be reached from a Model form by selecting the transition button for a certain Model.
@html
<br><br><img src='Images/transitionsmodel.jpg'><br><br>
@end html
@item
This form shows the transitions for a given Model. Select the Model to be used from the drop-down box (A). Note: if the Transitions page was opened from the Model page, that Model will be selected and the combo box will be grayed out.
@item
Click the 'Add' button (B).
@item
Select the origin state for the transition (D).
@item
Select the destination state for the transition (E).
@item
Enter the transition probability in the box (F) as an expression, which may or may not include Parameters and State Indicators.
@item
It is recommended you add notes regarding the transition in (J). It is a good idea to write down the source of the information in the notes to improve model traceability.
@item
Close the form to save the entry.
@end enumerate
@section Removing Transitions
Identify the row that will be removed, and click the 'X' button (C) in that row. This may require deletion of other entities and may be difficult if the deletion candidate was extensively used.
@section Copying Transitions from Another Model
It may be desirable to build or modify a model by copying transition information from another model. The systems support this sort of copy using the following steps:
@enumerate
@item
Initiate the transitions copy by pressing the @strong{Copy From Model} button (K). The following form will appear:
@html
<br><br><img src='Images/copytransitions.jpg'><br><br>
@end html
@item
Select the model you wish to copy the transitions from by clicking on it.
@item
Press @strong{OK} to initiate the copy or @strong{Cancel} to abort the copy operation.
@item
If the operation was not aborted, the system will bring a message indicating how many transitions were successfully copied. Dismiss this dialog box by pressing @strong{OK} and the transitions form will display the copied transitions.
@end enumerate
Note that this operation is useful while creating variations of a specific model that change the state/sub-process hierarchy. The copy transitions operation will try to copy all the transitions from the source model to the destination model. However, some transitions may not be copied as these may violate validation rules. Here are examples of transitions that will not be copied:
@itemize @bullet
@item
Transitions that are already defined by states in the destination model will not be copied from the source model.
@item
Transitions where at least one of the states does not exist in the destination Model will not be copied.
@item
Transitions that will violate the sub-process hierarchy will not be copied. For example if the to/from states are not in the same sub-process in the destination model.
@end itemize
@node Populations
@chapter Populations
A population (also referred to as population set or data set) represents a pool of subjects and their characteristics. A populations can be either input as data, or by specifying a distribution (to be used for randomly generating population sets).
@section Creating Populations
@enumerate
@item
From the main form, click the 'Populations' button on the left-hand navigation pane. Note that this form can also be accessed by drilling down from the project form.
@html
<br><br><img src='Images/populations.jpg'><br><br>
@end html
@item
This form shows the population groups. Click the 'Add' button (A), and a new row will appear.
@item
Enter the name for the population set in the box (C). It is also recommended that you enter notes in (F) and a reference to the source of the information in (G) since this improves tractability and improves the modeling work.
@item
Click the 'Data' button (E) to define the population characteristics and associated data/distributions. The following form will appear.
@html
<br><br><img src='Images/popdata.jpg'><br><br>
@end html
@item
To input a population as data: Add a characteristic by selecting a parameter from the table in the lower left (D) and Click the up arrow (C). To remove a row, highlight it in (A), then click the down arrow (B). After all the population characteristics have been added, press the Data Tab (G) and fill in data for the chosen parameters for each individual. The data can also be imported from a file using the Import button - to view or change the imported data, press the data tab (G).
@item
To specify a population by its distribution: Add a characteristic by selecting a parameter from the table in the lower left (D). Additionally, define the distribution expression in the text box (E), or select a predefined expression parameter from the table in the lower right (F) and it will appear in (E). Click the up arrow (B) to add a row that combines the distribution and the parameter. To remove a row from (A) highlight it, then click the down arrow (C).
@item
To specify objectives for a distribution based population: press the Objectives tab (G) and the display will change to the image below. The Objectives will be listed as rows in the list (P). To Add an objective to the list fill in the Filter Expression (K) and Statistics Expression (L), select a Function to apply on the statistics expression (M), define the Target Value (N) and define the Weight of the objective (O), then click the up arrow (I) to add the new objective to the objective list (P). To remove an objective from the list, select it in the list (P) and then click the down arrow (J).
@html
<br><br><img src='Images/popobjectives.jpg'><br><br>
@end html
@end enumerate
@section Removing an Entire Population
Identify the population, and click the 'X' (delete) button. This may require deletion of other entities and may be difficult if the deletion candidate was extensively used.
@section Generating new population data based on distributions
The system supports the automatic generation of a population set defined by distributions of its characteristics. This feature can be used to automatically generate population sets in the system according to distributions provided in the literature. To perform these tasks, the following steps should be taken:
@enumerate
@item
Follow the steps defined above in @strong{Creating Populations} to define a population set defined by distributions that were defined in the previous step.
@item
Select the desired distribution based population. The population set should read "Distribution based" in the Definition Type field (D).
@item
Right click the mouse and a pop up menu will appear. Select the entry "Regenerate New Population Data from a Distribution".
@item
A new input dialog window will appear and will ask for the population size to be generated. Enter the desired number and press OK.
@item
The system will generate a new population set filled with data that was generated according to the distributions defined in the originally selected distribution population set. The system will place this population set at the end of the list and will focus on it so the user can modify it.
@end enumerate
Note that generation of a data based population from distributions is controlled by multiple system option parameters that are listed in @ref{Parameters}.
Also note that during generation of a population from distributions it is possible to have interdependent parameters that influence each other. For example, Blood Pressure may be a function of Age and Weight can be a function of Age and Height. The system will resolve these interdependencies upon generation as long as there are no circular conflicts such as A depends of B that depends back on A. Also note that parameter bounds are enforced during population generation and may skew a distribution. Using Objectives may correct this phenomenon.
Data populations generated from distributions with objectives will show fitness to objectives in the objectives tab just after creation. Yet this information will not be retained after modification.
@node Parameters
@chapter Parameters
Parameters are used for various purposes by the system: Parameters that will change during simulation or define a demographic characteristic of a subject, they also can be defined by a user-specified expression/function and then used in subsequent functions as a symbol/shorthand for the user specified function; i.e., they may replace complex mathematical expressions or random generators in multiple functions.
@section Parameter Types
The following parameter types can be defined by the system.
@itemize @bullet
@item
@strong{Number} - accepts any floating point number such as 1.23345 or -0.123 or 1.2e3, subject to specified limits.
@item
@strong{Integer} - accepts integers, such as 1,2,3, the system will raise an error if a non integer is assigned to the parameter during simulation, subject to specified limits.
@item
@strong{Expression} - gives a name for an expression/function that can be used later during calculations. Each time the function name is used, it will be replaced by the expression that it represents. For example, a function that increases age may be called AgeIncrease and hold the function Age+1. When a function parameter is encountered in an expression, it is replaced by its contents during evaluation. Note that if this function includes a random number generator, a different value of the generator will be used each time the expression/function is invoked. Consider for example a parameter called CappedGaussian that generates random numbers using a Gaussian distribution with mean=0 and STD =1 that is restricted to the range from -3 to +3. This can be done by the user using the formula Min(Max(Gaussian(0,1),-3),3) to define this function type parameter. After definition in the parameter form, CappedGaussian can be used in any expression in the system during simulation or population generation from distributions. Whenever this parameter is encountered during simulation, a new random number will be generated on the fly; that is, reusing CappedGaussian will generate a new random number rather than return the same value. This is different than most other parameter types that generally hold values that are assigned to them. Note that bounds can still be defined to an expression parameter.
@item
@strong{System Options} - These names are set by the system by default; their values can be modified by the user to change functionality of the system. Here is a short description of these parameters by categories of influence:
@itemize @bullet
@item
@code{ValidateDataInRuntime}: A number that defines the level of validity checking of expressions during simulation and population generation from distributions. The following levels are supported:
@itemize @bullet
@item
0: No validity checking.
@item
1 or greater: Check that probabilities are within 0 and 1 and check that these sum to 1 when leaving event states and joiner states, and check that a value assigned to a parameter fits the validation rules defined for it.
@item
2 or greater: Check that function parameter validity rules are honored during calculation of expressions - this is the default option.
@item
3 or greater: Impose extra redundant validation checks on all phases of calculation.
@end itemize
@item
@code{NumberOfErrorsConsideredAsWarningsForSimulation}: The number of times the system will accept parameter validity violation errors during simulation as warnings and will not stop simulation. When this number of errors is reached, the system will raise a fatal error to the user and stop simulation. The error messages can be seen on the console window.
@item
@code{NumberOfTriesToRecalculateSimulationStep}: The number of times that the system will force recalculation of the same time step if an error was raised during this time step. If unsuccessful after this number of recalculations then force recalculation of the entire individual from the first time step.
@item
@code{NumberOfTriesToRecalculateSimulationOfIndividualFromStart}: The number of times an individual will be recalculated from start in case errors appeared during simulation that forced restarting calculations. If this number of tries is reached, a fatal error is raised that stops simulation.
@item
@code{SystemPrecisionForProbabilityBoundCheck}: This is a very small tolerance number that defines how accurate will be fatal error checks for probabilities if ValidateDataInRuntime>=1. This number allows overlooking machine precision issues.
@item
@code{RepairPopulation}: This integer defines the level the system will try to correct a population set to fit a model before simulation. The following levels are supported:
@itemize @bullet
@item
0: No repairs are made and errors are generated. This forces the user to match population set parameters and model parameters very carefully, including process names.
@item
1 or Greater: The system will attempt to figure out values for process state indicators and other states in the process according to the model structure and according to state indicator values defined in the population set.
@item
10 or Greater: The system will remove individuals with empty values in the population data before simulation, and therefore avoid generating an error that will stop the simulation process.
@end itemize
@item
@code{VerboseLevel}: Defines how much information to output during simulation.
@itemize @bullet
@item
Here are supported levels for output from population generation from distributions:
@itemize @bullet
@item
3 or greater: Record random seed number on file that will be created at the start of population generation from distributions.
@item
7 or greater: Record generated population set on file. This would be a pickled python list object.
@item
10 or greater: Print an announcement each time a new individual starts generation. Also print a generation summary at the end of of population generation from distributions.
@end itemize
@end itemize
@item
Here are supported levels for output from bridging population set and model definitions before simulation:
@itemize @bullet
@item
1 or greater: Print summary of the bridge process.
@item
5 or greater: Print a message if deleting a record due to a missing value.
@item
10 or greater: Show each process set by the system due to a child state.
@end itemize
@item
Here are supported levels for output from simulation:
@itemize @bullet
@item
3 or greater: Record random seed number on file that will be created at the start of simulation.
@item
7 or greater: Record simulation results set on file.
@item
10 or greater: Print an announcement each time a new individual starts simulation. Also print a simulation summary at the end of simulation.
@item
20 or greater: Print an announcement each time an individual starts a new repetition during simulation. Also print a message if recalculation of a repetition was forced due to error.
@item
30 or greater: Print an announcement each time step during simulation. Also print a message if recalculation of a time step was forced due to error.
@item
40 or greater: Print an announcement for each state in the State Processing Queue (SPQ). This is highly advanced and requires deep understanding of the system.
@end itemize
@item
@code{RandomSeed}: Defines a random seed to start both population generation and simulation. NaN is used to indicate that system time will be used as a random seed - essentially making numbers different each simulation.
@item
@code{NumberOfErrorsConsideredAsWarningsForPopulationGeneration}: The number of times the system will accept boundary violation errors as warnings and will not stop during population generation from distributions. When this number or errors is reached, the system will raise a fatal error to the user. Error messages can be found on the console window.
@item
@code{NumberOfTriesToRecalculateIndividualDuringPopulationGeneration}: The number of time the system will try to recalculate the same individual if a non fatal error is encountered during calculation of that individual. Once this number is reached a fatal error will be raised and generation of data from distributions will stop.
@item
@code{GeneticAlgorithmCandidatesPerSelectedIndividual}: Defines the number of candidates to generate for each individual if objectives are defined. If this number is X and an a population of size 100 is requested then the initial pool of candidates will be 100*X from which the genetic algorithm will select the 100 best individuals that fit the objectives.
@item
@code{GeneticAlgorithmSolutionPopulationSize}: The number of candidate solutions in each generation. A solution is a selection of individuals from the candidate pool group.
@item
@code{GeneticAlgorithmMutationRate}: The probability of an individual to change to another candidate in any given solution.
@item
@code{GeneticAlgorithmMaxEvalsTerminator}: A stop criteria for the genetic algorithm defined by the maximal number of evaluations of candidate solutions. This stop criteria is similar to limiting the overall number of objective computations.
@item
@code{GeneticAlgorithmMaxStableGenerationCountTerminator}: A stop criteria for the genetic algorithm defining the number of consecutive generations that the best solution does not change before stopping. Using a higher number here and in @code{GeneticAlgorithmMaxEvalsTerminator} improves the probability of reaching an optimal solution - yet this will take much more time. Note that stop criteria compete.
@item
@code{GeneticAlgorithmTournamentSize}: The number of tournaments used to define the population of the next generation. For additional information see:
@html
<a href='http://inspyred.github.io/reference.html#selectors-parent-selection-methods' target="_blank"> http://inspyred.github.io/reference.html#selectors-parent-selection-methods</a>
@end html
@item
@code{GeneticAlgorithmNumberOfElitesToSurviveIfBetterThanWorstOffspring}: The number of solutions from previous generation to be kept in the next generation if better than offspring. If this number is at least 1 then it is guaranteed that the best solution in each generation is at least as good as the previous generation. For additional information see:
@html
<a href='http://inspyred.github.io/reference.html#replacers-survivor-replacement-methods' target="_blank"> http://inspyred.github.io/reference.html#replacers-survivor-replacement-methods</a>
@end html
@end itemize
@item
@strong{State Indicator} - These cannot be changed by the user, but can be used in expressions and other system functions. For each state created in the system, there will be two State Indicator parameters associated with it - the actual state and the entered state indicator - see @ref{States}. The validation rule for this type of parameter is Integer [0,1].
@end itemize
When defining a parameter the user can define additional validation rule parameters of the type [min, max] that will define bounds for this parameter. For example a user who wishes to define a Boolean parameter, should define an integer with the validation rule parameters of [0,1]. Another example is a user who wishes to define a positive integer should define a parameter of the type integer with the validation rule parameter of [0,Inf]. By default and unless specifically requested otherwise by the user by changing the appropriate system options, validation rule parameters are checked during simulation at each step to verify values are within the allowed ranges.
@section Working with Parameters
@subheading Creating Parameters
@enumerate
@item
From the main form, click the 'Parameters' button on the left-hand navigation panel. The following form will appear:
@html
<br><br><img src='Images/parameter_filter.jpg'><br><br>
@end html