— the global portal for all things SBML

Changes to stoichiometry

Image:Updated.gif on 2009-7-23.

In Level 2's definition of a reaction, the stoichiometry attribute of a SpeciesReference is actually a combination of two factors, the standard biochemical stoichiometry and a conversion factor that may be needed to translate the units of the species quantity to the units of the reaction rate. Unfortunately, Level 2 offers no direct way of decoupling these two factors, or for explicitly indicating the units. The only way to do it in Level 2 is to use the StoichiometryMath object associated with SpeciesReferences, and to reference SBML Parameter objects from within the StoichiometryMath formula. This works because Parameter offers a way to attach units to a numerical value, but the solution is relatively complex for something that should be a simple matter, and moreover, the software support for StoichiometryMath has always been relatively limited among SBML-compatible tools. In any case, the question of how to properly encode stoichiometries in SBML reactions has caused much confusion among implementers of SBML software.

After considerable discussion, we believe we have found a simple approach to resolving this problem; it simultaneously (1) makes explicit the conversion factor and (2) removes the need for StoichiometryMath, all without loss of generality. This page summarizes the proposed change to the Reaction construct in Level 3.

Changes relative to Level 2

There are four changes to the Reaction object involving stoichiometry: (1) the new enhancement of defining SpeciesReference identifiers to represent the value of the stoichiometry attribute; (2) the addition of a constant flag on SpeciesReference; (3) making the stoichiometry attribute optional; and (4) the removal of StoichiometryMath. The new UML diagram for Reaction is shown here:

In SBML Level 2, the stoichiometry of a reactant or product is a combination of both a "biochemical stoichiometry" (meaning, the standard stoichiometry of a species in a reaction) and any necessary conversion factors. (This is described as the "SBML stoichiometry" in the middle of page 76 of the Level 2 Version 4 r.1 specification.) The introduction of an explicit attribute on Species for a conversion factor allows Level 3 to avoid having to overload the meaning of stoichiometry. The stoichiometry given by a SpeciesReference object in a reaction is now a "proper" biochemical stoichiometry, meaning a dimensionless number free of unit conversions.

An existing issue in Level 2 is that there is no direct way to access or set the stoichiometry attribute value for a species. The only way is to create a parameter, then reference it from the StoichiometryMath <math> element, but this is cumbersome. To make it possible to refer to the actual value of stoichiometry for a given species in a reaction, Level 3 makes use of an identifier that has existed in SBML but so far has had no mathematical interpretation: the identifier on SimpleSpeciesReference. This identifier is global in scope and is inherited by the SpeciesReference object class. In Level 3, the identifier will stand for the stoichiometry attribute value of a species' participation in a given reaction. The identifier can be used in initial assignments and rules to achieve the same effects for which the previous StoichiometryMath object was used.

With the ability to reference and set the stoichiometry from other SBML constructs, there needs to be a constant attribute on SpeciesReference. A value of true (which will be the case for the vast majority of models) means that the stoichiometry value is a fixed constant in the model. This simply mirrors the way other identifiers (species, compartments, parameters) have a constant attribute.

In addition, with the value of stoichiometry potentially being set by using the SpeciesReference identifier in an InitialAssignment construct, the stoichiometry attribute must be optional in Level 3. It will allow a model to skip setting the stoichiometry attribute if the species stoichiometry is known to be set by some other means.

Finally, with the new ability to make arbitrarily complex stoichiometry calculations by referencing SpeciesReference identifiers in a model, the only reason for the existence of the StoichiometryMath construct goes away. StoichiometryMath has always been an oddity in SBML Level 2 because it is the only case where there is both an attribute (i.e., the stoichiometry attribute on SpeciesReference) and an element (i.e., the stoichiometryMath element on SpeciesReference) for the same thing. In Level 3, StoichiometryMath can be removed without any loss of capabilities. The Level 3 scheme is simpler and more flexible at the same time.

Notable implications

The combination of the two changes of (i) introducing an explicit conversion factor on Species objects and (ii) making the SpeciesReference identifier stand for the value of stoichiometry, eliminates the need for the previous StoichometryMath element while still making it possible to express complicated stoichiometries. If a mathematical formula is needed for expressing some sort of elaborate stoichiometry, it can be accomplished by using the SpeciesReference identifier in (e.g.) an AssignmentRule. Support for StoichiometryMath has rarely been implemented in software tools, and software developers expressed little desire to ever support it, which means that many tools would never be 100% SBML compliant. The Level 3 approach is by comparison simpler, and it is hoped, more likely to be supported by software tools, removing another obstacle to interoperability.

The changes to stoichiometry in Level 3 may make it seem as though there is more power, for example by appearing to introduce the potential for variable stoichiometries. In fact, this is not true; exactly the same capabilities already exist in Level 2, albeit in different form. Best practice guidelines for SBML will stipulate that stoichiometries should be declared constant and set via the stoichiometry attribute.

Retrieved from ""

This page was last modified 01:56, 23 July 2009.

Please use our issue tracking system for any questions or suggestions about this website. This page was last modified 01:56, 23 July 2009.