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
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.
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.
- File - The file menu provides the user with file management options.
- New - Opens a new model builder file with empty spreadsheets.
- Open - Allows the user to open an SBML file.
- Save - Saves the active SBML file.
If the active file has not yet been saved, a Save dialog box will prompt the user to choose a location and enter a name for the file.
- Save As - Also saves the active SBML file, however, will always ask the user for a location and name.
- Exit - Closes JCMB and all associated files.
- Edit - The edit menu provides the user with the ability to edit data in the spreadsheets.
- Cut - This command removes the selection and places it on a clipboard.
- Copy - This command places a copy of the selection on the clipboard
- Paste - This command only places those rows cut or copied from the JCMB to the
clipboard at the current cursor location in the displayed spreadsheet. Rows cannot be
pasted across different tabs/spreadsheets.
- Add 1 Row - This command adds 1 row to the end of the currently displayed spreadsheet.
- Add 5 Rows - This command adds 5 rows to the end of the currently displayed spreadsheet.
- Shift Up - This command shifts the selected rows up by one.
- Shift Down - This command shifts the selected rows down by one.
- Remove Row(s) - This command deletes the selected rows.
- Help - The help menu provides the user with an About option that will
display an about box for JCMB. Inside the about box the user will be given the
version number and contact information. If any problems are encountered please
use this information to get help.
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.
Figure 2. A Frogegg Model as entered in JCMB's Reaction tab.
There are six columns in the Reactions spreadsheet:
- Name - Defines the name of the chemical reaction.
This field does not define any characteristics of the reaction, but does allow the modeler to quickly and easily identify the importance of
certain reactions in the model.
- Reaction - Defines the species (reactants and products) and their corresponding
stoichiometries of the chemical reaction.
A list of substrates separated by '+' signs is entered first. An arrow'->' is then entered, and is followed by a list of products, also separated by '+' signs. Substrate and product names can contain any combination of letters, numbers, underscores, and apostrophes. There is no limit to the number of species that can be entered as substrates or products. The stoichiometry of a reaction is defined by placing a number and a '*' character in front of the species (ex 3*Ca).
- Type - The Type field allows the user to specify the
kinetics of the reaction being defined by picking a rate law from a dropdown list.
JCMB provides three built in rate laws: Mass Action, Michaelis Menten,
Local as well as any user defined kinetic laws.
For all rate laws other than Local, JCMB will enter the associated rate law equation in the equation field.
The Local law allows the user to specify a new rate law for a specific reaction.
If the user selects Local, the equation field will remain empty until the user
defines the desired rate law. The Local type is most useful when a user defined
rate law will be used only once or twice in a model. Local rate laws may
contain algebraic expressions with constants and species specified in
the reaction column.
- Equation - This column specifies the kinetic law of the reaction.
If a user selects the reaction type to be Local this column is
left blank to allow the user to enter the local rate law. If the reaction type is not
Local the Equation column displays the unsubstituted equation of the selected kinetic
law. The user edits the kinetic law equation by clicking on the cells in this column which displays the
Parameters/Modifiers Editor.
JCMB will substitute the user entered parameter values (from the Parameters/Modifiers
Editor) into the Equation field of the spreadsheet so the user can see the final rate law used to govern the reaction.
- Fast - The optional fast field has no default value. If the user checks this
field it signifies that the given reaction is a "fast" one compared to others in the system
being modeled.
- Notes - The Notes field stores optional information such as user comments
about the structure in which the Notes field is enclosed.
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:
- Variable - Uneditable field that lists the variables in the unsubstitued
equation.
- Assignment operator - Uneditable field that displays an "=" sign to signify the assignment of a
particular parameter/modifer to a variable.
- Parameters/Modifiers - Defines the name of the chemical reaction.
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.
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.
Figure 4. JCMB Functions tab.
There are four columns in the Functions spreadsheet:
- Name - Defines the name of the function.
- Kinetic Law - This field tells JCMB whether to include a function in the list of
functions/kinetic laws in the Type field in the Reactions spreadsheet.
- Equation - The Equation column allows the user to specify the equation
that is defined by the function. This equation may contain arguments, passed to
the function by the user when the function is called, and constants. Each
argument is in the form Ai, where 'i' indicates the position of
the argument in the list of arguments passed by the user (ex. A3). Function
definitions do not allow for modifiers and constants so all terms in the
equation definition must be arguments. When defining an equation for a function
the modeler is allowed to use another, previously defined function.
Once a function has been defined it can be used in equations throughout the
model. The syntax for using a function is: FunctionName(A1,A2,A3, ... ,An).
- Notes - The Notes field stores optional information such as user comments
about the structure in which the Notes field is enclosed.
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:
- Variable - Defines a new species that will be assignmed a quantity in this Assignment rule.
Algrebraic rules have no variable field so this is left blank.
- Type - Specifies the type of the rule, in JCMB this will either be
Assignment or Algrebraic.
- Equation - Defines the equation of the rule governing the value assigned to the
new species. In order to aide in error prevention the species and parameter names are automatically entered in the
Species and Parameters spreadsheets by JCMB as the user enters data on the Rules spreadsheet.
The JigCell Run Manager will use these parameters to establish a basal parameter set
for the model.
- Notes - The Notes field stores optional information such as user comments
about the structure in which the Notes field is enclosed.
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.
Figure 6. JCMB Compartments tab.
There are seven columns in the Compartments spreadsheet:
- Name - The user must give the new compartment a name before continuing.
- Outside Of - This field is used to express containment relationships between
compartments.
The information entered in this field must be the name of a previously defined compartment.
The compartment listed in the Outside Of field encapsulates the compartment that is currently being defined.
- Spatial Dimensions - The Spatial Dimensions accepts an integer from 0 to 3 representing the number of spatial dimensions of the region. The defualt spatial dimension is 3.
- Size - The Size field represents the total size of the compartment. The
Size field enables concentrations of species to be calculated in the absence of
geometry information.
- Units - The Units field associates the compartment's size value with
units defined in the Units spreadsheet.
- Constant - This field indicates whether the comparment's size stays constant or
can vary during a simlation. The default value for the Constant field is true.
- Notes - The Notes field stores optional information such as user comments
about the structure in which the Notes field is enclosed.
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.
Figure 7. JCMB Species tab.
There are eleven columns in the Species spreadsheet:
- Name - The user must specify a species name before continuing.
- Initial Substance - This field specifies the initial amount of a species present in a model.
This field is optional, and when left blank implies that the value is either unknown or not needed in the analysis of the system.
- Initial Concentration - Defines the initial concentration of a species in a
model and is an optional field.
If the compartment containing the species has a dimension of 0 then this field can not take on a value.
- Charge - The Charge field is an optional.
This field takes an integer value that represents the charge on a species in terms of electrons.
A modeler may find this field useful when working with ions.
- Compartment - This field allows the user to specify in which compartment the designated species is contained.
If the user has defined compartments, the name of one of the compartments should be entered in this field.
This field can also be left blank if the user has chosen not to create any compartments for the model.
- Substance Units - Specifies the unit type for the substance being defined.
All units, defined by the user or JCMB can be selected. This is not a required
field.
- Spatial Size Units - Defines the units of the area containing the substance. This field is not
required, however, if the user enteres data, the units must agree with the
dimensions of the compartment. For example if compartment dimension is 3, then the Spatial Size
Units must be volume.
- Only Substance Units - An optional field that defaults to false.
- Boundary Condition - An optional field that accepts the values true and false. This field is used to specify how the
concentration of a particular species is determined. The default setting
for this option is false and indicates if a species is either a product or reactant of
chemical reactions then its concentration is determined by these chemical
reactions. However, if the species is on the boundary of a reaction system,
this field can be set to true and a differential equation for the species will
not be derived from the reactions.
- Constant - This is an optional field when set to false (the default value) indicates that the
concentration of that species can vary during a simulation.
- Notes - The Notes field stores optional information such as user comments
about the structure in which the Notes field is enclosed.
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.
Figure 8. JCMB Parameters tab.
There are five columns in the Species spreadsheet:
- Name - The user must specify a parameter name before continuing.
- Value - This field specifies the initial amount of a parameter present in a model.
JCMB does not require that a value be entered for every parameter.
Leaving this field blank implies that the value is either unknown, determined by an assignment rule, or
not required for analysis.
- Units - The field specifies the units associated with the value of the parameter.
- Constant - The optional Constant field indicates whether the parameter's
value can vary during simulation.
- Notes - The Notes field stores optional information such as user comments
about the structure in which the Notes field is enclosed.
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.
Figure 9. JCMB Events tab.
There are six columns in the Events spreadsheet:
- Name - This is an optional field to identify an event.
- Trigger - The Trigger field defines when the event has an effect on the model.
The event is fired when the condition in the Trigger field becomes true.
The format of this entry allows the user to specify an equality relationship.
An algebraic expression should be entered and followed by one of the following symbols: = , >, <, > =, < =.
The right hand side of the relationship can be an algebraic expression or a constant.
Whenever the relationship entered in the trigger column is satisfied the actions specified in the assignments column will occur.
- Delay - The optional Delay field dines the length of time after an event
has fired that the event is executed. Once the expression entered in the Trigger column is satisfied a delay
will be applied, and then the actions specified in the Assignments column will be
taken.
- Time Units - The optional Time Units field determines the units of time
that apply to the Delay field.
- Assignments - The Assignments field represents variable assignments that
have effect when an event is executed.
JCMB provides the user the ability to define multiple actions for an event and uses a
semicolon separated list to display all the event assignments.
The user edits the events assignments by clicking on
the cells in this column which displays the Event Assignment Editor.
- Notes - The Notes field stores optional information such as user comments
about the structure in which the Notes field is enclosed.
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.
Figure 10. JCMB Event Assignemt Editor.
There are three columns in the Event Assignment spreadsheet:
- Variable - This is an drop down menu of all the compartments, species and
parameters that an be assigned values or expressions.
- Assignment operator - Uneditable field that displays an "=" sign to signify the assignment of a
particular value (defined in the Math field) to a variable.
- Math - The Math field defines the value for the selected variable.
The math of each assignment can be a constant or an expression
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.
Figure 11. JCMB Units tab.
There are two columns in the Units spreadsheet:
- Name - The name of a given unit definition.
- Unit Definition - Specifies the compositional makeup of unit definition. For
example the unit acceleration is constructed by combining the unit meter with the unit second
resulting in the unit definition metre/second^2.
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.
Figure 12. JCMB Units Editor.
There are five columns in the Units Editor spreadsheet:
- Unit - A drop down menu of the list of base units defined in SBML (see Table 2 of the SBML Level 2 Specifications)
- Exponent - The exponent of the base unit, its defualt value is 1. A value of 2
for metre corresponds to metre^2.
- Scale - This is an optional field whose value must be an integer exponent for a
power of ten multiplier user to set the scale of the unit. The default value is 0. A value of -3 for gram
corresponds to 10^-3 * gram (or milligrams).
- Multiple - This is an optional field which can be used to multople the unit by a
real-numbered factor. This enables the definitions of units that are not power-of-ten
multiples of SI units.
- Offset - This field is used to represent the addition of a constant to the unit.
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.
Figure 13. Conservation Relations tab.
There are three columns in the Conservation Relations Spreadsheet:
- Conservation Relation - This field allows the user to
substitute new conservation relations for those entered by JCMB. JCMB derives
all the conservation relations on this spreadsheet from the user-entered data
on the Reactions spreadsheet.
Occasionally, one of the relationships JCMB derives will be
phyiscally meaningless. Although the equation is physically meaningless, it is
still correct, and can be used to simplify conservation relationships. For
example, if JCMB derives the equations -A1 - A2 - A3 and A1 + A2 + A3 + A4 + A5
a simplification can be made. The user can now substitute A4 + A5 for the first
equation.
- Constant Total Name - This field represents the name of the variable that will
be used to store the constant value associated with this conservation
relationship. The user does have the ability to edit the name of this variable
to something meaningful
- Dependent Species - The Dependent Species field allows the user to choose
which species from this conservation relation is dependent.
JCMB willnot generate a differential equation for the dependent species in a conservation relation, but will instead use a linear combintation of other species to determine its concentration.
The modeler also has the ability to edit this field by selecting the species from a drop down menu.
However, JigCell will set one of the species to be dependent by default so the user does not have to edit this field.
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.
Figure 14. Differential Equation tab.
There are two columns in the Equations Spreadsheet.
- Species - The Species field identifies all the species in the model. For
species that are assigned by a rule the species name is given. For species with a differential
equation the species name (X) is modified to display dX/dt.
- Equation - This displays either a differential equation (generated automatically by
JCMB), the assignment rule or the condition set on the species if no equation exists, such as "Set by conservation
relation."
)
)
)
)
)
)
)
)
)
)
)
)
)
)