Jump to: navigation, search

Difference between revisions of "Creating a STEM Scenario"

Line 1: Line 1:
[[Image:STEM TOP BAR.gif|800px]]
+
[[Image:STEM TOP BAR.gif|800px]]  
 +
 
 
{| align="right"
 
{| align="right"
  | __TOC__
+
|-
  |}
+
| __TOC__
 
+
|}
'''[http://wiki.eclipse.org/Tutorials_for_Developers Back]'''
+
 
+
'''Creating a STEM Scenario'''
+
 
+
=Create the Project=
+
 
+
1) Click on the Icon with many little squares (or new->STEM Project) and create new STEM project (ExperimentalDisease). See Figure 1.
+
 
+
[[Image:Newproject.jpg|600px]]
+
 
+
''Figure 1: Creating a New STEM Project ("ExperimentalDisease")''.
+
 
+
 
+
[[Image:ProjectDialog.jpg|400px]]
+
 
+
''Figure 2: The New Project Dialog''
+
 
+
2) Open the new project – you should see several folders including: decorators, graphs, etc.
+
 
+
=Create a New Model=
+
 
+
1) Click on blue triangle (or New->Model) to create new model (for example: Cuba)
+
 
+
2) Fill in any Dublin core data you want to add
+
 
+
=Add a Disease to the Model=
+
 
+
1) Click on the New Disease icon (black square with the health symbol) or on the menu bar click ->new>new disease
+
 
+
2) This will launch the Dialog shown in Figure 3. Fill in the Name: (ExperimentalDisease)
+
 
+
3) Fill in the Disease Name: You can use the same name you used above (ExperimentalDisease)
+
 
+
4) Select the DiseaseModel in the ComboBox: e.g., select your Disease model. For our case we will use "DeterministicSIDiseaseModel". For a description of the various disease models available, see [[Introduction_to_Compartment_Models#Built-in_compartment_models_in_STEM|Built-in STEM Compartment Models]]
+
 
+
Also select the Solver algorithm you want to use. The Finite Difference method is a simple algorithm that is useful to quickly run a simulation and verify that everything looks right. However, for real scenarios where data is being collected for analysis, we recommend using the Runge Kutta Adaptive Step Size method because this algorithm is much more accurate. If you use the Runge Kutta method, you also need to specify a "Relative Tolerance" factor in the disease model parameters. The smaller this number the more accurate the calculations will be, but the simulation will also run slower. The default is 0.05 (or 5%), which we recommend lowering if possible to 0.01 or even 0.001. It all depends how much time you can spare running a scenario.
+
 
+
At this point you can also edit or set any of the disease parameters (i.e. Transmission Rate, Recovery Rate, etc).
+
If you don't want to do it now, it will also be editable any time after the scenario is created.
+
 
+
[[Image:DiseaseDialog.jpg]]
+
 
+
''Figure 3: The New Disease Dialog''
+
 
+
5) Fill in any Dublin core data you want to add
+
 
+
6) Click finish
+
 
+
7) Under decorators you should see ExperimentalDisease.standard
+
 
+
8) Double click on MODELS in the project explorer. You should see "Cuba" in the Resource Set
+
 
+
9) DRAG your new disease (e.g., ExperimentalDisease.Standard) from decorators (in the project explorer window) into the model "Cuba" in the Resource Set window. Expand the "Cuba" Model in the Resource Set window to see that it worked. See Figure 4
+
 
+
 
+
[[Image:Dragdiseasetomodel.jpg|400px]]
+
 
+
''Figure 4. Drag the Disease Model (decorator) into the Model in the Resource Set.''
+
 
+
=Add a Population Model=
+
 
+
 
+
Population Models in STEM are used to control how a population changes over time regardless of the diseases circulating within the population.
+
 
+
1) Create a new population model either by selecting the “Define a new Population Model” icon in the toolbar (resembling a person, see Figure 1) or selecting New -> Population Model from the menu.
+
 
+
[[Image:PopulationModelToolbar.jpg]]
+
 
+
''Figure 5. Opening up the wizard used to create a new population model''
+
  
A wizard opens up (see Figure 2). STEM currently comes with two types of Population Model, a StandardPopulationModelImpl and a StochasticStandardPopulationModelImpl. Both are very similar except that the stochastic variant allows you to add noise to your model.
+
'''[http://wiki.eclipse.org/Tutorials_for_Developers Back]'''
  
2) Specify a name, the background Birth Rate and a Background Mortality rate for your population. The wizard also allows you to change the name of the population from the default ‘human’ to any other population identifier your model requires (e.g. “mosquitoes”). The background birth and death rate are in relationship to a time period that can also be changed. By default, it’s set to 1 day (or 86400000 ms).
+
'''Creating a STEM Scenario'''
  
As an example if you assume a person lives on average 72 years, the death rate can be set to 1/(72*365.25) = 3.8E-5. Assuming a couple on average gives birth to 2.5 kids in their lifetime, the birthrate would be 3.8E-5 * 2.5 / 2.0 = 4.7E-5.
+
= Create the Project  =
  
Observe that the background birth rate/death rate currently applies to all regions in your model.
+
To create a new STEM project, click on the ‘new project’ icon in the command bar, or from the “New”-menu use the “New -> scenario” command.  
  
3) When the population model has been created, you can drag it into your model just like you do with disease models. The population model ends up under the Decorator folder in the project explorer.  
+
<br> [[Image:Newproject.jpg|600px]]
  
If no population model is specified in your scenario, the background birth and death rate is assumed to be 0.
+
''Figure 1: Creating a New STEM Project ("ExperimentalDisease")''.  
  
Before starting a simulation, STEM will retrieve the population model(s) and the sequencer and using the start date of the sequencer it adjust the population values to match the expected value at the beginning of the simulation. This can either be a date in the past or the future in relationship to the year the population data was valid.
+
<br>
+
  
[[Image:NewPopulationModel.jpg]]
+
<br> [[Image:StemTut2.png]]  
''Figure 6. Wizard used to define a new Population Model''
+
  
<br>
+
''Figure 2: Project Explorer'' <br> The ‘Project’ structure thus created under the name ‘ExperimentalDisease’ contains headings for all the components that are necessary to compose a runnable scenario, including a substructure for the scenario definitions themselves.
  
=Add the Geographical Data to the Model=
+
<br><br>
  
1) To add the geography data for Cuba to the Model, at the bottom panel under the  Models tab, click on >STEM>Geography>Political>Country>CUB>CUB (0) full infrastructure
+
= Create a Scenario  =
The models tab is shown selected in the bottom of Figure 1 above. It is also identified by a blue triangle.
+
  
2) Drag this up to the Model "CubaExperimentalDisease" in the Resource set window
+
The ‚Scenario’ is the basic executable unit that can be run as an experiment. A scenario requires a number of mandatory components to be executable, while some other control elements are optional and can add extended functionality to a given basic scenario. Under the menu item “New -&gt; scenario”, you can create a new scenario entry for the scenarios section of your new project.
+
''save your work at this point by hitting <ctrl>S''
+
  
=Alternatively, Add a Custom Graph=
+
<br> [[Image:StemTut3.png]]
  
 +
''Figure 3: Scenario Creation'' <br> Upon creation of the scenario, you also select the Solver algorithm you want to use.<br> The Finite Difference method is a simple algorithm that is useful to quickly run a simulation and verify that everything looks right. <br> However, for real scenarios where data is being collected for analysis, we recommend using the Runge Kutta Adaptive Step Size method because this algorithm is much more accurate.<br> If you use the Runge Kutta method, you also need to specify a "Relative Tolerance" factor in the disease model parameters. <br> The smaller this number the more accurate the calculations will be, but the simulation will also run slower. The default is 0.05 (or 5%), which we recommend lowering if possible to 0.01 or even 0.001. <br>It all depends how much time you can spare running a scenario.
  
At times it is interesting to study the propagation of a disease model on a simple lattice instead of the more complex geograhical administrative divisions. STEM now supports user creation of custom lattices via the New Graph wizard, shown in the Figure below. The wizard makes use of "Graph Generators," a new concept. A graph generator is a pluggable component that is able to generate a graph (a collection of nodes and edges) either algorithmically or from an external file. Currently, we have implemented an abstract Lattice Graph Generator with a Square Lattice Implementation. To create a custom square lattice or other custom graph please read the documentation on [[Creating a new Graph | '''Creating a new Graph''']]
+
<br>
  
=Create a Scenario and Add Your Model to It=
+
<br>
  
1) Click on the purple diamond icon to create new scenario
+
[[Image:StemTut4.png]]
  
2) Give it a name (you might want more than one so index it, for example, as "ExperimentalDisease1")
+
''Figure 4: Project Explorer''
  
3) Fill in any Dublin core data you want to add
+
<br> To be made executable, the blank scenario further requires a sequencer, an infector and a nested model structure.
  
4) Click finish
+
<br>
  
5) From the Project Explorer window, under Models, drag the new model ("CubaExperimentalDisease.model") into the new Scenario in the Resource Set. Expand the scenario so you can see that it worked.
+
= Add model containers for the model hierarchy  =
  
=Add a Sequencer to the Scenario=
+
By clicking “New -&gt; model”, you can create an empty model container. <br> Because we will need three different models in a nested structure, we need to create three model containers, named ‘geo’, ‘pop’ and ‘dis’ for this example.
  
1) Go to Sequencers on the bottom window - expand fully
+
<br>
  
2) Drag Sequential Sequencer 2006 into the Scenario in the Resource Set.  
+
[[Image:StemTut5.png]]
Make sure you have a properties Editor Window open
+
  
3) Click on >Window>other>General>Properties to open the properties view.
+
''Figure 5: Model Creation''
Open the Disease in the Properties Editor – get ready to Create an Infector
+
  
4) To create an infector you first need to make sure you know the exact ‘Disease Name’ used in step 2 above. To be sure check it as follows. In the Project Explorer, Under Decorators, double click on ExperimentalDisease.standard
+
<br>
The new disease will be visible in the resource set. Expand the file node an you should see “ExperimentalDisease model human”. Click on “ExperimentalDisease Disease model human”. In the bottom window click on the properties tab to show the disease in the properties editor view.
+
  
 +
= Import graphs from the STEM framework  =
  
[[Image:PropEditor.jpg|600px]]
+
The geographical data and the population data can be imported as graphs from the STEM framework by pulling the graphs from the STEM resources section on the right into the graphs section on the left of the project, in this case using country-specific data for Germany.  
  
''Figure 9: In the Resource Set the new Scenario is expanded showing that it now contains a model which contains a disease (decorator). The disease contains a Dublin Core. Double Clicking on the Disease in the Resource Set opens an editor at the bottom of the screen. Click on the Properties Tab (shown selected) to see the Properties Editor.
+
<br>
Here you can also change any of the disease parameters at any time.''
+
  
5) This is the view where you can see, edit, and change any disease parameter. Find and confirm the disease name ("ExperimentalDisease" in this case).
+
[[Image:StemTut6.png]]
  
=Create a Custom Sequencer=
+
''Figure 6: Graph Import ''
  
Every scenario must also include a "sequencer" which basically is a clock that
+
<br> <br> <br>
regulates time, and an "infector" which sets the initial infectious population. Stem has a build in default
+
sequencer called the "Sequential Sequencer" but you will no doubt want to create your own to specify
+
start time, step size, end time, etc.
+
  
1) To create a new sequencer click on the New Sequencer Icon which appears as a little clock.
+
= Create the geography model  =
Alternatively, on the menu bar you can select >NEW>SEQUENCER
+
  
[[Image:Sequencer3.jpg|200pm]]
+
The bottom model in the model hierarchy is the geographic model. <br> This needs to be filled with the ‘area’ graph, the ‘nodes’ graph, and the ‘Common Border relationship within country DEU’ graph. <br> This is done by opening the ‘geo.model’ in the Designer view (simply by double-clicking it in the Project Explorer), <br> and dragging the graphs into the geo.model. Saving your geo.model at this stage is probably a good idea, and can be done by hitting &lt;ctrl S&gt; in the Designer view of the model.  
  
''Figure 10: The new Sequencer Icon''
+
<br>
  
 +
[[Image:StemTut7.png]]
  
The "New Sequential Sequencer" Dialog will open as shown in Figure 7 below.
+
''Figure 7: Equipping Models '' <br> <br> <br>
2) Specify in which Project to put the Sequencer (it will always go in your Sequencers folder).
+
Give it a name, and select the cycle period and unit. At this point in time STEM only supports
+
constant time steps. In the future new Sequencers will be created that allow variable time steps.
+
  
3) Select the starting date.
+
= Create the population model  =
  
4) If you wish to specify an End Date be sure to check the "Specify End Date" checkbox.
+
The population model contains the geography model plus the population graph. It can be created by opening the pop.model in the Designer Perspective, and dragging the geo.model from the project view into the pop.model in the Designer. Add the population graph to this, and the basic population model is ready. There also exists the possibility of creating more elaborate population models (e.g. multiple populations etc.), but if further specifications are not present, an automatically generated population model will be used, that basically is just a wrapper around the population data contained in the imported graph. <br> [[Image:StemTut8.png]] <br> ''Figure 8: Population Model '' <br> <br> <br>
This check box MUST be set for the end date to be editable later.
+
  
You will then be allowed to set the End Date in the second calendar.
+
= Create the disease model  =
  
[[Image:Sequencer1.jpg|300pm]]
+
To compose the disease model, we finally also need a disease. The disease construction is accessible via the “New -&gt; disease” command. For the sake of creating an example disease, take note that the transmisson rate is set to a value larger than zero, and also note that the name of this disease will be required to initialize the infector later on in the scenario construction. The newly defined disease appears in the ‘Decorators’ section of the Project Explorer, and this is also where the infector will appear when it is created. For this demonstration, choose e.g. DeterministicSEIRDiseaseModelImpl. with a Transmission Rate of 1.0, an Infectious Recovery rate of 0.5, Immunity Loss Rate of 0.3, and an Incubation Rate of 0.3
  
''Figure 11: The New Sequential Sequencer Dialog helps you configure a Sequencer.''
+
<br> [[Image:StemTut9.png]] <br> ''Figure 9: Disease Creation '' <br> <br> After creating a disease, you will be able to inspect the properties of the disease in the ‘Properties’ tab of the Resources section of the Designer View. Make sure that all parameters have been entered correctly, e.g. that you have a Transmission Rate larger Zero. You can change the values of properties in this tab by simply editing them, and saving them by hitting &lt;ctrl-S&gt; in the Designer View again.  
  
 +
<br> <br> [[Image:StemTut10.png]] <br> ''Figure 10: Disease Model '' <br> <br> <br>
  
5) Once you have created your sequencer it must be dragged into your scenario folder. Follow the same instructions
+
To create the disease model, proceed just as before by pulling the pop.model and the disease from the Project Explorer onto the empty dis.model in the Designer View, and save the disease model with &lt;ctrl-S&gt; to update the project.  
under "Creating a Scenario". The sequencer can be edited after creation by opening the scenario, selecting the
+
sequencer, and double clicking to open it in the "property editor" at the bottom of the screen (See Figure 8).
+
  
[[Image:Sequencer2.jpg|400pm]]
+
<br>
  
''Figure 12: Changing the sequencer in the property editor after it has been added to a scenario.''
+
= Create an Infector  =
  
= Create and Add an Infector or Inoculator  =
+
The command “New -&gt; infector” allows you to create an infector. An essential information for the infector is the disease to be linked to this infector, thus ‘Disease Name’ must correctly spell out the name of the disease defined earlier. Furthermore, the geographical location must be specified (under the ‘Select Location’ button), in this case Hamburg as one of the 41 nodes in the geographic model for Germany.
  
There are now several new options available when a new infector or inoculator is created. First, you can create mnually create an infector or inoculator to place a specific number (or percentage) of infectious or recovered people at any geospatial location known to STEM. For example, for the Cuba Scenario:  
+
<br> [[Image:StemTut11.png]] <br> ''Figure 11: Infector Creation '' <br> <br>
  
1) Click on the new infector icon (black square with the health symbol and the letter I)
+
<br> <br> [[Image:StemTut12.png]] <br> ''Figure 12 ISO Key selection for Infector '' <br> <br>
  
2) Name it (e.g., "CubaInfector"), under DiseaseName: "ExperimentalDisease"
+
<br>
  
3) Under country select Cuba
+
= Create a Sequencer  =
  
4) Click on the Scenario to open it in the Resource set
+
Any scenario will also need a sequencer to be runnable. Under “New-&gt;Sequential Sequencer” you can create a sequencer, that specifies the temporal increments upon which the evolution of your scenario will be based. For the sake of brevity, the screenshot is omitted here. <br>
  
5) Drag the CubaInfector from Decorators into the scenario (open it to see it)
+
<br>
  
6) In the resource set click on the infector SI Infector ExperimentalDisease to edit it. Your disease model may be SI, SIR, SIER, etc but in all cases you only need an SI infector (as this base class will add infectious people to seed any model).
+
= Equip the Scenario  =
  
7) Save your work at this point by hitting &lt;ctrl&gt;S
+
With a sequencer, an infector, and a nested model hierarchy at our disposal, we can now proceed to equip the scenario. This is done again by simply dragging the components from the Project Explorer onto the scenario heading in the Designer View. The asterisk preceding the scenario name in the tab header of the Designer View indicates unsaved work. Saving the scenario will update the scenario hierarchy in the Project Explorer. <br>
  
8) Click on the scenario, right click and run<br>
+
[[Image:Stem scen tut13.png]] <br> ''Figure 13: Scenario Completion '' <br> <br>  
  
When infecting or inoculation locations on a custom graph or lattice, there is also a radio button that allows you to '''Select Within Project'''. Instead of choosing from STEM's built in location ISO keys, this option presents the user only with those keys that already exist within the graph(s) contained in the users project. In the example below, the nodes on a small square lattice are shown.
+
<br>
  
Finally it is also possible to create an infector or inoculator by importing data from external files in the form of the comma separated files used by the STEM logger. A collection of infectors/inoculators can either be created from the first, last or any manually specified row from such files. We have found this feature extremely valuable when "boot-strapping" the initial state of a disease from a steady state (e.g., the seasonal flu state of the population in the summer time for northern hemisphere).
+
= Run the Scenario  =
  
[[Image:NewInfector.jpg|400pm]]
+
Right-clicking on the scenario heading and selecting the green triangle icon for “run”, you can now run the scenario and observe the progression of the disease given the selected parameters.  
  
''Figure 13. The New Infector Wizard''
+
<br> <br>

Revision as of 10:35, 7 February 2011

STEM TOP BAR.gif

Back

Creating a STEM Scenario

Create the Project

To create a new STEM project, click on the ‘new project’ icon in the command bar, or from the “New”-menu use the “New -> scenario” command.


Newproject.jpg

Figure 1: Creating a New STEM Project ("ExperimentalDisease").



StemTut2.png

Figure 2: Project Explorer
The ‘Project’ structure thus created under the name ‘ExperimentalDisease’ contains headings for all the components that are necessary to compose a runnable scenario, including a substructure for the scenario definitions themselves.



Create a Scenario

The ‚Scenario’ is the basic executable unit that can be run as an experiment. A scenario requires a number of mandatory components to be executable, while some other control elements are optional and can add extended functionality to a given basic scenario. Under the menu item “New -> scenario”, you can create a new scenario entry for the scenarios section of your new project.


StemTut3.png

Figure 3: Scenario Creation
Upon creation of the scenario, you also select the Solver algorithm you want to use.
The Finite Difference method is a simple algorithm that is useful to quickly run a simulation and verify that everything looks right.
However, for real scenarios where data is being collected for analysis, we recommend using the Runge Kutta Adaptive Step Size method because this algorithm is much more accurate.
If you use the Runge Kutta method, you also need to specify a "Relative Tolerance" factor in the disease model parameters.
The smaller this number the more accurate the calculations will be, but the simulation will also run slower. The default is 0.05 (or 5%), which we recommend lowering if possible to 0.01 or even 0.001.
It all depends how much time you can spare running a scenario.



StemTut4.png

Figure 4: Project Explorer


To be made executable, the blank scenario further requires a sequencer, an infector and a nested model structure.


Add model containers for the model hierarchy

By clicking “New -> model”, you can create an empty model container.
Because we will need three different models in a nested structure, we need to create three model containers, named ‘geo’, ‘pop’ and ‘dis’ for this example.


StemTut5.png

Figure 5: Model Creation


Import graphs from the STEM framework

The geographical data and the population data can be imported as graphs from the STEM framework by pulling the graphs from the STEM resources section on the right into the graphs section on the left of the project, in this case using country-specific data for Germany.


StemTut6.png

Figure 6: Graph Import




Create the geography model

The bottom model in the model hierarchy is the geographic model.
This needs to be filled with the ‘area’ graph, the ‘nodes’ graph, and the ‘Common Border relationship within country DEU’ graph.
This is done by opening the ‘geo.model’ in the Designer view (simply by double-clicking it in the Project Explorer),
and dragging the graphs into the geo.model. Saving your geo.model at this stage is probably a good idea, and can be done by hitting <ctrl S> in the Designer view of the model.


StemTut7.png

Figure 7: Equipping Models


Create the population model

The population model contains the geography model plus the population graph. It can be created by opening the pop.model in the Designer Perspective, and dragging the geo.model from the project view into the pop.model in the Designer. Add the population graph to this, and the basic population model is ready. There also exists the possibility of creating more elaborate population models (e.g. multiple populations etc.), but if further specifications are not present, an automatically generated population model will be used, that basically is just a wrapper around the population data contained in the imported graph.
StemTut8.png
Figure 8: Population Model


Create the disease model

To compose the disease model, we finally also need a disease. The disease construction is accessible via the “New -> disease” command. For the sake of creating an example disease, take note that the transmisson rate is set to a value larger than zero, and also note that the name of this disease will be required to initialize the infector later on in the scenario construction. The newly defined disease appears in the ‘Decorators’ section of the Project Explorer, and this is also where the infector will appear when it is created. For this demonstration, choose e.g. DeterministicSEIRDiseaseModelImpl. with a Transmission Rate of 1.0, an Infectious Recovery rate of 0.5, Immunity Loss Rate of 0.3, and an Incubation Rate of 0.3


StemTut9.png
Figure 9: Disease Creation

After creating a disease, you will be able to inspect the properties of the disease in the ‘Properties’ tab of the Resources section of the Designer View. Make sure that all parameters have been entered correctly, e.g. that you have a Transmission Rate larger Zero. You can change the values of properties in this tab by simply editing them, and saving them by hitting <ctrl-S> in the Designer View again.



StemTut10.png
Figure 10: Disease Model


To create the disease model, proceed just as before by pulling the pop.model and the disease from the Project Explorer onto the empty dis.model in the Designer View, and save the disease model with <ctrl-S> to update the project.


Create an Infector

The command “New -> infector” allows you to create an infector. An essential information for the infector is the disease to be linked to this infector, thus ‘Disease Name’ must correctly spell out the name of the disease defined earlier. Furthermore, the geographical location must be specified (under the ‘Select Location’ button), in this case Hamburg as one of the 41 nodes in the geographic model for Germany.


StemTut11.png
Figure 11: Infector Creation



StemTut12.png
Figure 12 ISO Key selection for Infector


Create a Sequencer

Any scenario will also need a sequencer to be runnable. Under “New->Sequential Sequencer” you can create a sequencer, that specifies the temporal increments upon which the evolution of your scenario will be based. For the sake of brevity, the screenshot is omitted here.


Equip the Scenario

With a sequencer, an infector, and a nested model hierarchy at our disposal, we can now proceed to equip the scenario. This is done again by simply dragging the components from the Project Explorer onto the scenario heading in the Designer View. The asterisk preceding the scenario name in the tab header of the Designer View indicates unsaved work. Saving the scenario will update the scenario hierarchy in the Project Explorer.

Stem scen tut13.png
Figure 13: Scenario Completion


Run the Scenario

Right-clicking on the scenario heading and selecting the green triangle icon for “run”, you can now run the scenario and observe the progression of the disease given the selected parameters.