JigCell Model Builder User's Manual

The JigCell Model Builder (JCMB) aides the modeler in defining a system to be modeled using SBML. JCMB uses a spreadsheet interface, allowing a large amount of data to be displayed in an organized manner. In addition to allowing the modeler to define chemical species, equations, and relationships, JCMB also provides the ability to define events that occur when a user-defined condition is met. The models created with JCMB can be used in conjunction with the other JigCell tools to simulate the behavior of the model, and to evaluate the ability of the model to match the phenomena the model is meant to represent.

See how JCMB is used in the modeling lifecycle here

Please report any bugs you have found in JigCell software here

Using JigCell Model Builder

JCMB Manual - Table of Contents
1 - Overview 2 - Interface Components 3 - JCMB Menu Bar
4 - JCMB Spreadsheets 4.1 - Reactions Spreadsheet 4.1.1 - Parameters/Modifiers Editor
4.2 - Functions Spreadsheet 4.3 - Rules Spreadsheet 4.4 - Compartments Spreadsheet
4.5 - Species Spreadsheet 4.6 - Parameters Spreadsheet 4.7 - Events Spreadsheet
4.7.1 - Events Assignment Editor 4.8 - Units Spreadsheet 4.8.1 - Units Editor
4.9 - Conservation Relations Spreadsheet 4.10 - Equations Spreadsheet

1 - Overview
The JCMB allows the user to define a regulatory network model using a spreadsheet interface. The JCMB provides a number of functionalities for both a first-time user and an expert modeler. The first of these is the ability to define all the necessary components of a regulatory network model. JCMB allows the user to specify the reaction equations, functions, rate laws, and conservation relations that define a complete model. In addition, JCMB also allows the modeler to specify units and events. An event, such as cellular division, can be defined by specifying a condition that must be met to trigger the event, and the changes that result due to the event. A major goal of JCMB is to minimize the time and errors associated with translating a wiring diagram for a regulatory network to a set of equations. JCMB accomplishes this through its spreadsheet interface. As the user enters reaction equations, rate laws, and functions into their respective spreadsheets, several other spreadsheets are updated to track the species, paramaters, equations (ODEs and rule equations), and conservation relations associated with the model. After the user has finished defining a model using JCMB, this model can be used with the other JigCell tools to simulate the response of the model to given conditions.

The JigCell Model Builder uses SBML Level 2 to define a model based on the data the user provides. There are 10 different spreadsheets for model data, each spreadsheet is associated with a particular tab. There are 8 tabs for the different SBML components in a model (reactions, functions, rules, compartments, species, parameters, units and events). There is 1 tab for the Conservation Relations that exist in a model, and 1 tab for the equations, both ODEs and rule equations.

Spreadsheet Interface
Figure 1. JCMB on startup showing the Reactions tab.

2 - Major Interface Components

Upon startup, the user will see a screen similar to Figure 1. There are two major components to the main JCMB screen. The menu bar at the top of the screen, and the tabbed bar below it. Each tab corresponds to a different spreadsheet based on its name. For example the Compartments tab contains a spreadsheet for editing the list of compartments in an SBML model. The first tab will hold the reaction equations spreadsheet. The user can also access other spreadsheets by clicking on the various tabs, such as: Functions, Rules, Compartments, Species, Parameters, Events, Units, Conservation Relations, amd Equations.

3 - JCMB Menu Bar
JCMB provides a standard menu bar that allows the user to perform basic file management tasks, edit properties of the JCMB interface, and get help if needed. The menu bar contains three menus.

4 - JCMB Spreadsheets
JCMB uses a series of spreadsheets to organize the model. The modeler will focus primarily on the Reactions spreadsheet to define the reaction network of the model. The other spreadsheets are either partially or completely filled by JCMB as a means of reducing errors. Each JCMB spreadsheet is described in its own section.

4.1 - Reactions Spreadsheet
The Reactions spreadsheet is the primary tool used to create the reaction network of a model. A reaction represents any transformation, transport or binding process such as a chemical reaction that can change the amount of one or more species. Each row allows the modeler to define a single chemical reaction. Figure 2 shows the Reactions tab loaded with the frogegg model.

Reactions Tab
Figure 2. A Frogegg Model as entered in JCMB's Reaction tab.
There are six columns in the Reactions spreadsheet:

4.1.1 - Parameters/Modifiers Editor
The Parameters/Modifiers Editor displays the unsubstitued rate equation, which was specified when the user selected the reaction type in the Reactions spreadsheet. There is a small spreadsheet below the unsubstituted with the following columns:

The Parameters/Modifiers Editor allows the user to specify the kinetics of a reaction by editing the Parameters/Modifiers field, by specifying a list of parameters, modifiers or constants associated with the rate law. JCMB requires the user to enter a value for each row in the the Parameters/Modifiers column in order to generate a valid kinetic law. The values entered for these parameters can be numeric constants, expressions, species and species related expressions.

Parameters/Modifiers Editor
Figure 3. Parameters/Modifiers Editor of the first reaction (MPF inactivation) in the Reactions tab (Figure 2).

4.2 - Functions Spreadsheet
The functions spreadsheet (see Figure 4) is used to edit and create functions definitions in the model. A function definition is a named mathematical function taht may be used throughout the rest of a model. The functions spreadsheet allows the modeler to define a mathematical function for use in the model. This can be particular useful when a complex function is used repeatedly in a model. Certain functions, such as Goldbeter-Koshland, require a significant amount of effort to enter correctly. By defining this function only once and then using it whenever needed many problems can be avoided.

Function Tab
Figure 4. JCMB Functions tab.
There are four columns in the Functions spreadsheet:

4.3 - Rules Spreadsheet
The Rules spreadsheet (see Figure 5) is used to edit and create assignment rules in the model. Rules provide a way to create constraints on variables for cases in which the constraints cannot be expressed using reactions, or the assignment of an initial value to a component in a model. JCMB supports two types of rules: Assignment and Algrebraic. The user is able to create and modify Assignment rules using the Rules spreadsheet. An Assignment row row can be used for two purposes. The first is to define a species that is present in the model but is not involved in the chemical reactions of the model. The second is to allow the modeler to define an intermediate value that can be used in computations. Algebraic rules cannot be created by the user as they are used to describe conservation relations in the model and are detected and created automatically. However using the Conservation Relation spreadsheet a user is allows to modify the conservation relations in a model.

Figure 5. JCMB Rules tab.

There are four columns in the Rules spreadsheet:

4.4 - Compartments Spreadsheet
The Compartments spreadsheet can be used by the modeler to define different regions in which a reaction occurs. A compartment represents a bouded space in which species can be located. In addition to defining these regions, spatial relationships between different regions can be set up. The modeler is not required to enter any compartment information when defining a model. By defualt JCMB will designate one three dimensional compartment (called "cell") that contains all the species in the model. The user can simply accept this defualt setting by leaving the compartment spreadsheet blank. If the user does wish to define more than one compartment, the spreadsheet provides several fields for specifying information.

Compartment Spreadsheet
Figure 6. JCMB Compartments tab.

There are seven columns in the Compartments spreadsheet:

4.5 - Species Spreadsheet
The Species spreadsheet presents the user with a list of all species that were part of a chemical reaction or defined in the Rules spreadsheet. The list of species is maintained by JCMB, though a user can add/delete and modify species. There are several values associated with each species, which the user can edit these values.

Species Spreadsheet
Figure 7. JCMB Species tab.

There are eleven columns in the Species spreadsheet:

4.6 - Parameters Spreadsheet
The parameter spreadsheet is used by JCMB to manage all parameters and their values associated with a model. A parameter is used to declare a variable for use in mathematical formulae in a model. JCMB recognizes any variable that is not defined as a species on the Reactions spreadsheet as a parameter.

Parameter Spreadsheet
Figure 8. JCMB Parameters tab.

There are five columns in the Species spreadsheet:

4.7 - Events Spreadsheet
The events spreadsheet allows the user to define actions associated with a model. For example, in cell cycle modeling, cellular division is an extremely important action that must be defined for completeness of a model. The name column of the events spreadsheet can be any combination of characters and has no effect on the model except to indicate the importance of a particular event.

Events Spreadsheet
Figure 9. JCMB Events tab.

There are six columns in the Events spreadsheet:

4.7.1 - Event Assignment Editor
The Event Assignment Editor helps the user in defining the assignments that will be made when an event is executed. JCMB provides the user the ability to define multiple actions for an event by selecting the Add Row and Remove Row buttons. When all assignments have been made the user can commit the changes by selecting the Done button. The assignments are displayed as a semi colon separated list in the Assignment column of the Events spreadsheet.

Event Assignment Editor
Figure 10. JCMB Event Assignemt Editor.

There are three columns in the Event Assignment spreadsheet:

4.8 - Units Spreadsheet
The User Spreadsheet list all of the unit specified in the model along with their definitions. A unit definition is a name for a unit used in the expression of quantities in a model. JCMB has a number of basic units and 5 built-in unit definitions (area, length, time, substance and volume). In order to create a unit definition the user specifies the name of the unit and then create the definition using the Units Editor by clicking on the cells in the Unit Definition column.

Events Spreadsheet
Figure 11. JCMB Units tab.

There are two columns in the Units spreadsheet:

4.8.1 - Units Editor
The Units Editor enables a user to explicitly specify a unit definition. The JCMB provides the user the ability to create unit definitions compositionally by selecting the Add Row and Remove Row buttons. The Add Row and Remove Row buttons enable the user to create complex unit definitions such as meter/second^2. The base unit specified in the Unit field is transformed according to the values in the other fields to give a transformed unit. The equation of the transformed unit is: transformed base unit = (multiplier * 10^scale * base unit^ exponent) + offset.

Event Assignment Editor
Figure 12. JCMB Units Editor.

There are five columns in the Units Editor spreadsheet:

4.9 - Conservation Relations Spreadsheet
The conservation relations spreadsheet is used by JigCell to maintain a list of all the conservation relationships that exist between species in the model. The list of conservation equations is generated automatically for the user. JCMB uses Reder's method to generate a list of conservation equations from the data specified on the model spreadsheet.

Conservation Relations Spreadsheet
Figure 13. Conservation Relations tab.

There are three columns in the Conservation Relations Spreadsheet:

4.10 - Equations Spreadsheet
The differential equation spreadsheet is maintained exclusively by JCMB. The user is not required to enter any data on this spreadsheet, however, it is useful when the modeler wants to see the different types of equations that compose the model. The two types of equations are differential equations and assignment rule equations.

Differential Equation Spreadsheet
Figure 14. Differential Equation tab.

There are two columns in the Equations Spreadsheet.