libSBML C API  libSBML 5.8.0 C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SpeciesReference Class Reference

Detailed Description

Implementation of SBML's SpeciesReference construct.

The Reaction structure provides a way to express which species act as reactants and which species act as products in a reaction. In a given reaction, references to those species acting as reactants and/or products are made using instances of SpeciesReference structures in a Reaction object's lists of reactants and products.

A species can occur more than once in the lists of reactants and products of a given Reaction instance. The effective stoichiometry for a species in a reaction is the sum of the stoichiometry values given on the SpeciesReference object in the list of products minus the sum of stoichiometry values given on the SpeciesReference objects in the list of reactants. A positive value indicates the species is effectively a product and a negative value indicates the species is effectively a reactant. SBML places no restrictions on the effective stoichiometry of a species in a reaction; for example, it can be zero. In the following SBML fragment, the two reactions have the same effective stoichiometry for all their species:

<reaction id="x">
    <listOfReactants>
        <speciesReference species="a"/>
        <speciesReference species="a"/>
        <speciesReference species="b"/>
    </listOfReactants>
    <listOfProducts>
        <speciesReference species="c"/>
        <speciesReference species="b"/>
    </listProducts>
</reaction>
<reaction id="y">
    <listOfReactants>
        <speciesReference species="a" stoichiometry="2"/>
    </listOfReactants>
    <listOfProducts>
        <speciesReference species="c"/>
    </listProducts>
</reaction>

The precise structure of SpeciesReference differs between SBML Level 2 and Level 3. We discuss the two variants in separate sections below.

SpeciesReference in SBML Level 2

The mandatory "species" attribute of SpeciesReference must have as its value the identifier of an existing species defined in the enclosing Model. The species is thereby designated as a reactant or product in the reaction. Which one it is (i.e., reactant or product) is indicated by whether the SpeciesReference appears in the Reaction's "reactant" or "product" lists.

Product and reactant stoichiometries can be specified using either "stoichiometry" or "stoichiometryMath" in a SpeciesReference object. The "stoichiometry" attribute is of type double and should contain values greater than zero (0). The "stoichiometryMath" element is implemented as an element containing a MathML expression. These two are mutually exclusive; only one of "stoichiometry" or "stoichiometryMath" should be defined in a given SpeciesReference instance. When neither the attribute nor the element is present, the value of "stoichiometry" in the SpeciesReference instance defaults to 1.

For maximum interoperability, the "stoichiometry" attribute should be used in preference to "stoichiometryMath" when a species' stoichiometry is a simple scalar number (integer or decimal). When the stoichiometry is a rational number, or when it is a more complicated formula, "stoichiometryMath" must be used. The MathML expression in "stoichiometryMath" may also refer to identifiers of entities in a model (except reaction identifiers). However, the only species identifiers that can be used in "stoichiometryMath" are those referenced in the Reaction list of reactants, products and modifiers.

The following is a simple example of a species reference for species X0, with stoichiometry 2, in a list of reactants within a reaction having the identifier J1:

<model>
    ...
    <listOfReactions>
        <reaction id="J1">
            <listOfReactants>
                <speciesReference species="X0" stoichiometry="2">
            </listOfReactants>
            ...
        </reaction>
        ...
    </listOfReactions>
    ...
</model>

The following is a more complex example of a species reference for species X0, with a stoichiometry formula consisting of the parameter x:

<model>
    ...
    <listOfReactions>
        <reaction id="J1">
            <listOfReactants>
                <speciesReference species="X0">
                    <stoichiometryMath>
                        <math xmlns="http://www.w3.org/1998/Math/MathML">
                            <ci>x</ci>
                        </math>
                    </stoichiometryMath>
                </speciesReference>
            </listOfReactants>
            ...
        </reaction>
        ...
    </listOfReactions>
    ...
</model>

SpeciesReference in SBML Level 3

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 indirect and awkward for something that should be a simple matter. Moreover, the question of how to properly encode stoichiometries in SBML reactions has caused much confusion among implementors of SBML software.

SBML Level 3 approaches this problem differently. It (1) extends the the use of the SpeciesReference identifier to represent the value of the "stoichiometry" attribute, (2) makes the "stoichiometry" attribute optional, (3) removes StoichiometryMath, and (4) adds a new "constant" boolean attribute on SpeciesReference.

As in Level 2, the "stoichiometry" attribute is of type double and should contain values greater than zero (0). A missing "stoichiometry" implies that the stoichiometry is either unknown, or to be obtained from an external source, or determined by an InitialAssignment object or other SBML construct elsewhere in the model.

A species reference's stoichiometry is set by its "stoichiometry" attribute exactly once. If the SpeciesReference object's "constant" attribute has the value true, then the stoichiometry is fixed and cannot be changed except by an InitialAssignment object. These two methods of setting the stoichiometry (i.e., using "stoichiometry" directly, or using InitialAssignment) differ in that the "stoichiometry" attribute can only be set to a literal floating-point number, whereas InitialAssignment allows the value to be set using an arbitrary mathematical expression. (As an example, the approach could be used to set the stoichiometry to a rational number of the form p/q, where p and q are integers, something that is occasionally useful in the context of biochemical reaction networks.) If the species reference's "constant" attribute has the value false, the species reference's value may be overridden by an InitialAssignment or changed by AssignmentRule or AlgebraicRule, and in addition, for simulation time t > 0, it may also be changed by a RateRule or Event objects. (However, some of these constructs are mutually exclusive; see the SBML Level 3 Version 1 Core specifiation for more details.) It is not an error to define "stoichiometry" on a species reference and also redefine the stoichiometry using an InitialAssignment, but the "stoichiometry" attribute in that case is ignored.

The value of the "id" attribute of a SpeciesReference can be used as the content of a <ci> element in MathML formulas elsewhere in the model. When the identifier appears in a MathML <ci> element, it represents the stoichiometry of the corresponding species in the reaction where the SpeciesReference object instance appears. More specifically, it represents the value of the "stoichiometry" attribute on the SpeciesReference object.

In SBML Level 3, the unit of measurement associated with the value of a species' stoichiometry is always considered to be dimensionless. This has the following implications:

  • When a species reference's identifier appears in mathematical formulas elsewhere in the model, the unit associated with that value is dimensionless.

  • The units of the "math" elements of AssignmentRule, InitialAssignment and EventAssignment objects setting the stoichiometry of the species reference should be dimensionless.

  • If a species reference's identifier is the subject of a RateRule, the unit associated with the RateRule object's value should be dimensionless/time, where time is the model-wide unit of time set on the Model object.