Skip to main content
Jump to: navigation, search

Difference between revisions of "STEM Model Creator/Tutorials"

(Enter Rate Equations)
(Create MySEIR Disease)
Line 189: Line 189:
 
#* '''Incubation Rate''':  ''0.5''
 
#* '''Incubation Rate''':  ''0.5''
 
#* '''All others''':  ''defaults''
 
#* '''All others''':  ''defaults''
 +
#: [[Image:STEM VisualEditor SEIRTutorial AddDisease.png|300px]]
 
# Click '''Finish''' to create the new disease
 
# Click '''Finish''' to create the new disease
  

Revision as of 17:11, 21 June 2013

Tutorials

Create a SEIR model by extending SIR

This tutorial shows how to create a new SEIR Disease Model by extending the existing SIR Disease Model. STEM already has a built-in SEIR model, so this tutorial is more a simple how-to.

Create Model Project and Initial Disease Model

  1. Launch the STEM application
  2. Open the Designer perspective
  3. From the New menu, select Model Generator Project
    STEM ModelCreator NewModelGeneratorProject.png
  4. Choose Create and configure a new STEM Model Package
  5. Click Next
  6. On the Model Package page, enter the following values:
    • Package Name: Demo
    • Package Prefix: com.example.diseasemodels
  7. Click Add Model to add the disease model
  8. On the Model Properties page, enter these values:
    • Model Name: MySEIR
    • Model Type: Disease Model
    • Parent Model: Select SIR from the list
  9. Click Finish
  10. At this point, your package properties should look like this:
    STEM VisualEditor SEIRTutorial PackageSettings.png
  11. Click Finish to run the Model Generator and create your model project
    This step may take 1-2 minutes to complete
  12. After the Model Generator finishes, the Visual Editor should automatically open
    STEM VisualEditor SEIRTutorial InitialLayout.png

Add New Compartment

Now that your model project is created, it's time to add new parameters and compartments. First, lets create a new compartment.

We're creating an S-E-I-R model, which is made up of compartments S, E, I, and R. Since we extended the built-in S-I-R model, we need to add a new E compartment.

  1. In the Visual Editor, click the Add Compartment button.
    STEM VisualEditor Toolbar AddCompartment.png
  2. In the Add Compartment dialog, enter the following values
    • Name: e (make sure this is lower case)
    • Compartment Type: Standard
    • Data Type: double
  3. Click Finish
  4. A new e box now appears in the diagram.
  5. You may want to rearrange the shapes so that the S, E, I, and R boxes are in order (easier when connecting the compartments)
    To rearrange, select a compartment and drag it to a new location.
    STEM VisualEditor SEIRTutorial RearrangedLayout.png

That's it. You've added a new compartment to your model. This is now a S-E-I-R model.

Add New Model Parameter

In addition to inheriting compartments from the parent SIR model, the new model also inherits the model (or rate) parameters from SIR. Inherited parameters include Transmission Rate (transmissionRate), Recovery Rate (recoveryRate), Immunity Loss Rate, etc.

We already added the new Exposed state to the disease model. In the textbook SEIR example, the movement from the E to I compartments is called the Incubation Rate. The next step is to add the incubationRate model parameter to the MySEIR model.

  1. In the Visual Editor, click the Edit Model button.
    STEM VisualEditor Toolbar EditModel.png
  2. In the Edit Model dialog, click the Add Parameter button
  3. In the Edit Parameter dialog, enter the following values:
    • Name: incubationRate
    • Display Name: Incubation Rate
    • Data Type: double (default)
    • Default Value: 0.0 (default)
    • Optionally, add a minValue constraint of 0.0
  4. Click OK to add the parameter
    STEM VisualEditor SEIRTutorial EditModel.png
  5. Click OK again to apply the changes

Regenerate the Model Project

Changing a model's parameters or compartments requires a Model Regeneration. This operations rebuilds several of the key Java files that make up the structure of your model project. For more information, see the section on Model Regeneration.

To run the Model Generator:

  1. In the Visual Editor , save the metamodel file
  2. Click the Model Generator button in the Visual Editor Toolbar
    STEM VisualEditor Toolbar ModelGenerator.png
  3. If prompted, save the metamodel file
  4. In the Model Generator wizard, immediately click Finish
  5. Wait while the model is regenerated
    This may take up to a minute to complete

After the Model Generator wizard closes, you're ready to implement the model's transitions and expressions.

Create Transitions and Expressions

You're now ready to move on to the fun part - creating the transitions that describe the movement of a population between various states in the disease model.

Transitions have three key pieces;

  • The Source Compartment
  • The Target Compartment
  • The equation that describes the flow rate out of the source compartment and into the target compartment per time step

With the STEM Visual Editor, you can easily draw the transitions as graph edges between a source and target compartment then use the STEM Expression Editor to enter the rate equation.

Draw Transitions

For this SEIR Model, we will create transitions between these compartments

  • S → E
  • E → I
  • I → R
  • I → diseaseDeaths
  • R → S

To draw transitions:

  1. In the Visual Editor, select the Draw Transition Tool button.
    STEM VisualEditor Toolbar DrawTransition.png
  2. To create the S → E transition:
    • Select the S compartment as the source. Click once on the s compartment box
    • Select the E compartment as the target. Move the mouse to and click once on the e compartment box
  3. You should now see a directed connector between the s and e compartment boxes
    STEM VisualEditor SEIRTutorial AddCompartment.png
  4. Repeat for the other transitions listed above
  5. After you create all five transitions, your diagram should look like this:
    STEM VisualEditor SEIRTutorial AllTransitions.png
Enter Rate Equations

For our SEIR model, the next step is to enter the equations for the five transitions we created in the previous step.

Using the Expression Editor , you can easily enter the equations that represent the state changes in your model as STEM Expressions. For more information, please read about the STEM Expression Language and the Expression Editor.

  1. In the Visual Editor, select the Chooser tool in the toolbar
    STEM VisualEditor Toolbar Chooser.png
  2. Select connector edge between the s and e compartment boxes
  3. In the Expression Editor , enter the equation expression
    Note: The final statement starts with the word delta and end with a semicolon ( ; )
    • For S → E, enter:
      delta transmissionRate*S*effective(i);
    Tip You can use auto-completing expression assistance as you enter your expression. Just type Control - S as you type for the assistance dialog!
    • For S → E, select the box next to incidence under For Incidence
      This tells the STEM simulation engine to count this transition as part of the disease incidence
    STEM VisualEditor SEIRTutorial ExpressionEditor.png
  4. Repeat these steps for the other transitions in the model, entering these expressions for the transition:
Transition Expression Incidences to select
S → E delta transmissionRate*S*effective(i); incidence
E → I delta incubationRate*E; none
I → R delta recoveryRate*I; none
I → diseaseDeaths delta infectiousMortalityRate*I; none
R → S delta immunityLossRate*R; none

Save your Model

That's it! You've now created a simple, textbook S-E-I-R disease model. Before you continue, be sure to Save the model. This will tell STEM to generate the Java code that will back your disease model and install it into the STEM application.

To save the open model in the Visual Editor, either do Control - S ( Command - S on Mac OS X) or open the File menu and select Save.

Prepare STEM Scenario to Run Simulation

You're now ready to try the new SEIR disease model in STEM. At this point, it's helpful to understand how STEM scenarios, models, and simulations work. Please read this guide before continuing.

Download and Import Demo Project & Scenario

As part of this tutorial, we created a simple demo scenario with pre-built scenarios, geographic models, infectors, innoculators, and sequencers. To complete this demo scenario, we'll create a new disease using our MySEIR disease model.

  1. Download the Visual Editor Demo project zip file
  2. In the STEM application, open the File menu and select Import
  3. In the Import Wizard, under General, select Existing projects into Workspace
  4. Click Next
  5. Click the radio button next to Select Archive File
  6. Click Browse and navigate to the location you downloaded ZIP file
  7. Select VisualEditorDemo.zip and click Open
  8. Verify VisualEditorDemo is listed under Projects
  9. Click Finish
    The VisualEditorDemo project should now appear in the Project Explorer
Create MySEIR Disease

Next, we want to create an instance of our new MySEIR disease model.

  1. In STEM, open the New menu and select Disease
    You can also choose the New Disease icon in the toolbar
  2. In the New Disease wizard, make sure VisualEditorDemo is the selected project
  3. For Name, enter SeasonalFlu
  4. From the Disease Model drop-down, choose MySEIR (probably at the bottom of the list)
  5. For Disease Name, enter flu (lower case)
  6. Enter appropriate rate parameter values. For this demo, here are some suggestions:
    • Transmission Rate: 1.2
    • Infectious Recovery Rate: 0.3
    • Immunity Loss Rate: 0.05
    • Incubation Rate: 0.5
    • All others: defaults
    STEM VisualEditor SEIRTutorial AddDisease.png
  7. Click Finish to create the new disease
Add Disease to Geographic Model

Next, we'll add the new Disease to the pre-built geographic model.

  1. In the STEM Project Explorer, expand the VisualEditorDemo project
  2. Expand the Models folder. Double-click on CubaDisease.model
    The CubaDisease.model editor should open
  3. In Project Explorer, expand the Decorators folder
  4. Select My SEIR flu, drag and drop into the CubaDisease.model editor root
  5. Save and Close the CubaDisease.model editor
  6. In Project Explorer, expand the Scenarios folder
Launch the Scenario as a STEM Simulation

You're finally ready to see the results of all the work. You will now launch the pre-built scenario as a STEM simulation and observe the epidemic curve as a time series chart.

  1. Right Click on CubaDisease.scenario and select Step
    This will launch a simulation and open the Simulation perspective
  2. Under the Graph Map, double click on the Cuba polygon to open a Time Series tracker
  3. Under Simulation, click the Run Button [ green arrow image ] to start the simulation
  4. Wait while the simulation runs, watching the Time Series view of the epidemic curve
  5. Your epidemic curve should look like this:
    [ epi curve ]
  6. When the simulation finishes, you can click the Stop [stop button image] button

Summary

You're finished! You've successfully authored a simple, textbook SEIR disease model, created a disease instance in STEM, and run a simple spatiotemporal simulation. Obviously this is not a real-world example, but it's a good introduction to using the STEM Model Creator, Visual Editor, and Expression Language to easily author compartmental models of disease.

In the next tutorial, you will build on this existing model to add more complicated features, such as sinusoidal and temperature forcing to your disease model.


Add seasonal modulation to the SEIR model

Back to the top