Sample Projects available for Download
- 1 Sample Projects Available For Download
- 1.1 Malaria Population Replay Demonstration
- 1.2 Food borne disease
- 1.3 Evacuation Demonstration
- 1.4 (Asia) Mosquito Density Model
- 1.5 Automated Experiment Example
- 1.6 Multi-Population Example
- 1.7 Multi-Population Pajek Graph Example
- 1.8 Square Lattice Example
- 1.9 Mexico/USA H1N1 Scenario
- 1.10 Global Earth Science Models
- 1.11 Global Geographic Models Only
- 1.12 Super-Continent Examples
- 1.13 Chicken Pox
Sample Projects Available For Download
The STEM home page ([]) contains several example projects users can import and run with STEM. STEM is designed to allow collaboration and sharing of work by simply importing and exporting projects from your workspace.
For information on how to import a project, please see: Importing and Exporting Projects
Sample Projects include:
- Malaria population replay demonstration
- Food borne disease: Beef production from a cattle population
- Evacuation (Demonstration of Migration Edges)
- Chickenpox: The ChickenPox example scenario shows how to use the new aging (demographic) population model. The initial conditions in this example start the population far from equilibrium.
- Asia Mosquito Density Model Demonstrates how the earth science data can be used to generate seasonal mosquito density estimates in Asia. Requires the Global Geography Models and the Global Earth Science Models.
- Automated Experiment Example Demonstrates the automated experiment feature in STEM and how it is used to fit unknown EPI parameters to a reference incidence data set
- Global Earth Science Models for release 1.2.1 and later Continent-level models of Earth Science Data including elevation, rainfall, temperature, and vegetation coverage. OBSERVE: You need to access the STEM update site and install the "STEM Earth Science Data for 2010" plugin to use these models.
- Global Earth Science Models for STEM release 1.2.0 and earlier Continent-level models of Earth Science Data including elevation, rainfall, temperature, and vegetation coverage.
- Multi-Population Example Demonstrates a simplified multi-population disease model with anopheles mosquitoes and humans
- Pajek Import Example Demonstrates a simplified multi-population disease model where the entire graph is created using the new Pajek Import facility
- Square Lattice Example Demonstrates both population migration and disease spread on a Square Lattice
The malaria replay demonstration requires a build from Mar 16, 2012 or later
The evacuation intervention demo requires a build from July 15, 2011 or later
The Automated Experiment Example requires a STEM build from Sept 2, 2010 or later
The Multi-population Example requires a STEM build from Aug 31, 2010 or later
The Square Lattice demo described below requires STEM version dated July 1, 2010 or later
The SuperContinentExample project requires GlobalGeography to exist in the STEM workspace before it any of the examples can run
Some of the example projects you can download are very large as they contain continents or even groups of continents. Before you try to run any of these large scenarios you must make sure you allocate enough system memory for STEM. If you don't do this the application may hang or crash with a "Heap Space" error. To allocate enough memory in Windows, create a shortcut for launching STEM. You may place this anywhere (e.g., on your desktop or on the quicklaunch bar).
Right click on the shortcut. Select "Properties" You should see a field in the Properties Dialogue labeled Target: to the right in the text field you will see something like
C:\stem_builds\stem\STEM.exe -vmargs -Xms812M -Xmx812M
To launch STEM with more memory you must add "virtual machine arguments" to the target line. For example, Target:
C:\stem_builds\stem\STEM.exe -vmargs -Xms896M -Xmx896M
Should work for the demo projects available.
On MAC OS X, using the finder, navigate to where the STEM application is located, right click and select "Show Package Content". Navigate to Contents->MacOS and open the STEM.ini file in an editor. Change the -Xms and the -Xmx lines to increase the memory, e.g. -Xms896M -Xmx 896M or more depending on how much memory is available.
In this demo, we are reading in a time series of Anopheles population data for 71 regions in Thailand and use it to drive a model of Malaria transmission. Seasonal counts of anopheles mosquitos are recorded, as well as counts of births and deaths. You'll notice that the data being read in was recorded earlier using the CSV logger in STEM and that the ExternalDataSourcePopulationModel is configured to read data from the folder containing the run parameter file as well as an XMI serialized version of the decorator generating the data. This gives us the flexibility to replay population data for more exotic kinds with non-tranditional labels. The same rule applies for disease model data read by an ExternalDataSourceDiseaseModel.
If your data files were not generated by STEM, you can still use an ExternalDataSourcePopulationModel and point it directly to the folder containing CSV data files. The folder must contain a file Count_x.csv (where x is the administrative level of the regions recorded in the file, e.g. 2) and use the same format as STEM log files. The folder can optionally contain the files 'Births_x.csv' and 'Deaths_x.csv' to indicate the number of births and deaths of the population in each time step. This information is feed into any disease model using external data source population model. If births and deaths data is not available, it is assumed that any increase in population is due to births only (zero deaths) and any decrease is due to deaths only (no births). Similarly, if there is a mismatch in the reported birth and deaths compared to the reported total count, the birth and deaths are adjusted to make up for the difference. This can happen if you recorded data from a STEM simulation that had population migration in the model.
Food borne disease
The BeefArgentina scenario is a model of beef production and consumption in Argentina using the new SlaughterHouse and FoodConsumer classes. The graph containing the cattle population, cattle transportation and slaughterhouses was created with the Pajek importer. The edges for beef transportation from this graph to the Argentina graph were created with the Graph Editor. Disease transmission from cattle to beef to human is also modeled.
Three of the nodes in the Pajek imported graph shown in the left image contain cattle populations. Cattle are born there and transported to the two nodes that contain slaughterhouses. In these nodes cattle is transformed to beef by using the SlaughterHouse class. The SlaughterHouse also models disease transmission in the transformation process (for example: 90% of infectious cattle transform to infectious beef and 10% to non-infectious beef). Beef is transported from the SlaughterHouse nodes to certain regions in Argentina as shown in the right image. In the Argentina graph beef consumption is modeled using the FoodConsumer class. This class also models disease transmission from beef to humans by consumption.
The downloadable archive contains the Pajek file for the graph.
2. More food borne demos coming soon....
The evacuation demonstration project aims to demonstrate how interventions can be used in STEM to control an outbreak. In this simple example, we have two regions (Square 0 and Square 1). The regions are connected by symmetrical migration edges moving 5 % of the population from region 0 to region 1, and 5 % of the population from region 1 to 0 in each time step. Hence the total population count is preserved in each region.
Region 1 has a hospital. The hospital is represented by a intervention label inside the HospitalGraph.graph file. You'll see that the hospital has the capacity to vaccinate 50 people per time step (daily).
In the scenario "NoEvacuationsScenario", an outbreak occurs in region 0 and no intervention takes place. Via migration the disease also spreads to region 1.
In "EvacuationScenario", after more than 5 cases per day occurs in region 0, an intervention policy is triggered. The policy does the following:
1. It cuts off any migration of people from region 1 to region 0.
2. It increases the migration of people from region 0 to region 1 (where the hospital is).
3. It increases the vaccination capacity of the hospital from 50 per day to 100 per day.
Once the number of cases in region 0 drops below 5 per day again, migration and vaccination are set back to their original settings
In the figure below, you'll see that the policy triggers around time step 6 and the population numbers starts dropping in region 0 due to evacuation. Correspondingly, the population increases in region 1. When the outbreak is under control at around time step 25, the migration is balanced out and the population numbers converges back towards the original values.
If we look at the cumulative disease deaths occurring in both scenarios, the figure below indicates that by evacuating and increasing vaccination capacity, a total of about 65 lives are saved.
This downloadable scenario demonstrates how the earth science data can be used to generate seasonal mosquito density estimates in Asia. Before you try to run this scenario you much also install the STEM Earth Science Data Feature for the year 2010 (the year used in this example). The scenario (configured for Asia) also requires the Global Geography Models and the Global Earth Science Models available on the STEM Downloads page. You can easily reconfigure this scenario for the entire globe or for other selected regions. The screenshot below shows the Asia Mosquito Model running as downloaded. On the right hand side in the Project Explorer the scenario is expanded to show how it is constructed. The model contains the prebuild Global Geography Model (Human) for Asia along with its polygons, nodes, and edges, as well as the corresponding Asia earth science model (this in turn contains rainfall, temperature, vegetation, and elevation data for the same regions of Asia). These, together with an Anopheles Initializer, are contained in a parent model simply called Asia. The parent model along with the STEM population model for Anopheles are placed in the parent scenario. Users may easily modify this to study other regions. In the future the Anopheles model will be used as part of a complete vector disease model for Malaria and other conditions.
Notice: You probably need to change the reference population and reference population density in the STEM preferences to ensure the map colors are not saturated. When STEM determines the intensity of the color used to fill regions on the map, it takes the actual count (in case the number of Anopheles mosquitos) and divides by the reference population. The number between 0 and 1 (if it's larger than 1 it's set to 1) determines the intensity of the color. See screenshot below for numbers that are reasonable for this particular scenario:
In this example, we have been given historical incidence data for a disease with unknown epi parameters and we want to try and determine what those parameters are. All we know is that the first cases showed up in Stockholm. If you import the demo project into your workspace, the reference incidence data is located under the "Recorded Simulations/Reference" folder in the Incidence_1.csv file (the other files in the folders are not used in this example).
We decide to try and fit an SIR model to the incidence data, and we would like to determine three unknown parameters:
1. What was the transmission rate of the outbreak?
2. How long were infected individuals shedding viruses (i.e. recovery rate)?
Given these two parameters it's possible to determine the reproductive number of the disease, an important epi parameter.
We also have one more unknown we would like to estimate
3. What was the initial background immunity to the disease.
Next, open the "Experiments" folder in the project explorer and double click "AutomatedExperiment.autmaticexperiment" it to bring up its editor. Select the top node in the editor and look at its properties in the properties view.
Automatic Experiment Editor
You will notice that the automatic experiment will run a scenario called "AutomatedExperiment.scenario". This is a basic SIR scenario where with a few initial cases of the disease occuring in Stockholm, as well as an inoculator to initialize the background herd immunity. You will also see that the algorithm being used to fit parameters to the reference is called "Nelder-Mead", and that an error function called "Simple error function" is used. Nelder-Mead is a well-known numerical model optimization algorithm, and the "Simple error function" calculates a normalized root mean square error between the incidence reported in the reference and the incidence calculated by the model simulation. The incidence is aggregated over all locations that are common between the model and the reference.
You'll also see that the maximum number of iterations is 1000. This means that at most 1000 simulations are run before either the algorithm stops or it restarts itself using the optimal set of parameter values found so far. If "Reinit" is false, the algorithm stops after either a solution having an error tolerance smaller than the one specified (1E-6) is found, or the maximum number of iterations is reached. If "Reinit" is true, the algorithm restarts itself again and stops only when the the solution converges towards the same minimum twice.
If you expand the top node "AutomatedExperiment.autmaticexperiment" in the editor you'll see that the automated experiment has 3 parameters it attempts to fit:
1. transmissionRate. The initial guess is 0.8 and the algorithm will use a step size of 0.2 when walking the parameter space for this parameter. Also, the maximum and minimim values for this parameter is 0.001 and 10. You can modify any of these values in the properties view.
2. recoveryRate. The initial guess is 0.2, step is 0.3 and the parameter value is between [0.001, 2.0]
3. inoculatedPercentage. The initial guess is 20, the step is 30 and the parameter is between [0,100]
All three parameters also reference the model the parameter belong to, in this case the first two reference the disease model and the last reference the inoculator.
To start running the automated experiment, right click on the "AutomatedExperiment.autmaticexperiment" file in the project explorer and select Run. STEM will automatically switch to the Automated Experiment perspective and the Automated Experiment view.
You'll see a view with tab options on top ("Error Convergence", "Incidence vs Time" etc.). Select "Current Values". You'll be shown a scrolling list of parameter values and to the right you'll see the calculated normalized root mean square error for that set of parameters.
The history of parameter values and the associated error is shown in the Current Values view.
The "Error Convergence" shows a graph of the calculated error for each simulation and you'll notice how the error gets smaller and smaller. "Incidence vs Time" shows the latest incidence calculated by the current set of parameters compared to the reference incidence. Click the link below to see an animation demonstrating how the incidence is converging towards the reference.
The current calculated incidence versus the reference incidence Click here to see animation
"Error vs Time" shows the difference in incidence between the reference and the current model, compared to the difference in the best fit found so far. Finally, you can stop and restart an automated experiment using the "Contols" tab. When it looks like the algorithm has converged and the error is not changing much it is often useful to stop the experiment and restart it manually using the current optimal set of parameter values found. You can also specify any other parameter values on the Controls page and restart the experiment from those.
If you let the algorithm run until it completes (after about 340 simulations), it ends up with the following estimates for the parameters:
- transmissionRate: 1.199874
- recoveryRate: 0.30012
- inoculatedPercentage: 34.9852
You've probably already guessed it, but the reference data in this case was actually generated using a model with known parameter values. The values were 1.2 for transmission rate, 0.3 for recovery rate and the inoculated percentage was 35% (you can try plugging these values into the automated experiment, the error returned should be 0). You can force the algorithm to search for an even better fit by lowering the Tolerance parameter in the automated experiment (the tradeoff being that it takes longer to finish).
Each combination of parameter value tried and the resulting error is stored in a file called resultLog.csv in a folder AutoExpTempDir in the STEM workspace.
Figure 1a-b. Square lattice world where the anopheles and human population is evenly distributed on each lattice square (a), and where there is a human village located in the center square (b). The edges are the common borders where both anopheles mosquitos and humans are mixing.
The Multi-Population example contains two scenarios of very much simplified Malaria models spreading across a 3x3 square lattice world. In the first example (Figure 1a), each node contains the same number of humans (50) and the same number of anopheles mosquitos (10,000). In the second example (Figure 1b), there is a village in the center square lattice containing 1,000 humans.
The disease is only spreading from infected humans to susceptible mosquitos or from infected mosquitos to susceptible humans, and it starts off by infecting 5 anopheles mosquitos in the upper left square. No infections transmit directly from human to human or mosquito to mosquito. The example also contains the log files from both scenarios, and a comparison between the incidence in the lower right square for both scenarios is shown in Figure 1c below. As can be seen, with the village in place, the incidence peaks about a week earlier for the lower right square. It should be noted, that in this simple sample model the mixing between anopheles members in two neighbouring nodes is at the same rate as the mixing between the human members of the very same nodes. In a real world example one would have to specify these rates seperately.
Figure 1c. Comparison of the daily incidence for both scenarios available in the Multi-Population example. In the scenario having a village in the center square, the incidence in the lower right square peaks about a week earlier than without the village.
Please find documentation for this downloadable scenario on the wiki page Importing a Pajek Graph.
Figure 2. Square Lattice Example
The Square Lattice Example shows how a square lattice, migration edges, and initial population gradient can be used to model the interaction between an infected and uninfected population. It also demonstrates the hierarchy required to set up a SquareLatticeScenario.scenario: disease models must contain population models, and population models must contain initialized graphs, etc.
As illustrated in the figures that follow, the Square Lattice Example shows how to use migration edges to create two population gradients that cause a population to spread out over space and time. Only one of two populations is initially infected with a disease so you can see both the spread of disease within the original population as well as the eventual transmission from the infected population to the susceptible group when they meet. To accomplish this, the example uses both a standard population model and a Population Initializer (see Figure 1 below and the Tutorial on Using Structured Populations). The population initializer places an initial number of individuals at two separate locations at time zero. Migration edges exist (with equal migration rates) in both directions between all sites but, because there is a population gradient, the population spreads out or diffuses across the lattice.
Note that the components that appear when you click on SquareLatticeScenario.scenario (Figure 2, right) are hierarchical. The two population initializers are placed within the innermost option, HumanPopulation1.standard. The standard population object (HumanPopulation.standard) depends on the existence of the initialized graph and, therefore, is placed in the outer HumanPopulationModel. Both of these submodels are components or bundles that can be reused across many scenarios. Finally, the disease itself (Flu.standard) is a human disease that depends on a contained human model so it is placed in the outermost model of the hierarchy (FluLatticeModel). This too is a reusable component.
The Infector for the disease (FluInfector.standard) depends on a model of what is already known about the disease. An infector changes the state of a model by moving individuals from the susceptible state to the infectious state (given the presence of the indicated disease). As such, an infector is really part of the scenario - the topmost level in the hierarchy that contains ALL models.
In the figures below, you can see the initial population spread by migration edges. In the same simulation at runtime you can select the disease as the property to display and watch the disease spread.
Figures 3a-c. Spread of the Human Population by Migration Edges
The figures above show the spread of the population itself by migration edges. The population is seeded in the center (10x10) and in a node just left of center. The center population is much larger than the smaller seed to the left (the intensity is saturated). Only the population to the left is infected initially. Open the infector and the population initializer in the property editor to see the initial values. As the infected population on the left spreads, it eventually makes contact with and infects the main population spreading from the center.
Figures 4a-c. Spread of the Disease
The figures above show the same simulation but display the fraction of people infected as a function of time. Note that the intensity does not reflect the NUMBER of infections (only the fraction). When the infected population on the left reaches the much larger fully susceptible (but not yet infected) population spreading from the right, the intensity actually goes down as the fraction of people infected drops (initially) at the point of contact (see the middle image above). Eventually (right) the main population also becomes infected.
The Mexico/USA H1N1 Scenario was created in the early spring of 2009 as a first attempt to measure the basic reproductive number, Ro, of the H1N1 virus. Little biosurveillance data was available but we knew that the first 10 people had been reported with H1N1 in NYC. At this time there were approximately 6000-7000 cases reported in Mexico City.
The Scenario makes use of STEMs model for air travel (calibrated against FAA data). The basic scenario was run repeatedly using a range of values for the transmission rate. For each run, we compared the number of people infectious in Mexico city at the time 10 people first appear with H1N1 in NYC. From this work we estimated Ro~1.7
The downloadable project contains this basic model without any expressed policies. The project also contains a second scenario that shows how to set up Modifiers, Predicates, and Triggers. In this case the Modifier changes the transmission rate based on a time trigger.
This downloadable project contains re-useable continent-level models of Earth Science Data including
- temperature and
- vegetation coverage (NDVI)
Please note: You need to access the STEM update site and install the "STEM Earth Science Data for 2010" plugin to use these models. Instructions for adding this and other additional features may be found on the STEM Installation Guide.
The Global Geographic Models project contains no runnable scenarios. Rather, is contains a set of pre-composed models for large regions of the world intended to be built upon in developing your own scenarios. These models, shown int he figure below, include a model for global air transportation, and a set of continent and super-continent models for geographic regions and people. After you download them, please expand them to see the inner components.
The Super-Continent Scenarios provide an examples of how to construct scenarios using the Global Model examples described above. These scenarios show how to model large regions such as the Americas, Europe+Africa, and Europe+Asia. The figure below expands the Eur-Africa Scenario. Note that the Inner Eur-Africa Model contains a model for Europe, a model for Africa, together with the connection between Spain and Morocco.
The Chicken Pox Scenario was created as an attempt to model a disease with lifelong immunity. An Aging Population Model is used to capture the different fractions of immune people for different age groups. Immunity acquired in one age group has an influence on the following age groups, since immune people age into these groups. Seasonal variations are achieved by using a Seasonal Population Model based on Interpolation of Sampling Points. The models are applied to geographic model of France. The following charts show the results for incidence and fraction of immune people for two different age groups.