Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Creating a STEM Scenario"

(Creating the Project)
(Create a Solver)
 
(139 intermediate revisions by 6 users not shown)
Line 1: Line 1:
'''[http://wiki.eclipse.org/Tutorials_for_Developers Back]'''
+
[[Image:STEM TOP BAR.gif|800px]]  
  
'''Note:''' Instructions below assume you have already created a new disease model of your own and already plugged it into the system. We will soon add directions for creating disease models.
+
{| align="right"
+
|-
To add your plugin to the STEM application, in the Eclipse IDE, go to '''Run->Run Dialog..->Plugins''' and make sure your  user defined plug-ins for the user disease model is checked. For full instructions on creating your own disease model please see [[Creating a new Disease Model Plug-in]]
+
| __TOC__
 +
|}
  
''Substitute YOUR_MODEL_NAME and YOUR_SCENARIO_NAME as appropriate. In this example, Project names and other NAMES are for a hypothetical user defined model based on percolation. Substitute your own name for the disease, model, and scenario accordingly. In this example, to make the documentation readable we will use for the scenario
+
'''[http://wiki.eclipse.org/Tutorials_for_Developers Back]'''  
YOUR_SCENARIO_NAME="Cuba". For the disease model we will use  YOUR_MODEL_NAME="ExperimentalDisease";''
+
  
 +
'''Creating a STEM Scenario'''
  
=Creating the Project=
+
= 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.
+
To create a new STEM project, click on the ‘new project’ icon in the command bar, or from the “New”-menu use the “New -> STEM Project” command.  
  
[[Image:Newproject.jpg|600px]]
+
<br> [[Image:Newproject.jpg|600px]]  
  
''Figure 1: Creating a New STEM Project ("ExperimentalDisease")''.
+
''Figure 1: Creating a New STEM Project ("ExperimentalDisease")''.  
  
 +
<br>
  
[[Image:ProjectDialog.jpg|400px]]
+
<br> [[Image:StemTut2.png]]  
  
''Figure 2: The New Project Dialog''
+
''Figure 2: Project Explorer'' <br> Give your project a new name, e.g. 'ExperimentalDisease'. The structure created under the new project contains headings for various components, including a substructure for the scenario definitions themselves.
  
2) Open the new project – you should see several folders including: decorators, graphs, etc.
+
<br><br>
  
=Creating a New Model=  
+
= Create a Scenario  =
  
3) Click on blue triangle (or New->Model) to create new model (for example: Cuba)
+
The Scenario is the basic executable unit in STEM. 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.
  
4) Fill in any Dublin core data you want to add
+
<br> [[Image:StemTut3.png]]
  
=Adding a Disease to the Model=
+
''Figure 3: Scenario Creation''
  
5) Click on the New Disease icon (black square with the health symbol) or on the menu bar click ->new>new disease
+
Starting with Version 2.0 of STEM (October 2013), it is no longer necessary to pick the "Solver algorithm" you want to use. Solvers are now first class objects in STEM so you can easily change your choice of solver without changing your scenario. See the section ''Create a Solver'' below.
  
6) This will launch the Dialog shown in Figure 3. Fill in the Name: (ExperimentalDisease)
+
= Create a Solver  =
  
7) Fill in the Disease Name: You can use the same name you used in (6) (ExperimentalDisease)
+
With STEM V2.0 and later you can create any one of several different "Solver" objects to solve (integrate) the differential equations in your model or models. Choices include:
  
8) Select the DiseaseModel in the ComboBox: e.g., select your Disease model. For our case we will use "DeterministicSIDiseaseModel"
+
* Finite Difference
 +
* Runge Kutta
 +
* [https://commons.apache.org/proper/commons-math/javadocs/api-3.0/org/apache/commons/math3/ode/nonstiff/DormandPrince853Integrator.html Dormand Prince 853]
 +
* [https://commons.apache.org/proper/commons-math/javadocs/api-3.4/org/apache/commons/math3/ode/nonstiff/DormandPrince54Integrator.html Dormand Prince 54]
 +
* [https://commons.apache.org/proper/commons-math/javadocs/api-3.1/org/apache/commons/math3/ode/nonstiff/GraggBulirschStoerIntegrator.html Gragg Bulirsch Stoer]
 +
* [https://commons.apache.org/proper/commons-math/javadocs/api-3.4/org/apache/commons/math3/ode/nonstiff/HighamHall54Integrator.html Higham Hall 54]
 +
* Stochastic Solver
  
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 since 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.
+
To create a solver, simply click on the ''create a new solver'' icon on the menu bar.
  
At this point you can also edit or set any of the disease parameters (i.e. Transmission Rate, Recovery Rate, etc).
+
[[Image:CreateSolver1.png]]
If you don't want to do it now it will also be editable any time after the scenario is created.  
+
  
 +
''Figure 4: Launching the new solver wizard''
  
 +
The wizard allows you to name it anything you like. Pick the type of solver you want and click ''next'' or ''finish'' (if you want to skip the dublin core).
  
''Figure 3: The New Disease Dialog''
+
[[Image:CreateSolver2.png]]
  
9) Fill in any Dublin core data you want to add
+
''Figure 5: Creating a new Solver''
  
10) Click finish
+
Once you have created one (or more) solvers, they will all appear in the solvers folder of the project you are working on. Simply drag the solver you want to use into your scenario. Later you can always delete or remove this solver from your scenario and then drag in a different one. This is very powerful. You don't have to make any changes to your models to switch between a finite difference solver, a deterministic numerical integration method, or even a ''stochastic solver''!!
  
11) Under decorators you should see ExperimentalDisease.standard
+
[[Image:CreateSolver3.png]]
  
12) Double click on MODELS in the project explorer. You should see "Cuba" in the Resource Set.
+
''Figure 6: Drag your Solver into your Scenario''
  
13) DRAG your new disease (e.g., ExperimentalDisease.Standard) from decorators (in the project explorer window) into the model "Cuba" in the Rescource Set window. Expand the "Cuba" Model in the Resource Set window to see that it worked. See Figure 4.
+
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 or one of the other numerical integration methods because these algorithms are 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.  
  
 +
For information on the solvers available in STEM, please see the page [[STEM Solvers]]
  
[[Image:Dragdiseasetomodel.jpg|400px]]
+
The other numerical integration algorithms (e.g., DormandPrince853, and DormandPrince 54) use the ''Apache commons mathematical library'' (http://commons.apache.org/math/) numerical integration methods. For more information on these solvers and what the four parameters do, see the documentation on the library web site (http://commons.apache.org/math/userguide/ode.html).
  
''Figure 4. Drag the Disease Model (decorator) into the Model in the Resource Set.''
 
  
=Adding 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.
+
<br>
  
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:StemTut4.png]]
  
+
''Figure 7: Project Explorer''
[Figure 1. 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.
+
To be made executable, the blank scenario further requires a sequencer and a nested model structure.  
  
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).
+
<br>
  
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.
+
= Add Model Containers for the Model Hierarchy  =
  
Observe that the background birth rate/death rate currently applies to all regions in your model.
+
A key concept in STEM is the idea of composing models on top of other models. A model in STEM is a container for graphs; a graph contains nodes, edges and labels. In STEM, a node is typically a geographic region (e.g. France), an edge a relationship between nodes (e.g. the fact that two regions share a common border). Labels store data, for instance the total population of a region or the length of a common border. Models also contain decorators such as disease models or population models. Decorators can create their own labels necessary to store data keeping track of the state of a population. An SI compartmental disease model creates SI labels (on each node) to keep track of the number of susceptible versus infected people in each time step of a simulation.  
  
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.  
+
Models can also contain other models, and this is how you determine dependencies between decorators. As an example, a (mathematical) model of a disease depends on having denominator data such as population data, spatial data (regions), and how regions are connected via common borders, road transportation and air transportation. When something "depends" on something else in STEM, we use nested models to represent such dependencies. A scenario in STEM has a single model (root model if you like) that contains nested models underneath. Deepest down in the model tree you put static data such as graphs containing geographic information (regions with area information and edges representing common borders) and demographic data such as human population counts. This is also where you can place "Population Initializers" to create populations of any type, e.g. animals. On top of this (in the parent model), you can put a mathematical population model describing how the population changes each time step of the simulation. The population model creates the place holders (label and label values) it needs to keep track of the population in each region, and it can also rescale the population initially if needed. This is useful when the population data in STEM (which typically comes from publicly available census data) is not up-to-date with current numbers. On top of the population model (in its models' parent model), you put mathematical models for diseases. Since a disease depends on the initial population numbers calculated by the associated population model (with matching population identifier, e.g. 'human'), it needs to be higher up in the model tree. Finally, above this or in the scenario itself, you create infectors, inoculators or initializers that determines the initial state of the disease (i.e. now many people to infect and where, or what is the background herd immunity).
  
If no population model is specified in your scenario, the background birth and death rate is assumed to be 0.
+
By clicking “New -&gt; model”, you can create an empty model container.  In this example, we will need three different models in a nested structure, so we create three model containers, named ‘geo’, ‘pop’ and ‘dis’ for this example.  
  
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>
+
[Figure 2. Wizard used to define a new Population Model]
+
  
 +
[[Image:StemTut5.png]]
  
 +
''Figure 8: Model Creation''
  
 
<br>
 
<br>
  
=Adding the Geographical Data to the Model=
+
= Import Built-in Models and Graphs from the STEM Library  =
  
14) 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
+
The Models view and the Graphs view (typically located in the lower right corner if you are in the STEM designer perspective) contains pre-built graphs and models you can use to construct your scenario. For convenience, the Models view has commonly used models organized by country. You can select and drag any model from the build-in ones to either the 'Models' folder inside a STEM project, or you can drag it into any existing model part of your project as a child. This screen shot shows both examples:
The models tab is shown selected in the bottom of Figure 1 above. It is also identified by a blue triangle.
+
  
15) Drag this up to the Model "CubaExperimentalDisease" in the Resource set window
+
[[Image:STEM_Drag_Model.png]]
+
''save your work at this point by hitting <ctrl>S''
+
  
=Create a Scenario and Add Your Model to It=
+
When you drag a built-in model into a STEM project, a complete (deep) copy of the model is done. This means you can edit the graph using the STEM [[Visualizing and Editing Graphs|Graph editor]]. If you drag a model into another model in your project, only a reference to the model is added and you cannot edit the model.
  
16) Click on the purple diamond icon to create new scenario
+
This particular model contains (DEU Human Population (Levels: 0,1) contains geographical regions in Germany both admin level 0 (Germany) and 1 (German states), the common borders within Germany as well as the containment relationship between Germany and its states. It also contains population data for each state.
  
17) Give it a name (you might want more than one so index it, for example, as "ExperimentalDisease1")
+
If you want to have more control over the graphs you want as part of your scenario, you can use the Graphs view.  Specific geographical data and the population data can be imported as graphs from the STEM library by pulling the graphs from the STEM resources section on the right into the graphs section on the left under project explorer, or directly under an existing model in your project. Here we use country-specific data for Germany.
  
18) Fill in any Dublin core data you want to add
+
<br>
  
19) Click finish
+
[[Image:StemTut6.png]]
  
20) 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.
+
''Figure 9: Graph Import ''
  
=Add a Sequencer to the Scenario=
+
<br>
  
21) Go to Sequencers on the bottom window - expand fully
+
If you want air transportation as part of your model, you need to select and drag the air transportation graphs from the Graphs view into your model. Air transportation is currently not available in any of the pre-build models.
  
22) Drag Sequential Sequencer 2006 into the Scenario in the Resource Set.
+
<br> <br>
Make sure you have a properties Editor Window open
+
  
23) Click on >Window>other>General>Properties to open the properties view.
+
= Create the Geography Model  =
Open the Disease in the Properties Editor – get ready to Create an Infector
+
  
24) To create an infector you first need to make sure you know the exact ‘Disease Name’ used in step 7 above. To be sure check it as follows. In the Project Explorer, Under Decorators, double click on ExperimentalDisease.standard
+
The bottom model in the model hierarchy is the geographic model. In this case, we will use the pre-build model for Germany human population data down to admin level 1 (states in Germany). This is done by opening the ‘geo.model’ in the Designer view (simply by double-clicking it in the Project Explorer), dragging the model "DEU Human Population (Levels 0, 1)" 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.  
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.  
+
  
 +
<br>
  
[[Image:PropEditor.jpg|600px]]
+
[[Image:StemTut7.png]]  
  
''Figure 5: 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.
+
''Figure 10: Equipping Models '' <br> <br> <br>
Click on the Properties Tab (shown selected) to see the Properties Editor.
+
Here you can also change any of the disease parameters at any time.''
+
  
25) This is the view where you can see, edit, and change any disease parameter. Find and confirm the disease name ("ExperimentalDisease" in this case).
+
= Create the Population Model  =
  
=Creating a Custom Sequencer=
+
In the model called 'pop', we will store the geography model plus a decorator of type standard population model that grows the population given a background birth rate and death rate. The standard population model is created by opening the "New Population Model" wizard in the toolbar. Select "Standard Population Model" in the drop-down and give it a name (e.g. HumanPopulation).  Specify the background birth rate and mortality rate of your population. You also have an option to specify an initial rescaling factor in your population model. You can use this to rescale the population data before running a simulation. This is useful when the population data in STEM comes from census data that's not up-to-date with current numbers. (Currently most census data is from the year 2006 in STEM).
  
Every scenario must also include a "sequencer" which basically is a clock that
+
<br>
regulates time, and an "infector" which sets the initial infectious population. Stem has a build in default
+
<br> [[Image:StemTut8.png]] <br> ''Figure 11: Creating a standard population model '' <br>
sequencer called the "Sequential Sequencer" but you will no doubt want to create your own to specify
+
start time, step size, end time, etc.
+
  
To create a new sequencer click on the New Sequencer Icon which appears as a little clock.
+
Now open the pop.model in the Designer Perspective, and drag the new standard population model into it (from the Decorators folder). Also drag the geography model (geo.model) from the Models folder in the Project Explorer into the pop.model. Save (Ctrl+S) pop.model.
Alternatively, on the menu bar you can select >NEW>SEQUENCER
+
  
[[Image:Sequencer3.jpg|200pm]]
+
[[Image:StemTut8b.png]]
  
''Figure 6: The new Sequencer Icon''
+
= Create the Disease Model  =
  
 +
To compose the disease model, we finally also need a disease. The disease construction is accessible via the “New -&gt; disease” command or by selecting the New Disease Model toolbar icon. For the sake of creating an example disease, note that the transmission 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, we choose a 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
  
The "New Sequential Sequencer" Dialog will open as shown in Figure 7 below.
+
<br> [[Image:StemTut9.png]] <br> ''Figure 12: 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 than 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.  
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.
+
  
Select the starting date.
+
<br> <br>
  
If you wish to specify and End Date be sure to check the "Specify End Date" checkbox.
+
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.  
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.
+
[[Image:StemTut10.png]] <br> ''Figure 13: Setting up the model containing the disease '' <br> <br> <br>
 +
<br>
  
[[Image:Sequencer1.jpg|400pm]]
+
= Create an Infector  =
  
''Figure 7: The New Sequential Sequencer Dialog helps you configure a Sequencer.''
+
The command “New -&gt; infector” allows you to create an infector, innoculator, or initializer. This sets the initial "disease state" for a given population. 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.  
  
 +
<br> [[Image:StemTut11.png]] <br> ''Figure 14: Infector Creation '' <br> <br>
  
Once you have created your sequencer it must be dragged into your scenario folder. Follow the same instructions
+
<br> <br> [[Image:StemTut12.png]] <br> ''Figure 15: ISO Key selection for Infector '' <br> <br>
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 8: Changing the sequencer in the property editor after it has been added to a scenario.''
+
= Create a Sequencer  =
  
=Creating and Adding an Infector=
+
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.  <br>
  
26) Click on the new infector icon (black square with the health symbol and the letter I)
+
[[Image:STEM_New_Sequencer.png]]
 +
<br>
  
27) Name it (e.g., "CubaInfector"), under DiseaseName: "ExperimentalDisease"
+
= Equip the Scenario  =
  
28) Under country select Cuba
+
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>
  
29) Click on the Scenario to open it in the Resource set
+
[[Image:Stem scen tut13.png]] <br> ''Figure 16: Scenario Completion '' <br> <br>
  
30) Drag the CubaInfector from Decorators into the scenario (open it to see it)
+
<br>
  
31) 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).
+
= Run the Scenario  =
  
32} Save your work at this point by hitting <ctrl>S
+
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.
  
33) Click on the scenario, right click and run
+
<br> <br>
 +
= Tips =
 +
In case you want to change the properties of a specific decorator in your scenario
 +
Changing properties is only possible in the specific decorator(e.g disease model) under the decorators section in the project explorer.
 +
In the STEM models and the scenario is it not possible to change the properties!

Latest revision as of 18:00, 9 February 2018

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 -> STEM Project” command.


Newproject.jpg

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



StemTut2.png

Figure 2: Project Explorer
Give your project a new name, e.g. 'ExperimentalDisease'. The structure created under the new project contains headings for various components, including a substructure for the scenario definitions themselves.



Create a Scenario

The Scenario is the basic executable unit in STEM. 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

Starting with Version 2.0 of STEM (October 2013), it is no longer necessary to pick the "Solver algorithm" you want to use. Solvers are now first class objects in STEM so you can easily change your choice of solver without changing your scenario. See the section Create a Solver below.

Create a Solver

With STEM V2.0 and later you can create any one of several different "Solver" objects to solve (integrate) the differential equations in your model or models. Choices include:

To create a solver, simply click on the create a new solver icon on the menu bar.

CreateSolver1.png

Figure 4: Launching the new solver wizard

The wizard allows you to name it anything you like. Pick the type of solver you want and click next or finish (if you want to skip the dublin core).

CreateSolver2.png

Figure 5: Creating a new Solver

Once you have created one (or more) solvers, they will all appear in the solvers folder of the project you are working on. Simply drag the solver you want to use into your scenario. Later you can always delete or remove this solver from your scenario and then drag in a different one. This is very powerful. You don't have to make any changes to your models to switch between a finite difference solver, a deterministic numerical integration method, or even a stochastic solver!!

CreateSolver3.png

Figure 6: Drag your Solver into your Scenario

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 or one of the other numerical integration methods because these algorithms are 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.

For information on the solvers available in STEM, please see the page STEM Solvers

The other numerical integration algorithms (e.g., DormandPrince853, and DormandPrince 54) use the Apache commons mathematical library (http://commons.apache.org/math/) numerical integration methods. For more information on these solvers and what the four parameters do, see the documentation on the library web site (http://commons.apache.org/math/userguide/ode.html).




StemTut4.png

Figure 7: Project Explorer

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


Add Model Containers for the Model Hierarchy

A key concept in STEM is the idea of composing models on top of other models. A model in STEM is a container for graphs; a graph contains nodes, edges and labels. In STEM, a node is typically a geographic region (e.g. France), an edge a relationship between nodes (e.g. the fact that two regions share a common border). Labels store data, for instance the total population of a region or the length of a common border. Models also contain decorators such as disease models or population models. Decorators can create their own labels necessary to store data keeping track of the state of a population. An SI compartmental disease model creates SI labels (on each node) to keep track of the number of susceptible versus infected people in each time step of a simulation.

Models can also contain other models, and this is how you determine dependencies between decorators. As an example, a (mathematical) model of a disease depends on having denominator data such as population data, spatial data (regions), and how regions are connected via common borders, road transportation and air transportation. When something "depends" on something else in STEM, we use nested models to represent such dependencies. A scenario in STEM has a single model (root model if you like) that contains nested models underneath. Deepest down in the model tree you put static data such as graphs containing geographic information (regions with area information and edges representing common borders) and demographic data such as human population counts. This is also where you can place "Population Initializers" to create populations of any type, e.g. animals. On top of this (in the parent model), you can put a mathematical population model describing how the population changes each time step of the simulation. The population model creates the place holders (label and label values) it needs to keep track of the population in each region, and it can also rescale the population initially if needed. This is useful when the population data in STEM (which typically comes from publicly available census data) is not up-to-date with current numbers. On top of the population model (in its models' parent model), you put mathematical models for diseases. Since a disease depends on the initial population numbers calculated by the associated population model (with matching population identifier, e.g. 'human'), it needs to be higher up in the model tree. Finally, above this or in the scenario itself, you create infectors, inoculators or initializers that determines the initial state of the disease (i.e. now many people to infect and where, or what is the background herd immunity).

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


StemTut5.png

Figure 8: Model Creation


Import Built-in Models and Graphs from the STEM Library

The Models view and the Graphs view (typically located in the lower right corner if you are in the STEM designer perspective) contains pre-built graphs and models you can use to construct your scenario. For convenience, the Models view has commonly used models organized by country. You can select and drag any model from the build-in ones to either the 'Models' folder inside a STEM project, or you can drag it into any existing model part of your project as a child. This screen shot shows both examples:

STEM Drag Model.png

When you drag a built-in model into a STEM project, a complete (deep) copy of the model is done. This means you can edit the graph using the STEM Graph editor. If you drag a model into another model in your project, only a reference to the model is added and you cannot edit the model.

This particular model contains (DEU Human Population (Levels: 0,1) contains geographical regions in Germany both admin level 0 (Germany) and 1 (German states), the common borders within Germany as well as the containment relationship between Germany and its states. It also contains population data for each state.

If you want to have more control over the graphs you want as part of your scenario, you can use the Graphs view. Specific geographical data and the population data can be imported as graphs from the STEM library by pulling the graphs from the STEM resources section on the right into the graphs section on the left under project explorer, or directly under an existing model in your project. Here we use country-specific data for Germany.


StemTut6.png

Figure 9: Graph Import


If you want air transportation as part of your model, you need to select and drag the air transportation graphs from the Graphs view into your model. Air transportation is currently not available in any of the pre-build models.



Create the Geography Model

The bottom model in the model hierarchy is the geographic model. In this case, we will use the pre-build model for Germany human population data down to admin level 1 (states in Germany). This is done by opening the ‘geo.model’ in the Designer view (simply by double-clicking it in the Project Explorer), dragging the model "DEU Human Population (Levels 0, 1)" 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 10: Equipping Models


Create the Population Model

In the model called 'pop', we will store the geography model plus a decorator of type standard population model that grows the population given a background birth rate and death rate. The standard population model is created by opening the "New Population Model" wizard in the toolbar. Select "Standard Population Model" in the drop-down and give it a name (e.g. HumanPopulation). Specify the background birth rate and mortality rate of your population. You also have an option to specify an initial rescaling factor in your population model. You can use this to rescale the population data before running a simulation. This is useful when the population data in STEM comes from census data that's not up-to-date with current numbers. (Currently most census data is from the year 2006 in STEM).



StemTut8.png
Figure 11: Creating a standard population model

Now open the pop.model in the Designer Perspective, and drag the new standard population model into it (from the Decorators folder). Also drag the geography model (geo.model) from the Models folder in the Project Explorer into the pop.model. Save (Ctrl+S) pop.model.

StemTut8b.png

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 or by selecting the New Disease Model toolbar icon. For the sake of creating an example disease, note that the transmission 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, we choose a 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 12: 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 than 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.



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.

StemTut10.png
Figure 13: Setting up the model containing the disease



Create an Infector

The command “New -> infector” allows you to create an infector, innoculator, or initializer. This sets the initial "disease state" for a given population. 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 14: Infector Creation



StemTut12.png
Figure 15: 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.

STEM New Sequencer.png

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 16: 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.



Tips

In case you want to change the properties of a specific decorator in your scenario. Changing properties is only possible in the specific decorator(e.g disease model) under the decorators section in the project explorer. In the STEM models and the scenario is it not possible to change the properties!

Back to the top