SBML.org — the global portal for all things SBML

Model changes

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

The Model component will have a number of new attributes related to the changes to the unit system. First, there will be a new set of attributes to replace the "built-in units" of Level 2 (i.e., the five reserved UnitSId identifiers substance, time, volume, area, and length), along with the addition of a new attribute for the unit of reaction extent. The second attribute is for a global conversion factor.

The motivations for the first changeĀ are the following. With the change to have no default values in SBML Level 3, the unit identifiers substance, time, volume, area, and length would necessarily no longer have default values. Although it is permissible in SBML to have model definitions without any unit definitions, the majority of models and modelers do define their units. In Level 3, doing this would mean that every model with units of (e.g.) substance, time and volume, would have to use the full Unit/UnitDefinition mechanism to define model-wide units; further, the same no-defaults change means that every attribute in the unit definitions would have to be provided. This approach is cumbersome and not very obvious, and consequently likely to be error-prone. The SBML unit system in Level 2 and the use of substance, time, etc., has always proven to be difficult to explain to new SBML developers, and the resulting system for Level 3 would only worsen the situation. A second motivation is that the use of reserved identifiers in the namespace of UnitSId has always been a less-than-ideal solution; apart from being inelegant, it always carried the risk that someone would unknowingly define a unit named, e.g., 'substance', not realizing the implications for the units of all the reactions in the model.

The motivations for the second change are the following. As mentioned elsewhere, Level 3 Core will introduce a conversion factor attribute on the Species object, so that a model can indicate how the units of reactions (which is to say, units of extent per unit of time) are related to the units of a given species. To fit with the general SBML scheme of providing a way to set model-wide defaults such as for substance units, the Model component will have an optional attribute allowing a model to define a single conversion factor when all the species are intended to use the same factor. (The analogy here is to the way a model can also define global substance units and then skip the specification of units on individual species definitions.)

Changes compared to Level 2

The new UML diagram for the Model element in Level 3 is shown below; it shows the new attributes to be defined on <model>.


The attributes substanceUnits, timeUnits, volumeUnits, areaUnits, lengthUnits and extentUnits all take unit identifiers as values, while the conversionFactor attribute takes the identifier of a Parameter in the model as value. Note that the attributes have no default values. To declare that a model uses, for example, substance units of moles, time units of second, and volume units of liters, the model would begin like this:

<model substanceUnits="mole" timeUnits="second" volumeUnits="litre">
   ...
</model>

To declare that a model uses micromoles for substance units, picoliters for volume, and seconds for time, the required constructs would be like this:

<model substanceUnits="micromole" timeUnits="second" volumeUnits="picoliter">
 <listOfUnitDefinitions> 
   <unitDefinition id="micromole"> 
     <listOfUnits> 
       <unit kind="mole" scale="-6" exponent="1" multiplier="1"/> 
     </listOfUnits> 
   </unitDefinition> 
   <unitDefinition id="picoliter"> 
     <listOfUnits> 
       <unit kind="litre" scale="-12" exponent="1" multiplier="1"/> 
     </listOfUnits> 
   </unitDefinition> 
 </listOfUnitDefinitions> 
  ... 
</model>

The conversion factor attribute, when provided, must be the identifier of a parameter in the model. When set, it indicates that all species that lack an explicit conversionFactor attribute value of their own should use the conversion factor given by the conversionFactor attribute on <model>. This facility is to meant to provide a shortcut for specifying conversion factors when a model uses all the same species units. The following is an example:

 
<sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" level="3" version="1">  
  <model substanceUnits="nanomole" timeUnits="second" extentUnits="mole"  
         conversionFactor="extent_to_substance">  
    <listOfUnitDefinitions>  
      <unitDefinition id="nanomole">  
        <listOfUnits>  
          <unit kind="mole" scale="-9" multiplier="1" exponent="1"/> 
         </listOfUnits>  
      </unitDefinition>  
      <unitDefinition id="femtoliter">  
        <listOfUnits>  
          <unit kind="litre" scale="-15" multiplier="1" exponent="1"/> 
        </listOfUnits>  
      </unitDefinition>  
    </listOfUnitDefinitions>  
    <listOfCompartments>  
      <compartment id="c" size="2" units="femtoliter" constant="true"/>  
    </listOfCompartments>  
    <listOfSpecies>  
      <species id="s1" compartment="c" initialAmount="100"  
                       hasOnlySubstanceUnits="false" constant="false" boundaryValue="false" /> 
      <species id="s2" compartment="c" initialAmount="20"  
                       hasOnlySubstanceUnits="false" constant="false" boundaryValue="false" /> 
      <species id="s3" compartment="c" initialAmount="350"  
                       hasOnlySubstanceUnits="false" constant="false" boundaryValue="false" /> 
    </listOfSpecies>  
    <listOfParameters>  
      <parameter id="extent_to_substance" value="1000000000" units="dimensionless"/>  
    </listOfParameters>  
    ...  
  </model>  
</sbml>  

In the example above, none of the species define a value for their substanceUnits attribute, hence they all inherit the global substanceUnits from <model> (in this case, "nanomole"). The conversion factor above has to convert from the rates of SBML kinetic laws in the model (which in this example, is set to be mole/second by virtue of the values of extentUnits and timeUnits on <model>) to the units of rate of change of species amounts (which are defined to be the substance units per time units, or nanomole/second in this example).

Notable implications

The change does not affect the way that units are inherited in SBML: just as in SBML Level 2, if a Species or Compartment object does not define the units of species quantity or compartment size, the units are taken from the global definitions of substance unit and volume/area/length units, respectively. In Level 3, what is changing is how the global units are defined. The unit identifiers named "substance", "time", etc., are being replaced with attributes on <model>. However, since there are not default units defined, it means that if the attributes substanceUnits, timeUnits, etc. on <model> are not defined, then there are simply no units to inherit; i.e., those units are undefined.

Retrieved from "http://sbml.org/Community/Wiki/SBML_Level_3_Core/Model_changes"

This page was last modified 17:56, 24 July 2009.



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