Creating a STEM Scenario
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.
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
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 YOUR_SCENARIO_NAME="Cuba". For the disease model we will use YOUR_MODEL_NAME="ExperimentalDisease";
Creating the Project
1) Click on the Icon with many little squares (or new->STEM Project) and create new STEM project (ExperimentalDisease). See Figure 1.
Figure 1: Creating a New STEM Project ("ExperimentalDisease").
Figure 2: The New Project Dialog
2) Open the new project – you should see several folders including: decorators, graphs, etc.
Creating a New Model
3) Click on blue triangle (or New->Model) to create new model (for example: Cuba)
4) Fill in any Dublin core data you want to add
Adding a Disease to the Model
5) Click on the New Disease icon (black square with the health symbol) or on the menu bar click ->new>new disease
6) This will launch the Dialog shown in Figure 3. Fill in the Name: (ExperimentalDisease)
7) Fill in the Disease Name: You can use the same name you used in (6) (ExperimentalDisease)
8) Select the DiseaseModel in the ComboBox: e.g., select your Disease model. For our case we will use "DeterministicSIDiseaseModel"
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.
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.
Figure 3: The New Disease Dialog
9) Fill in any Dublin core data you want to add
10) Click finish
11) Under decorators you should see ExperimentalDisease.standard
12) Double click on MODELS in the project explorer. You should see "Cuba" in the Resource Set.
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.
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.
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.
File:PopulationModelToolbar [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.
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).
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.
Observe that the background birth rate/death rate currently applies to all regions in your model.
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.
If no population model is specified in your scenario, the background birth and death rate is assumed to be 0.
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.
[Figure 2. Wizard used to define a new Population Model]
=Adding the Geographical Data to the Model=
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 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
save your work at this point by hitting <ctrl>S
Create a Scenario and Add Your Model to It
16) Click on the purple diamond icon to create new scenario
17) Give it a name (you might want more than one so index it, for example, as "ExperimentalDisease1")
18) Fill in any Dublin core data you want to add
19) Click finish
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.
Add a Sequencer to the Scenario
21) Go to Sequencers on the bottom window - expand fully
22) Drag Sequential Sequencer 2006 into the Scenario in the Resource Set. Make sure you have a properties Editor Window open
23) Click on >Window>other>General>Properties to open the properties view. 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 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.
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. 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).
Creating a Custom Sequencer
Every scenario must also include a "sequencer" which basically is a clock that 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.
To create a new sequencer click on the New Sequencer Icon which appears as a little clock. Alternatively, on the menu bar you can select >NEW>SEQUENCER
Figure 6: The new Sequencer Icon
The "New Sequential Sequencer" Dialog will open as shown in Figure 7 below. 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.
If you wish to specify and End Date be sure to check the "Specify End Date" checkbox. 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.
Figure 7: The New Sequential Sequencer Dialog helps you configure a Sequencer.
Once you have created your sequencer it must be dragged into your scenario folder. Follow the same instructions 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).
Figure 8: Changing the sequencer in the property editor after it has been added to a scenario.
Creating and Adding an Infector
26) Click on the new infector icon (black square with the health symbol and the letter I)
27) Name it (e.g., "CubaInfector"), under DiseaseName: "ExperimentalDisease"
28) Under country select Cuba
29) Click on the Scenario to open it in the Resource set
30) Drag the CubaInfector from Decorators into the scenario (open it to see it)
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).
32} Save your work at this point by hitting <ctrl>S
33) Click on the scenario, right click and run