Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "STEM Model Creator"

(Working with Compartments)
(Installation)
 
(53 intermediate revisions by 2 users not shown)
Line 5: Line 5:
 
''' Important note:  This document is about the STEM Model Creator, which was first introduced in STEM 2.0.  For the previous version that was used in the Eclipse SDK, see the [[STEM Model Generator]]'''
 
''' Important note:  This document is about the STEM Model Creator, which was first introduced in STEM 2.0.  For the previous version that was used in the Eclipse SDK, see the [[STEM Model Generator]]'''
  
''This document is currently being updated for changes in STEM 2.0 Milestone 3.  Please check back as we document new features.''
 
  
The model creator supports users who want to create a new disease or population model in STEM rather than use an existing model. Setting up the basic structure for a new model can be challenging. This tutorial provides step-by-step instructions for using the STEM Model Creator to design and generate the structure of a new STEM computational (disease/population) model project. Using a simple menu driven interface a user can define a new model (disease or population model) using terminology familiar to any subject matter expert. The model creator will then auto-generate the eclipse plugin and java code defining the model and hot inject it into the user's run time instance of STEM.
+
The model creator supports users who want to create a new disease or population model in STEM rather than use an existing model. Setting up the basic structure for a new model can be challenging. This tutorial provides step-by-step instructions for using the STEM Model Creator to design and generate the structure of a new STEM computational (disease/population) model project. Using a simple menu driven interface a user can define a new model (disease or population model) using terminology familiar to any subject matter expert. The model creator will then auto-generate the Eclipse plugin and Java code defining the model and hot inject it into the user's run time instance of STEM.
  
 
Beginning with STEM 2.0 Milestone 3, a new visual editor is now included as part of the STEM Model Creator.
 
Beginning with STEM 2.0 Milestone 3, a new visual editor is now included as part of the STEM Model Creator.
Line 14: Line 13:
 
The development of the Model Creator tool was sponsored in part by the [http://www.bfr.bund.de German Federal Institute for Risk Assessment (BfR)]. Additional special thanks to Alex Falenski from BfR for assistance creating and editing this document.
 
The development of the Model Creator tool was sponsored in part by the [http://www.bfr.bund.de German Federal Institute for Risk Assessment (BfR)]. Additional special thanks to Alex Falenski from BfR for assistance creating and editing this document.
  
=== Installation ===
+
== Tutorial ==
As of STEM 2.0, this tool is now part of the STEM application.  For more information on installing STEM, see the [[STEM Installation Guide]]
+
  
== Creating a new STEM Disease/Population Model Project  ==
+
[http://www.youtube.com/watch?v=MtQlS7g7Qnw STEM Model Generator] Video Tutorial
  
''This document is currently being updated for changes in STEM 2.0 Milestone 3Please check back as we document new features.''
+
== Installation  ==
 +
As of STEM 2.0, this tool is now part of the STEM applicationFor more information on installing STEM, see the [[STEM Installation Guide]]
  
 +
== Creating a new STEM Disease/Population Model Project  ==
  
 
# Launch the STEM application
 
# Launch the STEM application
Line 27: Line 27:
 
#: [[Image:STEM_ModelCreator_NewModelGeneratorProject.png]]
 
#: [[Image:STEM_ModelCreator_NewModelGeneratorProject.png]]
 
#Choose '''Create and configure a new STEM Model Package'''  
 
#Choose '''Create and configure a new STEM Model Package'''  
#: [[Image:STEM-ModelGen-NewProjectCreatePackage.png|500px]]
 
 
#Click '''Next'''
 
#Click '''Next'''
  
 
=== Configure the Model Package  ===
 
=== Configure the Model Package  ===
  
The model package is the container for all models in a given package. A model package generates an Eclipse plug-in project.<br>
+
The model package is the container for all disease models in a given Model Generator project.
  
: [[Image:STEM-ModelGen-PackagePage-NoModels.png|400px]]
+
: [[Image:STEM_ModelCreator_ModelPackage.png|400px]]
  
 
:{| cellspacing="0" cellpadding="5" border="1"
 
:{| cellspacing="0" cellpadding="5" border="1"
Line 44: Line 43:
 
| Package Name
 
| Package Name
 
| String<br />(Java Identifier)
 
| String<br />(Java Identifier)
| CattleSalmonellosis
+
| Demo
 
|-
 
|-
 
| Package Prefix
 
| Package Prefix
Line 51: Line 50:
 
|}
 
|}
  
The '''Package Name''' and '''Package Prefix''' are combined to create the resulting Eclipse plug-in/project identifier.  For example, the model package with values above will generate an Eclipse plug-in/project with ID '''com.example.diseasemodels.cattlesalmonellosis'''. This plug-in, once automatically generated, will be added to your STEM runtime (while it is running). Later we will explain how you can also send this plug-in to colleagues you wish to share it with.
+
The '''Package Name''' and '''Package Prefix''' are combined to create the resulting Eclipse plug-in/project identifier.  For example, the model package with name and prefix above will generate an Eclipse plug-in/project with ID '''com.example.diseasemodels.demo'''. This plug-in, once automatically generated, will be added to your STEM runtime (while it is running). Later we will explain how you can also send this plug-in to colleagues you wish to share it with.
  
 
=== Add/Edit a Computational Model  ===
 
=== Add/Edit a Computational Model  ===
When you're ready to add a computational model to the package, from the '''Model Package''' page, click '''Add Model'''. To edit an existing computational model, select it in the '''Contained Models''' list and click '''Edit Model'''.
+
Before the Model Generator can generate the project, you must add at least one computational (disease) model. To begin, click '''Add Model'''. This will launch the '''New Model Wizard'''.
This will launch the '''Computational Model Wizard'''.
+
  
==== Configure Model Properties  ====
+
To configure the model, enter values for the model's name, the model's type, and which parent model it extends and inherits parameters and compartments from.  '''All fields are required'''.
Model properties are the most basic settings of a STEM Computational Model.  Properties include the model's name, the model's type, and which parent model it extends and inherits parameters and compartments from.  '''All are required'''.
+
  
:[[Image:STEM-ModelGen-NewModelPage.png|500px]]
+
:[[Image:STEM_ModelCreator_NewModel.png|500px]]
  
 
:{| cellspacing="0" cellpadding="5" border="1"
 
:{| cellspacing="0" cellpadding="5" border="1"
Line 71: Line 68:
 
| Model Name  
 
| Model Name  
 
| String<br>(Java Identifier)  
 
| String<br>(Java Identifier)  
| CattleSalmonella
+
| MySEIR
 
| The model's name.&nbsp; This value will be the Java class name of the generated model. ''Should contain alphanumeric characters, no spaces, and cannot begin with a number.''
 
| The model's name.&nbsp; This value will be the Java class name of the generated model. ''Should contain alphanumeric characters, no spaces, and cannot begin with a number.''
 
|-
 
|-
Line 85: Line 82:
 
|}
 
|}
  
When you're finished, click '''Next''' to configure the '''Model Parameters'''
+
These are the minimum settings required for a computational model.  At this point, you can click '''Finish''' to add the model.  To add model parameters and compartments, you can either click '''Next''' and use this form or later edit them from the Visual Editor.
 
+
==== Configure Model Parameters  ====
+
 
+
Model parameters - also called rate parameters - represent user-defined variables that are passed into the computational model. The values can represent many things, but are often variables to the differential equations that make up the model. Users are asked to provide values for these parameters when a new Disease/Population/etc is created in STEM. Examples include '''Transmission Rate''', '''Immunity Loss Rate''', etc.
+
 
+
:[[Image:STEM-ModelGen-ParamsPage.png|500px]]
+
 
+
By default, a model inherits parameters from its ancestor models (which might be a model you already created using these instructions). These are shown in <span style="color: #a0a0a0; font-style:italic;">light gray italics</span>. '''You cannot edit or remove parameters inherited from another model.''' So, if you don't want to use a parameter on the list, start with a higher level model. The most generic Disease Model has one state 'S' for susceptible and no parameters at all.   
+
 
+
To add a ''new'' model parameter, click '''Add Parameter'''. To edit an existing parameter, select one from the list and click '''Edit Parameter'''.
+
 
+
:[[Image:STEM-ModelGen-ParamDialog.png]]
+
 
+
When you click '''Add''' or '''Edit Parameter''', the '''Model Parameter Editor''' window opens. Use the form provided to set the properties for the model parameter.  
+
 
+
:{| cellspacing="0" cellpadding="1" border="1"
+
|-
+
| '''Property '''
+
| '''Required?'''
+
| '''Type'''
+
| '''Example'''
+
| '''Description'''
+
|-
+
| Name
+
| '''Yes'''
+
| String (Java Identifier)
+
| transmissionRate2
+
| The parameter's name. This is the name of the Java member variable in the resulting computational model. ''This required property is a Java identifier and should contain alphanumeric characters, no spaces, and cannot begin with a number.''
+
|-
+
| Display Name
+
| '''Yes'''
+
| String
+
| Transmission Rate 2
+
| The display name of the parameter.&nbsp; This should be a short, user-friendly description of the parameter.
+
|-
+
| Data Type
+
| '''Yes'''
+
| EClassifier
+
| double
+
| The data type of the parameter.&nbsp; This will be the Java type of the resulting member variable.&nbsp; '' '''Tip''': For models with multiple populations, select a '''ValueList''' or '''ValueMatrix''' data type.''
+
|-
+
| Default Value
+
| '''Yes'''**
+
| Type-specific
+
| 0.0
+
| The default value of the parameter if a value is not provided by the user.&nbsp; A default value often accompanies the parameter in literature. ''**This field is required for numeric data types (like double, integer, float, etc)''.
+
|-
+
| Constraints
+
| No
+
| Constraint
+
| minValue
+
| Parameter constraints are used to restrict the allowed parameter values. See below for more details about Parameter Constraints.
+
|-
+
| Units
+
| No
+
| String
+
| PM/TP
+
| User interface message that explains what units are expected for this parameter
+
|-
+
| Help Message
+
| No
+
| String
+
|
+
| User interface message that further explains the purpose or other details about this parameter.
+
|-
+
| Missing Message
+
| No
+
| String
+
|
+
| User interface message that displays when no value is entered for this parameter.
+
|-
+
| Invalid Message
+
| No
+
| String
+
|
+
| User interface message that displays when an invalid value (e.g. violates the constraints) is entered for this parameter.
+
|}
+
 
+
===== Parameter Constraints =====
+
 
+
Parameter constraints are used to restrict the allowed values for a model parameter. A parameter can have multiple constraints. Each constraint is evaluated independently and must be fulfilled for a value to be accepted.
+
 
+
: '''''Note''':  You can add multiple constraints of the same type.  However, for certain constraint types, this may not make sense and may cause a value to never be valid.  For example, it does not make sense to create two '''minValue''' constraints.''
+
 
+
To add a new constraint, click '''Add'''. To edit an existing constraint, select one from the constraint list and click '''Edit'''.
+
 
+
:[[Image:STEM-ModelGen-EditConstraintDialog.png]]
+
 
+
Use the Constraint Editor to select the '''Constraint Type''' and enter a '''Constraint Value'''.  When finished, click '''OK'''.
+
 
+
:'''Available Constraints'''
+
:{| cellpadding="5" cellspacing="0" border="1"
+
|-
+
| '''Constraint Type'''
+
| '''Example Constraint Value'''
+
| '''Description'''
+
|-
+
| minValue
+
| 0.0
+
| The minimum numeric value allowed for the parameter
+
|-
+
| maxValue
+
| 1.0
+
| The maximum numeric value allowed for the parameter
+
|-
+
| colspan="3" | ''More constraint types coming soon...''
+
|}
+
 
+
When you're finished working with '''Model Parameters''', click '''Next''' to configure '''Model Compartments'''.
+
 
+
==== Configure Model Compartments  ====
+
 
+
Model compartments are the second type of variable in the computational model and represent the various groupings within the model lifecycle. Unlike Model Parameters, however, these values are not defined by the user, but instead are calculated as the output from the model's differential equations. For more information, please read the [[Introduction to Compartment Models|Introduction to Compartment Models]].
+
 
+
:[[Image:STEM-ModelGen-CompartmentsPage.png|500px]]
+
 
+
Like Model Parameters, Model Compartments are inherited from the parent model. Compartments inherited from another model are shown in <span style="color: #a0a0a0; font-style:italic;">light gray italics</span> and '''cannot be edited or removed'''. ''If the compartments from your parent model do not closely match the compartment model you're implementing, you can elect to choose a different model to inherit compartments from.''
+
 
+
:'''''Note:''' Just because a compartment does not match the compartment name in literature does not mean it's not logically the same or can't be reused. Consider this before deciding not to use an inherited compartment.''
+
 
+
To add a new compartment, click '''Add Compartment'''. To edit an existing compartment, select it from the list and click '''Edit Compartment'''.
+
 
+
Use the Compartment Editor dialog to edit the compartment's properties. '''All properties are required.'''. When finished editing the compartment, click '''OK'''.
+
 
+
:[[Image:STEM-ModelGen-CompartmentDialog-Standard.png]]
+
 
+
:{| cellspacing="0" cellpadding="5" border="1"
+
|-
+
| '''Property'''
+
| '''Type'''
+
| '''Example'''
+
| '''Description'''
+
|-
+
| Compartment Name
+
| String (Java identifier)
+
| s
+
| The name of the compartment.&nbsp; This is also the name of the resulting Java member variable. It should contain alphanumeric characters, no spaces, and cannot begin with a number.
+
|-
+
| Compartment Type
+
| String
+
| Standard
+
| The property of values stored in the&nbsp; compartment.&nbsp; This helps determine what kinds of underlying calculations occur.&nbsp; Example types are ''Standard'', ''Incidence'', and ''Deaths''.
+
|-
+
| Data Type
+
| EClassifier
+
| double
+
| The data type of the compartment. Currently only valid type is ''double''.
+
|}
+
 
+
 
+
When you're finished working with compartments, the model is complete. Click '''Finish'''.
+
 
+
 
+
  
 
=== Run the Code Generator ===
 
=== Run the Code Generator ===
When you're finished working with the computational models in the model package, you're ready to run the code generator.
+
When you've added a model to this project, you're ready to run the code generator.
  
: [[Image:STEM-ModelGen-PackagePage.png|500px]]
+
: [[Image:STEM_VisualEditor_RunGenerator.png|500px]]
  
 
From the Model Package page, click '''Next'''.
 
From the Model Package page, click '''Next'''.
 
On the '''Generator Options''', configure advanced properties for the code generator.
 
 
: [[Image:STEM-ModelGen-GeneratorOptionsPage.png|500px]]
 
: ''Advanced Generator Options coming soon!''
 
  
 
When finished, click '''Finish'''.
 
When finished, click '''Finish'''.
Line 258: Line 97:
 
: [[Image:STEM-ModelGen-GenerateOperation.png|500px]]
 
: [[Image:STEM-ModelGen-GenerateOperation.png|500px]]
  
 
+
After the initial Model Generation completes, your new model will open in the Visual Model Editor.  You're now ready to begin defining the compartments and transitions that describe your compartment model.  See the next section for more information.
After the initial Model Generation completes, your new model will open in the Visual Model Editor.  You're now ready to begin defining the state transitions that describe your compartment model.  See the next section for more information.
+
  
 
== Working with your STEM Computational Model ==
 
== Working with your STEM Computational Model ==
Line 265: Line 103:
 
=== The Visual Model Editor ===
 
=== The Visual Model Editor ===
  
The STEM Visual Model editor is a new tool to scientists to describe the structure - and mathematics - behind their computational model in an easy to use graphical user interface.
+
The STEM Visual Model Editor is a new tool that allows scientists to describe the structure - and mathematics - behind their computational model in an easy to use graphical user interface.
 
+
 
+
  
 
=== Getting Started With the Visual Model Editor ===
 
=== Getting Started With the Visual Model Editor ===
  
The Visual Model editor is a tool for visual designing compartment models. With the Visual Editor, a scientist can arrange the compartments in their model, draw transitions that describe the state transitions between compartments, insert the equations, and immediately run STEM simulations - without needing to restart.
+
The Visual Model Editor is a tool for visual designing compartment models. With the Visual Editor, you can arrange the compartments in your model, draw transitions that describe the state transitions between compartments, insert the equations, and immediately run STEM simulations - without needing to restart.
  
 
[[Image:STEM VisualEditor.png]]
 
[[Image:STEM VisualEditor.png]]
  
The Visual Editor currently supports these types of operations:
+
The Visual Editor currently supports the following types of operations:
  
 
* Adding new disease/population models to a metamodel
 
* Adding new disease/population models to a metamodel
Line 323: Line 159:
 
: [[Image:STEM VisualEditor Toolbar EditModel.png]]
 
: [[Image:STEM VisualEditor Toolbar EditModel.png]]
  
This will launch the ''' Edit Model ''' dialog.  For help editing Model Parameters, see the section on [[#Configure_Model_Parameters|Configure Model Parameters]] section.
+
This will launch the ''' Edit Model ''' dialog.  For help editing Model Parameters, see the [[STEM_Model_Creator/New_Model_Project#Configure_Model_Parameters|Configure Model Parameters]] section.
  
 
: [[Image:STEM_VisualEditor_EditModel.png|500px]]
 
: [[Image:STEM_VisualEditor_EditModel.png|500px]]
Line 336: Line 172:
 
=== Working with Compartments ===
 
=== Working with Compartments ===
 
==== Add a Compartment ====
 
==== Add a Compartment ====
''' <span style="color:red;">Any changes during this operation require a model regeneration </span> '''
+
''' <span style="color:red;">Changes during this operation require a [[#Model_Regeneration|model regeneration]] </span> '''
  
 
To add a new compartment to a model, click the ''' Add Compartment ''' button in the toolbar
 
To add a new compartment to a model, click the ''' Add Compartment ''' button in the toolbar
Line 342: Line 178:
 
: [[Image:STEM_VisualEditor_Toolbar_AddCompartment.png]]
 
: [[Image:STEM_VisualEditor_Toolbar_AddCompartment.png]]
  
This will launch the add compartment dialog.  Enter a ''' Name ''' and select a '''Compartment Type '''.
+
This will launch the add compartment dialog.  Enter a ''' Name ''' and select a '''Compartment Type '''
  
 
: [[Image:STEM_VisualEditor_AddCompartment.png]]
 
: [[Image:STEM_VisualEditor_AddCompartment.png]]
Line 348: Line 184:
 
When finished, click ''' OK '''.  To discard your changes, click ''' Cancel '''
 
When finished, click ''' OK '''.  To discard your changes, click ''' Cancel '''
  
''After completing this operation, be sure to re-run the Model Generator.''
+
''After completing this operation, be sure to re-run the [[#Model_Regeneration|Model Generator]]''
  
 
==== Edit a Compartment ====
 
==== Edit a Compartment ====
 
''' <span style="color:red;">This operation requires a model regeneration </span> '''
 
''' <span style="color:red;">This operation requires a model regeneration </span> '''
  
''' You can only edit compartments that owned by the current model.  ''' Inherited compartments are indicated with a lock icon in the box.
+
''' You can only edit compartments that owned by the current model.  ''' Inherited compartments are indicated with a lock icon in the box
  
 
: [[Image:STEM_VisualEditor_CompartmentComparison.png]]
 
: [[Image:STEM_VisualEditor_CompartmentComparison.png]]
  
To edit an existing compartment contained in a model, select the Chooser tool in the Toolbar.
+
To edit an existing compartment contained in a model, select the '''Chooser''' tool in the Toolbar
  
 
: [[Image:STEM_VisualEditor_Toolbar_Chooser.png]]
 
: [[Image:STEM_VisualEditor_Toolbar_Chooser.png]]
  
Select the model to edit in the editor and '''double click'''.  This will open the '''Edit Compartment''' dialog.
+
Select the compartment to edit and '''double click'''.  This will open the '''Edit Compartment''' dialog
  
 
: [[Image:STEM_VisualEditor_EditCompartment.png]]
 
: [[Image:STEM_VisualEditor_EditCompartment.png]]
Line 367: Line 203:
 
When finished, click ''' OK '''.  To discard your changes, click ''' Cancel '''
 
When finished, click ''' OK '''.  To discard your changes, click ''' Cancel '''
  
''After completing this operation, be sure to re-run the Model Generator.''
+
''After completing this operation, be sure to re-run the Model Generator''
  
 
==== Remove a Compartment ====
 
==== Remove a Compartment ====
Line 373: Line 209:
  
 
=== Working with Transitions ===
 
=== Working with Transitions ===
==== Create a new transition between two compartments ====
+
==== Create a New Transition between Two Compartments ====
 +
''' <span style="color:green;">This operation does NOT require a model regeneration </span> '''
  
==== Delete a transition ====
+
Transitions between compartments represent the movement of population from one state to another during a STEM simulation.  Each transition is described by an expression - or equation - that describes the flow out of the source compartment and into the target compartment.  For more information about the expressions, see the [[#Expression Editor|Expression Editor]] section.
  
=== Expression Editor ===
+
Transitions can be drawn between the following source and target compartment type pairs:
 +
 
 +
* '''Standard''' Compartment to '''Standard''' Compartment
 +
* '''Standard''' Compartment to '''Disease Deaths''' Compartment
 +
 
 +
To create a new transition, begin by selecting the '''Draw Transition''' tool from the toolbar
 +
: [[Image:STEM VisualEditor Toolbar DrawTransition.png]]
 +
 
 +
Select the source compartment by '''clicking once on the compartment''' (must be type '''Standard''')
 +
: [[Image:STEM_VisualEditor_DrawingTransition.png]]
 +
 
 +
After the source is selected, move the mouse and '''click once on the target compartment''' 
 +
: [[Image:STEM VisualEditor DrawTransition.png]]
 +
 
 +
A transition should now be drawn that connects the compartments
 +
 
 +
You can now select the transition and edit the expression that describes the equation in the '''[[STEM Expression Language#Expression Editor|Expression Editor]]'''.
 +
 
 +
==== Remove a Transition ====
 +
''' <span style="color:green;">This operation does NOT require a model regeneration </span> '''
 +
 
 +
To remove a transition, select the '''Chooser''' tool in the toolbar
 +
: [[Image:STEM_VisualEditor_Toolbar_Chooser.png]]
 +
 
 +
Select the transition you want to remove.  '''Right click on the transition''' and select '''Delete'''
 +
: [[Image:STEM VisualEditor RemoveTransition.png]]
 +
 
 +
==== Edit Expressions ====
 +
: ''See main article: '''[[STEM Expression Language]]''' ''
 +
''' <span style="color:green;">This operation does NOT require a model regeneration </span> '''
 +
 
 +
The Expression Editor allows you to input the mathematical expressions that define the transitions between model compartments using the '''[[STEM Expression Language]]'''.  For more information about the expression editor, see the '''[[STEM Expression Language#Expression Editor|Expression Editor article]]'''.
  
 
=== Model Regeneration ===
 
=== Model Regeneration ===
 +
Certain operations that change the "structure" of a computational model require a "Model Regeneration".  This is a non-invasive operation that rebuilds several of the key Java files that make up a computational model project.  It does not change the Java code associated with your expressions or change the project's metamodel in any way.
 +
 +
Operations that require a regeneration are:
 +
* Add a new model
 +
* Add, edit, remove model parameters
 +
* Add, edit, remove model compartments
 +
 +
To run the model regenerator, follow these steps:
 +
 +
# Open the project's metamodel in the Visual Editor
 +
# Make sure any changes are saved '''File, Save''' or '''Control-S''' (Command-S on Mac OS X)
 +
# Click the ''' Model Generator ''' icon in the Visual Editor toolbar
 +
#: [[Image:STEM_VisualEditor_Toolbar_ModelGenerator.png]]
 +
# When the Model Generator wizard opens, immediately click ''' Finish '''
 +
#: [[Image:STEM_VisualEditor_RunGenerator.png|300px]]
 +
# '' Wait while the model generator runs.  This step may take a minute to complete ''
 +
# When the Model Generator closes, you're ready to begin using your model in STEM

Latest revision as of 17:15, 3 September 2019

About

Important Note: The instructions on this page require STEM 2.0 Milestone 3 or later.

Important note: This document is about the STEM Model Creator, which was first introduced in STEM 2.0. For the previous version that was used in the Eclipse SDK, see the STEM Model Generator


The model creator supports users who want to create a new disease or population model in STEM rather than use an existing model. Setting up the basic structure for a new model can be challenging. This tutorial provides step-by-step instructions for using the STEM Model Creator to design and generate the structure of a new STEM computational (disease/population) model project. Using a simple menu driven interface a user can define a new model (disease or population model) using terminology familiar to any subject matter expert. The model creator will then auto-generate the Eclipse plugin and Java code defining the model and hot inject it into the user's run time instance of STEM.

Beginning with STEM 2.0 Milestone 3, a new visual editor is now included as part of the STEM Model Creator.

Acknowledgements

The development of the Model Creator tool was sponsored in part by the German Federal Institute for Risk Assessment (BfR). Additional special thanks to Alex Falenski from BfR for assistance creating and editing this document.

Tutorial

STEM Model Generator Video Tutorial

Installation

As of STEM 2.0, this tool is now part of the STEM application. For more information on installing STEM, see the STEM Installation Guide

Creating a new STEM Disease/Population Model Project

  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

Configure the Model Package

The model package is the container for all disease models in a given Model Generator project.

STEM ModelCreator ModelPackage.png
Parameter Name Data Type Example Value
Package Name String
(Java Identifier)
Demo
Package Prefix String
(Java Package Identifier)
com.example.diseasemodels

The Package Name and Package Prefix are combined to create the resulting Eclipse plug-in/project identifier. For example, the model package with name and prefix above will generate an Eclipse plug-in/project with ID com.example.diseasemodels.demo. This plug-in, once automatically generated, will be added to your STEM runtime (while it is running). Later we will explain how you can also send this plug-in to colleagues you wish to share it with.

Add/Edit a Computational Model

Before the Model Generator can generate the project, you must add at least one computational (disease) model. To begin, click Add Model. This will launch the New Model Wizard.

To configure the model, enter values for the model's name, the model's type, and which parent model it extends and inherits parameters and compartments from. All fields are required.

STEM ModelCreator NewModel.png
Property Type Example Description
Model Name String
(Java Identifier)
MySEIR The model's name.  This value will be the Java class name of the generated model. Should contain alphanumeric characters, no spaces, and cannot begin with a number.
Model Type String from list DiseaseModel The underlying model type. If you're implementing a Disease Model, select DiseaseModel. A Population Model, select PopulationModel. This value is used to find appropriate parent models.
Parent model Computational Model SIR The computational model this new model will extend. If you're not sure, select the textbook model that most closely resembles the compartment model you're implementing (SI, SIR, SEIR)

These are the minimum settings required for a computational model. At this point, you can click Finish to add the model. To add model parameters and compartments, you can either click Next and use this form or later edit them from the Visual Editor.

Run the Code Generator

When you've added a model to this project, you're ready to run the code generator.

STEM VisualEditor RunGenerator.png

From the Model Package page, click Next.

When finished, click Finish.

If no errors are found, the code generator will now run. This process may take 1-2 minutes.

STEM-ModelGen-GenerateOperation.png

After the initial Model Generation completes, your new model will open in the Visual Model Editor. You're now ready to begin defining the compartments and transitions that describe your compartment model. See the next section for more information.

Working with your STEM Computational Model

The Visual Model Editor

The STEM Visual Model Editor is a new tool that allows scientists to describe the structure - and mathematics - behind their computational model in an easy to use graphical user interface.

Getting Started With the Visual Model Editor

The Visual Model Editor is a tool for visual designing compartment models. With the Visual Editor, you can arrange the compartments in your model, draw transitions that describe the state transitions between compartments, insert the equations, and immediately run STEM simulations - without needing to restart.

STEM VisualEditor.png

The Visual Editor currently supports the following types of operations:

  • Adding new disease/population models to a metamodel
  • Adding, editing, and removing model parameters from a model
  • Adding, editing, and removing compartments from a model
  • Adding and removing compartment transitions
  • Expression editor for authoring the equations that describe the state transition between two compartments, including equation assistance and data access functions for accessing denominator data
  • Automatic translation of expressions into Java code, compilation, and installation into STEM - without needing to restart!

Opening a Project's Metamodel in the Model Editor

If you have just created a new model project, the Visual Model Editor should open automatically after the project is created.

To edit an existing model project, simply open the project's metamodel in the Visual Model Editor

  1. Open the STEM Designer perspective
  2. Navigate to the project in the Project Explorer window
  3. Expand the model folder
  4. Select and double click on the [projectname].metamodel file
    STEM VisualEditor MetamodelSelect.png
  5. The Visual Model Editor should open automatically

Working with Models

The Visual Model Editor supports multiple models in the same metamodel. To pick the model to work with, choose from the Model dropdown in the editor toolbar

STEM VisualEditor Toolbar SelectModel.png

Add a New Model

This operation requires a model regeneration

To add a new disease/population model to an existing metamodel, click the Add Model button in the Visual Editor toolbar.

STEM VisualEditor Toolbar AddModel.png

This will launch the Add Model wizard. For help with the Add Model wizard, see this section.

After completing this step, be sure to re-run the Model Generator.

Change Model Parameters

This operation requires a model regeneration

This feature is a work in progress and is subject to UI changes

Once a computational model is created, users can edit a model's parameters. This includes adding new parameters plus editing and removing existing parameters.

Important: if you edit or remove a parameter, be sure to update all references to that parameter from your transition expressions. The model editor currently does not support this automatically.
STEM VisualEditor Toolbar EditModel.png

This will launch the Edit Model dialog. For help editing Model Parameters, see the Configure Model Parameters section.

STEM VisualEditor EditModel.png

When finished, click OK to apply your changes or Cancel to discard changes.

After completing this operation, be sure to re-run the Model Generator.

Remove a Model

Currently not supported

Working with Compartments

Add a Compartment

Changes during this operation require a model regeneration

To add a new compartment to a model, click the Add Compartment button in the toolbar

STEM VisualEditor Toolbar AddCompartment.png

This will launch the add compartment dialog. Enter a Name and select a Compartment Type

STEM VisualEditor AddCompartment.png

When finished, click OK . To discard your changes, click Cancel

After completing this operation, be sure to re-run the Model Generator

Edit a Compartment

This operation requires a model regeneration

You can only edit compartments that owned by the current model. Inherited compartments are indicated with a lock icon in the box

STEM VisualEditor CompartmentComparison.png

To edit an existing compartment contained in a model, select the Chooser tool in the Toolbar

STEM VisualEditor Toolbar Chooser.png

Select the compartment to edit and double click. This will open the Edit Compartment dialog

STEM VisualEditor EditCompartment.png

When finished, click OK . To discard your changes, click Cancel

After completing this operation, be sure to re-run the Model Generator

Remove a Compartment

Currently not supported

Working with Transitions

Create a New Transition between Two Compartments

This operation does NOT require a model regeneration

Transitions between compartments represent the movement of population from one state to another during a STEM simulation. Each transition is described by an expression - or equation - that describes the flow out of the source compartment and into the target compartment. For more information about the expressions, see the Expression Editor section.

Transitions can be drawn between the following source and target compartment type pairs:

  • Standard Compartment to Standard Compartment
  • Standard Compartment to Disease Deaths Compartment

To create a new transition, begin by selecting the Draw Transition tool from the toolbar

STEM VisualEditor Toolbar DrawTransition.png

Select the source compartment by clicking once on the compartment (must be type Standard)

STEM VisualEditor DrawingTransition.png

After the source is selected, move the mouse and click once on the target compartment

STEM VisualEditor DrawTransition.png

A transition should now be drawn that connects the compartments

You can now select the transition and edit the expression that describes the equation in the Expression Editor.

Remove a Transition

This operation does NOT require a model regeneration

To remove a transition, select the Chooser tool in the toolbar

STEM VisualEditor Toolbar Chooser.png

Select the transition you want to remove. Right click on the transition and select Delete

STEM VisualEditor RemoveTransition.png

Edit Expressions

See main article: STEM Expression Language

This operation does NOT require a model regeneration

The Expression Editor allows you to input the mathematical expressions that define the transitions between model compartments using the STEM Expression Language. For more information about the expression editor, see the Expression Editor article.

Model Regeneration

Certain operations that change the "structure" of a computational model require a "Model Regeneration". This is a non-invasive operation that rebuilds several of the key Java files that make up a computational model project. It does not change the Java code associated with your expressions or change the project's metamodel in any way.

Operations that require a regeneration are:

  • Add a new model
  • Add, edit, remove model parameters
  • Add, edit, remove model compartments

To run the model regenerator, follow these steps:

  1. Open the project's metamodel in the Visual Editor
  2. Make sure any changes are saved File, Save or Control-S (Command-S on Mac OS X)
  3. Click the Model Generator icon in the Visual Editor toolbar
    STEM VisualEditor Toolbar ModelGenerator.png
  4. When the Model Generator wizard opens, immediately click Finish
    STEM VisualEditor RunGenerator.png
  5. Wait while the model generator runs. This step may take a minute to complete
  6. When the Model Generator closes, you're ready to begin using your model in STEM

Back to the top