View source for How scenarios are structured

[[Image:STEM TOP BAR.gif|800px]]

{| align="right"
  | __TOC__
  |}


'''[http://wiki.eclipse.org/index.php/STEM 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.


[[Image: STEM_Nesting_Models.png|left|frame|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.

<br>

==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
[http://www.eclipse.org/stem/downloads.php#DownloadableScenarios|the download page]
unzip it and [[Importing_and_Exporting_Projects|import it]] into your workspace.

==Template for a Basic Scenario with a Human Disease==


In this tutorial you will:

# Add a geographic model to the GeographicModelGroup model node
# Create a human population model
# Add the population model to the PopulationModelLevel model node
# Create a disease model
# Add the disease model to the DiseaseModelLevel model node
# Create an initializer for the disease
# Add the initializer to the scenario
# Create a time sequencer
# Add the time sequencer to the scenario
# Run your scenario


===Define the Geography===

<br> [[Image: ScenarioTutorial2.png |400px|none|frame|Figure 2 pick a geography (including the human census data)]]


After you successfully download, extract, and import the scenario (archive file Templates.zip), 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. 

<br> [[Image: ScenarioTutorial3.png |400px|none|frame|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===

<br> [[Image: ScenarioTutorial4.png |400px|none|frame|Figure 4 ]]

<br>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). 

<br> [[Image: ScenarioTutorial5.png |400px|none|frame|Figure 5 ]]

===Create and add a DiseaseModel===

<br> [[Image: ScenarioTutorial6.png |400px|none|frame|Figure 6 ]]

<br>
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===

<br> [[Image: ScenarioTutorial7.png |400px|none|frame|Figure 7 ]]

<br>

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'''. 
<br>

[[Image: ScenarioTutorial8.png |400px|none|frame|Figure 8 ]]

<br>

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.

<br>

[[Image: ScenarioTutorial9.png |300px|none|frame|Figure 9 ]]

<br>

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.

<br>

[[Image: ScenarioTutorial10.png |300px|none|frame|Figure 10 ]]


<br>

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. 

<br>

==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.

<br>[[Image: ScenarioTutorial10B.png |400px|none|frame|Figure 11: Pig Population Model ]]
<br>

===Food Borne Scenario Exercise===

As an exercise try the following steps.

# Start with an empty templates project (backup and delete your version above and re-extract the zip file)
# Add a geographic model to the GeographicModelGroup model node
# 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''.
# Drag the two PopulationInitializers into the GeographicModelGroup
# create a population model for ''pig'' (see figure 12). 
# create a population model for ''pork''
# Add both population models to the PopulationModelLevel model node
# 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''. 
# Add both disease models to the DiseaseModelLevel model node
# Create an initializer for both the diseases
# Add the initializers to the scenario
# Define a slaughterhouse as (shown in Figure 13). This maps pigs to pork and the diseases of pigs to diseases of pork.
# Add the slaughterhouse to the scenario
# Create a time sequencer
# Add the time sequencer to the scenario
# Run your scenario

===Create a model of non-human populations===

<br>

[[Image: ScenarioTutorial11.png |400px|none|frame|Figure 12: Pig Population Model ]]
<br>

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===

<br>[[Image: ScenarioTutorial12.png |400px|none|frame|Figure 13: Creating a SlaughterHouse ]]

<br>
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===

<br>[[Image: ScenarioTutorial13.png |400px|none|frame|Figure 14: The completed scenario ]]


<br>

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.