| Stoichiometry Information in CellML | |
Author:
Melanie Nelson (Physiome Sciences Inc.)
Contributors:
Warren Hedley (Bioengineering Institute, University of Auckland)
Poul Nielsen (Bioengineering Institute, University of Auckland)
David Bullivant (Bioengineering Institute, University of Auckland)
This document discusses three possible ways to allow processing software to extract stoichiometric information from CellML models. It is intended to initiate a discussion about how best to store this information in CellML.
Currently, stoichiometric information is contained only in the the MathML block of a <component>, as shown in Figure 1 for the reaction:
<component name="basic_reaction">
<variable name="A" public_interface="in" units="concentration_units" />
<variable name="B" public_interface="in" units="concentration_units" />
...
<variable name="delta_C" public_interface="out" units="flux_units" />
<variable name="delta_D" public_interface="out" units="flux_units" />
...
<variable name="r" units="flux_units" />
<reaction reversible="yes">
<variable_ref delta_variable="delta_A" variable="A">
<role role="reactant" direction="forward" />
</variable_ref>
<variable_ref delta_variable="delta_B" variable="B">
<role role="reactant" direction="forward" />
</variable_ref>
...
<variable_ref variable="r">
<role role="rate" direction="forward" />
</variable_ref>
</reaction>
<math xmlns="http://www.w3.org/1998/Math/MathML">
<!--
The rate is first calculated from the rate constants
and concentrations.
-->
...
<apply><eq />
<ci> delta_A </ci>
<apply><times />
<cn cellml:units="dimensionless"> 1.0 </cn>
<ci> r </ci>
</apply>
</apply>
<apply><eq />
<ci> delta_B </ci>
<apply><times />
<cn cellml:units="dimensionless"> 1.0 </cn>
<ci> r </ci>
</apply>
</apply>
...
</math>
</component>
Figure 1
A reaction <component> in which stoichiometric information is found in the component's MathML block.
This example is taken from the basic reaction example, with modifications made to the <reaction> element to reflect how the CellML development team anticipates including information about the reversibility of the reaction. Note that these changes to the <reaction> element structure also allow the representation of species with more than one role in a given reaction (e.g., a species that is both a reactant and a catalyst). (A set of example reaction elements to demonstrate these changes is available.)
The disadvantages of this method are:
-
The stoichiometric information is not easy to find. It may appear anywhere in the MathML block. However, the inclusion of the
delta_variable attributes on the <variable_ref> elements does at least indicate to software which variable contains the stoichiometric information.
-
It is not possible to indicate the stoichiometry of species whose concentration is not modified by the reaction (i.e., variables with roles of
"catalyst", "inhibitor", or "modifier").
The advantages of this method are:
-
It is consistent with how mathematics are specified in other types of models (such as electro-physiological models).
An alternative method for storing stoichiometric information is shown in Figure 2. The equations that define the stoichiometry of the reaction are still stored as MathML, but now appear in the <variable_ref> elements of the <reaction> element. The reaction described is again:
<component name="basic_reaction">
...
<reaction reversible="yes">
<variable_ref delta_variable="delta_A" variable="A">
<role role="reactant" direction="forward" />
<math xmlns="http://www.w3.org/1998/Math/MathML">
<apply><eq />
<ci> delta_A </ci>
<apply><times />
<cn cellml:units="dimensionless"> 1.0 </cn>
<ci> r </ci>
</apply>
</apply>
</math>
</variable_ref>
...
<variable_ref delta_variable="delta_C" variable="C">
<role role="product" direction="forward" />
<math xmlns="http://www.w3.org/1998/Math/MathML">
<apply><eq />
<ci> delta_C </ci>
<apply><times />
<cn cellml:units="dimensionless"> -2.0 </cn>
<ci> r </ci>
</apply>
</apply>
</math>
</variable_ref>
...
<variable_ref variable="r">
<role role="rate" direction="forward" />
<!--
One possible permutation of this method is to include the math for
the calculation of the rate in the reaction element as well.
-->
<math xmlns="http://www.w3.org/1998/Math/MathML">
...
</math>
</variable_ref>
</reaction>
</component>
Figure 2
A reaction <component> in which stoichiometric information is found in the <reaction> element.
The disadvantages of this method are:
-
It is not possible to indicate the stoichiometry of species whose concentration is not modified by the reaction (i.e., variables with roles of
"catalyst", "inhibitor", or "modifier").
-
We have now broken the mathematics specifying the behavior of the reaction into multiple MathML blocks. This may or may not make it harder for processing software to assemble the equations in the correct order for running the simulation.
-
The storage of MathML is no longer consistent with the best practices recommended for other types of models.
The advantages of this method are:
-
It is now easy for processing software to locate the stoichiometric information for a given reaction.
A set of example reaction elements to demonstrate this method is available.
The equations that define the stoichiometry of the reaction can still be stored as MathML, but now appear in the <variable_ref> elements of the <reaction> element. However, the stoichiometry of a reactant participant can also be indicated using the stoichiometry attribute of the <variable_ref> element. This allows modellers to indicate the stoichiometry of a species whose concentration does not change due to the reaction. This is demonstrated with species C in Figure 3.
A third method for storing stoichiometric information is shown in Figure 3, for the reaction:
A + B <-> D
(where the reaction is catalyzed by species C)
<component name="basic_reaction">
...
<reaction reversible="yes">
<variable_ref delta_variable="delta_A" stoichiometry="1" variable="A">
<role role="reactant" direction="forward" />
</variable_ref>
<variable_ref delta_variable="delta_B" variable="B">
<role role="reactant" direction="forward" />
<math xmlns="http://www.w3.org/1998/Math/MathML">
<apply><eq />
<ci> delta_B </ci>
<apply><times />
<cn cellml:units="dimensionless"> 1.0 </cn>
<ci> r </ci>
</apply>
</apply>
</math>
</variable_ref>
<variable_ref stoichiometry="1" variable="C">
<role role="catalyst" direction="forward" />
</variable_ref>
<variable_ref delta_variable="delta_D" stoichiometry="1" variable="D">
<role role="product" direction="forward" />
</variable_ref>
<variable_ref variable="r">
<role role="rate" direction="forward" />
<math xmlns="http://www.w3.org/1998/Math/MathML">
...
</math>
</variable_ref>
</reaction>
...
</component>
Figure 3
A reaction <component> in which stoichiometric information is found in the <reaction> element, either as MathML or as the value of an attribute on the <variable_ref> elements.
The disadvantages of this method are:
-
We now allow implicit math. Stoichiometry indicated with the stoichiometry attribute is assumed to result in a simple relationship between the delta variable and the rate, as shown for species
D in Figure 3. Alternatively, we could still to require math explicitly defining this relationship, even for species on which the stoichiometry attribute has been declared. However, this would be a duplication of information, which is also a disadvantage.
-
We now require software to deal with two different methods of specifying stoichiometry.
-
We still can't handle the case where the same species has two different stoichiometries, depending on its role. For instance, a species could participate in the reaction as a substrate with a stoichiometry of 1, but as an inhibitor with a stoichiometry of 2 (i.e., 2 moles of the species would need to be present for every mole of other species in order for inhibition to occur). It is not clear if we need to be able to represent this case. A possible method to allow CellML to handle this case is presented in Section 5
The advantages of this method are:
-
It is now possible to indicate the stoichiometry of species whose concentration is not modified by the reaction (i.e., variables with roles of
"catalyst", "inhibitor", or "modifier").
-
It allows a simple definition of stoichiometry in the majority of cases.
A set of example reaction elements to demonstrate this method is available.
[Note: This final method was partly developed on January 22nd, and is included here for comparison purposes. This would have been method four, but we call it method three to be consistent with the scheme used for the examples in the January 20 meeting minutes.]
In order to permit the specification of stoichiometry for activator and inhibitor reaction participants we move the stoichiometry attribute to the <role> element. The delta_variable attribute is also moved to the <role> element. The combination of delta_variable and stoichiometry attributes implies mathematical behaviour which is also dependent on whatever <variable_ref> plays the "rate" role. In the reaction defined in Figure 4, the species A is a reactant with a stoichiometry of one, and an inhibitor with a stoichiometry of 2. The actual reaction defined is:
A + B <-> D
(where the reaction is catalyzed by species C)
<component name="basic_reaction">
...
<reaction reversible="yes">
<variable_ref variable="A">
<role
role="reactant"
direction="forward"
delta_variable="delta_A"
stoichiometry="1" />
<role
role="inhibitor"
direction="forward"
stoichiometry="2" />
</variable_ref>
<variable_ref variable="B">
<role
role="reactant"
direction="forward"
delta_variable="delta_B"
stoichiometry="1" />
</variable_ref>
<variable_ref variable="C">
<role role="catalyst" direction="forward" />
</variable_ref>
<variable_ref variable="D">
<role
role="product"
direction="forward"
delta_variable="delta_D"
stoichiometry="1" />
</variable_ref>
<variable_ref variable="r">
<role role="rate" direction="forward" />
<math xmlns="http://www.w3.org/1998/Math/MathML">
...
</math>
</variable_ref>
</reaction>
...
</component>
Figure 4
A <component> element in which stoichiometric information and the delta_variable attribute has been moved to the <role> element.
The only real disadvantage with this method is that we have introduced CellML syntax that "implies" mathematical behaviour. The specification will define a set of rules for the use of delta_variable and stoichiometry attributes that forbids the specification of inconsistent reactions; basically all implied math must be consistent with any equations explicitly defined with MathML. A preview of the reaction-related part of the CellML specification is in the 22 January meeting minutes.
| 
