Difference between revisions of "STEM Model Creator"

From Eclipsepedia

Jump to: navigation, search
(Defining Transitions)
(Creating a new STEM Disease/Population Model Project)
(10 intermediate revisions by one user not shown)
Line 1: Line 1:
 
== About  ==
 
== About  ==
  
The STEM Model Generator was released in STEM V1.4.1 as a ''development environment'' tool to assist in the creation of new models by developers.
+
'''Important Note:  The instructions on this page require STEM 2.0 Milestone 3 or later'''.  
  
  Now, as part of STEM 2.0.0 Milestone 1, we have integrated the Model Generator into the STEM application itself
+
''' 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]]'''
to '''beta test''' ''automated creation of new models'' !!
+
  
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 Generator 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. In the future we plan to make these instructions (and the creation process) even simpler with an improved Graphical User Interface.
+
''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.
  
 +
Beginning with STEM 2.0 Milestone 3, a new visual editor is now included as part of the STEM Model Creator.
 +
 
=== Acknowledgements ===
 
=== Acknowledgements ===
The development of the Model Generator 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  ===
 
=== Installation  ===
# Download and install STEM V2.0.0 Milestone 1 or later [http://www.eclipse.org/stem/downloads.php].
+
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]]
# No other installation is required. The model creator is now a part of STEM itself as of V2.0.0 Milestone 1.
+
  
== Instructions ==
+
== Creating a new STEM Disease/Population Model Project  ==
  
=== Launch the STEM Model Generator Wizard ===
+
''This document is currently being updated for changes in STEM 2.0 Milestone 3. Please check back as we document new features.''
  
'''(this page is still under construction - but the instructions should work :-)'''
 
  
#Open the Eclipse SDK
+
# Launch the STEM application
 
#Open the '''File''' menu, '''New''', and choose '''Other'''  
 
#Open the '''File''' menu, '''New''', and choose '''Other'''  
 
#:''You can also do Control-N (Command-N on Mac OS X)''
 
#:''You can also do Control-N (Command-N on Mac OS X)''
Line 242: Line 241:
 
When you're finished working with compartments, the model is complete. Click '''Finish'''.
 
When you're finished working with compartments, the model is complete. Click '''Finish'''.
  
=== Defining Transitions ===
 
 
This Doc is ''temporary''
 
the instruction for adding transitions will change once the new graphical user interface is complete
 
The dialogue shown was implemented for testing purposed until we are done with the Visual Editor.
 
 
: [[Image:STEM-transition.png|500px]]
 
 
The transitions you specify are used to automatically generate the code defining your model specific differential equations.
 
 
* To add a transition (click the ADD button)
 
* Next Select the two compartments (source and target for the transition) (this is entered in a second dialog that appears after you click "Add")
 
* The equation defining your transition is entered in the text field with a notation that should be easy to understand by any subject matter expert.
 
# start typing in the expression screen.
 
# The expression must always begin with "delta" then a space character
 
# for example: 
 
<font color="red">delta</font>  tranmissionRate*S*I;
 
# after you type delta, at anytime you can type <CTRL><SPACE> to get an "assist" window showing valid options of what you can type to define your equation
 
# '''REMEMBER''' click "'''Apply Changes'''" when you are done with the new transition.
 
# '''REMEMBER''' click "'''Apply Changes'''" when you are done with the new transition.
 
# finally, click "finish"
 
  
<br/>
 
  
 
=== Run the Code Generator ===
 
=== Run the Code Generator ===
Line 284: Line 261:
 
: [[Image:STEM-ModelGen-GenerateOperation.png|500px]]
 
: [[Image:STEM-ModelGen-GenerateOperation.png|500px]]
  
=== Work with your Generated Computational Models ===
+
== Working with your STEM Computational Model ==
 
Once the code generator finishes, the new computational model project will be automatically added to your STEM Workspace.   
 
Once the code generator finishes, the new computational model project will be automatically added to your STEM Workspace.   
 
Follow the instructions for creating any type of STEM Scenario and your new model will appear on the list when you click on the new Disease (or new Population) model dialog.
 
Follow the instructions for creating any type of STEM Scenario and your new model will appear on the list when you click on the new Disease (or new Population) model dialog.

Revision as of 15:49, 18 June 2013

Contents

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

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.

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.

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

This document is currently being updated for changes in STEM 2.0 Milestone 3. Please check back as we document new features.


  1. Launch the STEM application
  2. Open the File menu, New, and choose Other
    You can also do Control-N (Command-N on Mac OS X)
    STEM-ModelGen-NewMenu.png
  3. In the list of Wizards, expand the STEM category and select New STEM Model Project
    STEM-ModelGen-NewProjectWizard2.png
  4. Click Next
  5. Choose Create and configure a new STEM Model Package
    STEM-ModelGen-NewProjectCreatePackage.png
  6. Click Next

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.

STEM-ModelGen-PackagePage-NoModels.png
Parameter Name Data Type Example Value
Package Name String
(Java Identifier)
CattleSalmonellosis
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 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.

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. This will launch the Computational Model Wizard.

Configure Model Properties

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.

STEM-ModelGen-NewModelPage.png
Property Type Example Description
Model Name String
(Java Identifier)
CattleSalmonella 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)

When you're finished, click Next to configure the Model Parameters

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.

STEM-ModelGen-ParamsPage.png

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 light gray italics. 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.

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.

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.  This should be a short, user-friendly description of the parameter.
Data Type Yes EClassifier double The data type of the parameter.  This will be the Java type of the resulting member variable.  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.  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.

STEM-ModelGen-EditConstraintDialog.png

Use the Constraint Editor to select the Constraint Type and enter a Constraint Value. When finished, click OK.

Available Constraints
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
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.

STEM-ModelGen-CompartmentsPage.png

Like Model Parameters, Model Compartments are inherited from the parent model. Compartments inherited from another model are shown in light gray italics 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.

STEM-ModelGen-CompartmentDialog-Standard.png
Property Type Example Description
Compartment Name String (Java identifier) s The name of the compartment.  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  compartment.  This helps determine what kinds of underlying calculations occur.  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

When you're finished working with the computational models in the model package, you're ready to run the code generator.

STEM-ModelGen-PackagePage.png

From the Model Package page, click Next.

On the Generator Options, configure advanced properties for the code generator.

STEM-ModelGen-GeneratorOptionsPage.png
Advanced Generator Options coming soon!

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

Working with your STEM Computational Model

Once the code generator finishes, the new computational model project will be automatically added to your STEM Workspace. Follow the instructions for creating any type of STEM Scenario and your new model will appear on the list when you click on the new Disease (or new Population) model dialog.