libSBML C API
libSBML 5.8.0 C API
|
Implementation of SBML's UnitDefinition construct.
Units of measurement may be supplied in a number of contexts in an SBML model. The SBML unit definition facility uses two classes of objects, UnitDefinition and Unit. The approach to defining units in SBML is compositional; for example, meter second –2 is constructed by combining a Unit object representing meter with another Unit object representing second –2. The combination is wrapped inside a UnitDefinition, which provides for assigning an identifier and optional name to the combination. The identifier can then be referenced from elsewhere in a model. Thus, the UnitDefinition class is the container, and Unit instances are placed inside UnitDefinition instances.
Two points are worth discussing in the context of SBML units. First, unit declarations in SBML models are optional. The consequence of this is that a model must be numerically self-consistent independently of unit declarations, for the benefit of software tools that cannot interpret or manipulate units. Unit declarations in SBML are thus more akin to a type of annotation; they can indicate intentions, and can be used by model readers for checking the consistency of the model, labeling simulation output, etc., but any transformations of values implied by different units must be incorporated explicitly into a model.
Second, the vast majority of situations that require new SBML unit definitions involve simple multiplicative combinations of base units and factors. An example is moles per litre per second. What distinguishes these sorts of unit definitions from more complex ones is that they may be expressed without the use of an additive offset from a zero point. The use of offsets complicates all unit definition systems, yet in the domain of SBML, the real-life cases requiring offsets are few (and in fact, to the best of our knowledge, only involve temperature). Consequently, the SBML unit system has been consciously designed to simplify implementation of unit support for the most common cases in systems biology. The cost of this simplification is to require units with offsets to be handled explicitly by the modeler.
UnitDefinition has two attributes and one subelement. The two attributes are "id" and "name", and the subelement is ListOfUnits.
The required attribute "id" and optional attribute "name" are both strings. The "id" attribute is used to give the defined unit a unique identifier by which other parts of an SBML model definition can refer to it. The "name" attribute is intended to be used for giving the unit definition an optional human-readable name. Please see the next section for information about the values permitted for "id".
A UnitDefinition must contain exactly one ListOfUnits, and this list must contain one or more Unit definitions; see the definitions of these other object classes for more information about them. The following example illustrates a complete unit definition (when written in XML) when they all the pieces are combined together. This defines "mmls" to be millimoles per litre per second.
<listOfUnitDefinitions> <unitDefinition id="mmls"> <listOfUnits> <unit kind="mole" scale="-3"/> <unit kind="litre" exponent="-1"/> <unit kind="second" exponent="-1"/> </listOfUnits> </unitDefinition> </listOfUnitDefinitions>
The attribute "id" in UnitDefinition cannot be given simply any value, and the precise details of the values permitted differ slightly between Levels of SBML:
The "id" of a UnitDefinition must not contain a value from the list of SBML's predefined base unit names (i.e., the strings gram
, litre
, etc.). In SBML Level 3, this list consists of the following:
ampere | farad | joule | lux | radian | volt |
avogadro | gram | katal | metre | second | watt |
becquerel | gray | kelvin | mole | siemens | weber |
candela | henry | kilogram | newton | sievert | |
coulomb | hertz | litre | ohm | steradian | |
dimensionless | item | lumen | pascal | tesla |
This list of predefined base units is nearly identical in SBML Level 2 Version 4, the exception being that Level 2 does not define avogadro
. SBML Level 2 Version 1 (and only this Level+Version combination) provides an additional predefined unit name, Celsius
, not available in Level 3. Finally, SBML Level 1 Versions 2–3 provide two more additional predefined unit names, meter
and liter
. This is explained in somewhat greater detail in the description of the Unit class.
In SBML Level 2 (all Versions), there is an additional set of reserved identifiers: substance
, volume
, area
, length
, and time
. Using one of these values for the attribute "id" of a UnitDefinition has the effect of redefining the model-wide default units for the corresponding quantities. The list of special unit names in SBML Level 2 is given in the table below:
Identifier | Possible scalable units | Default units |
---|---|---|
substance | mole, item, gram, kilogram, dimensionless | mole |
volume | litre, cubic metre, dimensionless | litre |
area | square metre, dimensionless | square metre |
length | metre, dimensionless | metre |
time | second, dimensionless | second |
Also, SBML Level 2 imposes two limitations on redefining the predefined unit substance
, volume
, area
, length
, and time:
(1) The UnitDefinition of a predefined SBML unit can only contain a single Unit object within it. (2) The value of the "kind" attribute in a Unit instance must be drawn from one of the values in the second column of the table above.
The special unit names substance
, volume
, area
, length
, and time
are not defined by SBML Level 3, which uses a different approach to setting model-wide inherited units.
The vast majority of modeling situations requiring new SBML unit definitions involve simple multiplicative combinations of base units and factors. An example of this might be moles per litre per second. What distinguishes these sorts of simpler unit definitions from more complex ones is that they may be expressed without the use of an additive offset from a zero point. The use of offsets complicates all unit definition systems, yet in the domain of SBML the real-life cases requiring offsets are few (and in fact, to the best of our knowledge, only involve temperature). Consequently, the SBML unit system has been consciously designed in a way that attempts to simplify implementation of unit support for the most common cases in systems biology.
As of SBML Level 2 Version 2, Unit no longer has the attribute called "offset" introduced in SBML Level 2 Version 1. It turned out that the general case involving units with offsets was incorrectly defined, and few (if any) developers even attempted to support offset-based units in their software. In the development of Level 2 Version 2, a consensus among SBML developers emerged that a fully generalized unit scheme is so confusing and complicated that it actually impedes interoperability. SBML Level 2 Version 2, Version 3 and Version 4 acknowledge this reality by reducing and simplifying the unit system, specifically by removing the "offset" attribute on Unit and Celsius
as a pre-defined unit.
The following guidelines suggest methods for handling units that do require the use of zero offsets for their definitions:
Handling Celsius. A model in which certain quantities are temperatures measured in degrees Celsius can be converted straightforwardly to a model in which those temperatures are in kelvin. A software tool could do this by performing a straightforward substitution using the following relationship: T kelvin = TCelsius + 273.15. In every mathematical formula of the model where a quantity (call it x) in degrees Celsius appears, replace x with xk+ 273.15, where xk is now in kelvin. An alternative approach would be to use a FunctionDefinition object to define a function encapsulating this relationship above and then using that in the rest of the model as needed. Since Celsius is a commonly-used unit, software tools could help users by providing users with the ability to express temperatures in Celsius in the tools' interfaces, and making substitutions automatically when writing out the SBML.
Other units requiring offsets. One approach to handling other kinds of units is to use a FunctionDefinition to define a function encapsulating the necessary mathematical relationship, then substituting a call to this function wherever the original quantity appeared in the model. For example, here is a possible definition for converting Fahrenheit to Celsius degrees:
<functionDefinition id="Fahrenheit_to_kelvin"> <math xmlns="http://www.w3.org/1998/Math/MathML"> <lambda> <bvar><ci> temp_in_fahrenheit </ci></bvar> <apply> <divide/> <apply> <plus/> <ci> temp_in_fahrenheit </ci> <cn> 459.67 </cn> </apply> <cn> 1.8 </cn> </apply> </lambda> </math> </functionDefinition>
An alternative approach not requiring the use of function definitions is to use an AssignmentRule for each variable in Fahrenheit units. The AssignmentRule could compute the conversion from Fahrenheit to (say) kelvin, assign its value to a variable (in Kelvin units), and then that variable could be used elsewhere in the model.
Please consult the SBML specifications for more information about this and other issues involving units.