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

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.

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.

Launch the STEM application

Open the Designer perspective

From the New menu, select Model Generator Project

Choose Create and configure a new STEM Model Package

Click Next

Configure the Model Package

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

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.

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.

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.

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.

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

Open the STEM Designer perspective

Navigate to the project in the Project Explorer window

Expand the model folder

Select and double click on the [projectname].metamodel file

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

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.

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.

Edit a Compartment

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

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

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

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

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

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

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

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

Edit Expressions

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:

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

When the Model Generator wizard opens, immediately click Finish

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