In order to explain the changes in SBML species and reactions for Level 3, some background information is useful.
Reactions are processes (perhaps biochemical, perhaps other) that occur over time. At their most fundamental, these processes involve events of some sort. A single reaction event is an event in which some set of entities (in SBML named reactants and modifiers) interact, once. As time moves forward in a system, the reaction keeps occurring as long as there are entities left to participate in the reaction. The extent of the reaction is how many times the reaction has happened after the system has started. The time derivative of this extent gives the rate at which the reaction is occurring. What is colloquially referred to as the "rate of the reaction" is in fact equal to the rate of change of the extent.
The commonly-used symbol for the extent of a reaction is ξ (the Greek letter xi). Imagine now the simplest possible kind of reaction, the decay or consumption of some particular kind of entity, A, which we might represent as A → . The rate of change in the number x of entities of A is related to the rate of change of the reaction extent in the following way:
dxA / dt = νA dξ / dt
The νA (Greek letter nu ) is the stoichiometric coefficient for species A. This is the traditional stoichiometry that chemists use. It is, properly speaking, a dimensionless number; when a species is consumed, as in this example, it is usually taken to be a negative number. In the expression above, what it means is that for every reaction event that occurs, a number equal to νA of entities A are changed.
Now, consider what happens if the units of ξ are not the same as the units of xA. (For example, the units of xA might be in terms of grams, while the reaction extent might be in terms of Avogadro's number of reaction events—sometimes inappropriately referred to as "moles of reaction events", even though the mole is, properly speaking, a unit of substance.) A conversion factor is needed somewhere. In SBML Level 2, this conversion factor is embedded in the "SBML stoichiometry" (which is either the SpeciesReference's
stoichiometry attribute or its StochiometryMath object, whichever happens to be used). StoichiometryMath and
stoichiometry on SpeciesReference in SBML Level 2 thus combine the "chemical" stoichiometry and any necessary unit conversion factors. In the most common usage, modelers only use the
stoichiometry attribute, in which case a single number in the model represents both the chemical stoichiometry and the unit conversion factor. The section on Reaction in the Level 2 Version 4 specification has many examples of setting
stoichiometry exactly in this manner. The problem is that the units are never explicitly stated, and by combining the "chemical" stoichiometry with any necessary conversion factors, it is impossible in some cases to untangle them without additional knowledge that is not present in the model representation.
In Level 3, the conversion factor is made explicit using a new attribute on Species.
Changes compared to Level 2
The figure below shows the new attribute
conversionFactor on the Species object:
conversionFactor attribute is optional and has no default value. The value of this attribute should be the identifier of a global parameter in the model. This parameter can be used to express any necessary unit conversions. Under this SBML Level 3 scheme, if a given Species A has a value for
conversionFactor, the rate of change in the quantity xA of species A is given by the following equation:
dxA / dt = νA ⋅ CA ⋅ dξ / dt
where CA is the conversion factor that takes the units of a kinetic law to the units of species A. Note that, because all kinetic laws in a model are assumed to have the same units, there only needs to be one conversion factor for a given species—it is not a per-reaction property, but a per-species property, because of the fact that all reaction rates in an SBML model are assumed to be in the same units (whatever those units may be).
Conversely, if a species object does not define a value for the
conversionFactor attribute, the factor is undefined. (This case must be permitted because SBML does not force units of quantities in a model to be declared, therefore leaving out conversion factors must also be permitted.) Then the interpretation given is
dxA / dt = νA ⋅ dξ / dt
This approach offers the advantage that all of the regular SBML machinery for annotations, SBO terms, initial assignments, etc., are available for conversion factors, by virtue of making them ordinary Parameters in the model.
conversionFactor attribute is optional, but since it has no default value, omitting conversion factors in a model means that the units of the model's system of reactions are incompletely specified. However, this does not mean the model is invalid; this follows the principle (in place since Level 2 Version 4) that SBML does not require unit consistency or completeness in order for a model to be considered valid.
As a consequence of the need for a conversion factor to add the necessary unit information, this approach does impose a new requirement for creating Level 3 models that have completely specified units: the model must define at least one conversion factor. For many models, this should not be a significant burden, since nearly all models follow a principle of good modeling practice to use the same units for all their species quantities; consequently, the models only need to define one parameter with units to serve as a conversion factor, and then can reference that same parameter as the conversion factor in every SpeciesReference. (Another way to do it would be to use the new global conversion factor attribute on Model.)