Skip to main content
Jump to: navigation, search

How scenarios are structured

Revision as of 10:23, 19 August 2012 by (Talk | contribs) (Scenario Structure)


back to STEM Contents Page

Scenario Structure

At the beginning of a simulation, STEM allows decorators such as population models, population initializers and disease models to initialize themselves. For instance, when a disease model is initialized, it creates the disease model labels necessary to track the state of the disese in a population. A disease model depends on the population model labels created by a population model to be able to create the disease model labels. Furthermore, a population model depends on the existance of static population labels, created either by a population initializers or by dragging population data into your model from the STEM library.

Figure 1 basic scenario structure

Consequently, the order of initialization becomes important, and the order is controlled by nesting models inside models. Decorators that are deeper in the model tree are initialized before decorators higher up in the tree. See the figure below for an example. Deepest in the tree is a population initializer that creates the static population labels needed by the demographic population model one level up. The demographic population model subdivides the population into subgroups needed by the disease model in the level above.

In summary, the order is population initializers before population models, population models before disease models, and disease models before infectors/inoculators.

Download the Templates

This tutorial shows users how to compose a basic disease model scenario and a basic foodborne disease scenario using a project containing prepared templates. Please begin by downloading the template scenario project from the download page unzip it and import it into your workspace.

Template for a Basic Scenario with a Human Disease

In this tutorial you will:

  1. Add a geographic model to the GeographicModelGroup model node
  2. Create a human population model
  3. Add the population model to the PopulationModelLevel model node
  4. Create a disease model
  5. Add the disease model to the DiseaseModelLevel model node
  6. Create an initializer for the disease
  7. Add the initializer to the scenario
  8. Create a time sequencer
  9. Add the time sequencer to the scenario
  10. Run your scenario

Define the Geography

Figure 2 pick a geography (including the human census data)

After you successfully download, extract, and import the scenario (archive file, open the 'Templates project' in the designer perspective. Double click on the Disease Model scenario and you should see a series of empty nested project (see Figure 2). The nested models within the scenario are named to make it easy to see what elements should be added to each model. In Figure 2 we navigated to the libraries of prebuilt models. The Models Tab contains folders with geographic information by country. In this example we pick Japan, and the prebuilt model with admin 0,1,2 data including the Human population data.

Figure 3 drag geographic model(s) into the folder labeled Geographic Model Group

Figure 3 shows the scenario with all models expanded. The data for Japan has been dragged into the project named Geographic Model Group

Create and add a PopulationModel

Figure 4

Create a new population model (figure 4) and drag it to the model PopulationModelLevel. Figure 5 shows the population model in the PopulationModelLevel. The GeographicModelGroup has been collapsed for clarity (but it still contains the model of Japan).

Figure 5

Create and add a DiseaseModel

Figure 6

Create a new disease model (Figure 6) and drag it into the model DiseaseModelLevel. Remember, you need to set the transmission rate and define the other epidemiological parameters for your disease. The default transmission rate is zero so if you don't change this your disease will not spread.

Figure 7 shows the DiseaseModelLevel with the disease model added. The PopulationModelLevel model has been collapsed for clarity (but it still contains the GeographicModelGroup).

Initialize the Scenario

Figure 7

In order to run a simulation, models must be initialized. This is the difference between a Model and a Scenario. The model DiseaseModelLevel contains a disease model for the common cold but no members of the human population have actually been given a cold. This is done in the Scenario.

Figure 8

Figure 8 shows the Templates project in the Project Explorer view. To create an initializer (the most flexible decorator to use in order to set initial conditions for the disease state), open the decorators folder. Right click on the disease model, and click on Create new initializer. The new initializer dialog allows the user to define the initial state of every compartment in a single step. NOTE that in Figure 8 we have chosen to initialize by fraction of the population instead of by population count.

Figure 9

The disease model initializer will appear in the decorators folder. Drag it into the scenario. You must then create a new sequencer and drag that into the scenario as well.

Figure 10

Figure 10 shows the disease model initializer after it has been dragged into the scenario.

The models within the scenario have been collapse for clarity (but the nested models are still there). Both the disease model initializer and the sequencer are shown.

Template for a Food Borne Disease Scenario

The second scenario template provided in the templates project contains nested models to show how a food borne disease scenario should be structured.

Figure 11: Pig Population Model

Food Borne Scenario Exercise

As an exercise try the following steps.

  1. Start with an empty templates project (backup and delete your version above and re-extract the zip file)
  2. Add a geographic model to the GeographicModelGroup model node
  3. STEM does not provide basic census data for animals like pig or pork. You need to initialize them. The simplest way to do this is to create a PopulationInitializer for pig and for pork.
  4. Drag the two PopulationInitializers into the GeographicModelGroup
  5. create a population model for pig (see figure 12).
  6. create a population model for pork
  7. Add both population models to the PopulationModelLevel model node
  8. Create two diseases. One for pig and one for pork. For now, use the Salmonella model. The disease names can be SalmonellaPig and SalmonellaPork. The first should affect population pig, and the second should affect population pork.
  9. Add both disease models to the DiseaseModelLevel model node
  10. Create an initializer for both the diseases
  11. Add the initializers to the scenario
  12. Define a slaughterhouse as (shown in Figure 13). This maps pigs to pork and the diseases of pigs to diseases of pork.
  13. Add the slaughterhouse to the scenario
  14. Create a time sequencer
  15. Add the time sequencer to the scenario
  16. Run your scenario

Create a model of non-human populations

Figure 12: Pig Population Model

Figure 12 shows creation of a new population model. If your population model is for something other than human (our default), please be sure to change the default ModelName from HumanPopulationModel to (e.g.) something like PigPopulationModel. Here we define the population pig.

Creating a Slaughterhouse

Figure 13: Creating a SlaughterHouse

Figure 13 shows the dialog for creating a new slaughterhouse. This maps pigs to pork and Salmonella in pigs to Salmonella in pork.

The completed template

Figure 14: The completed scenario

Figure 14 shows how your finished scenario should be structured. All nested models are shown expanded. Each model contained by another models must contain everything the higher level model requires to run.

Back to the top