Checking units in libSBML

Units in SBML
and how libSBML checks them
Sarah Keating

Associate units with a variable
• Use attributes in the SBML
<compartment units=“ ” />
<species substanceUnits=“ ” />
<parameter units=“ ” />

• Values that can be used
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

• Use attributes in the SBML
<compartment units=“litre” />
<species substanceUnits=“mole” />
<parameter units=“second” />

• Not one of the base units

UnitDefinitions
id of unitDefinition used as unit attribute

<unitDefinition id=“my_metre”>
<listOfUnits>
<unit kind=“metre” scale=“0” multiplier=“1” exponent=“1”/>
</listOfUnits>
</unitDefinition>
1 id = (multiplier * 10scale * kind)exponent
1 my_metre = (1 * 100 * metre)1 = 1 m

<unitDefinition id=“milligram”>
<listOfUnits>
<unit kind=“gram” scale=“-3” multiplier=“1” exponent=“1”/>
</listOfUnits>
</unitDefinition>
1 milligram = (1 * 10-3 * gram)1 = 0.001 g

<unitDefinition id=“minute”>
<listOfUnits>
<unit kind=“second” scale=“0” multiplier=“60” exponent=“1”/>
</listOfUnits>
</unitDefinition>
1 minute= (60 * 100 * second)1 = 60 s

<unitDefinition id=“metre_squared”>
<listOfUnits>
</listOfUnits>
</unitDefinition>
1 metre_squared= (1* 100 * metre)2 = 1 m2

<unitDefinition id=“minute_squared”>
<listOfUnits>
<unit kind=“second” scale=“0” multiplier=“60” exponent=“2”/>
</listOfUnits>
</unitDefinition>
1 minute2= (60* 100 * second)2 = (60 s)2 =3600 s2

<unitDefinition id=“u0”>
<listOfUnits>
<unit kind=“second” scale=“0” multiplier=“1” exponent=“-1”/>
</listOfUnits>
</unitDefinition>
1 id = (m1 * 10s1 * kind1)e1 * (m2 * 10s2 * kind2)e2
1 u0 = (1* 100 * metre)2 * (1* 100 * second)-1 = 1 m2s-1
• Combination of base units

Checking units of variables
compartment
Spatial
Dimensions
Appropriate values for units attribute
0 dimensionless
1 metre
OR id of unitDefinition with
<unit kind=“metre” scale=“ ” multiplier=“ ” exponent=“1”/>
OR length (predefined in L1/L2 NOT L3)
2 id of unitDefinition with
OR area (predefined in L1/L2 NOT L3)
3 litre
<unit kind=“litre” scale=“ ” multiplier=“ ” exponent=“1”/>
OR volume (predefined in L1/L2 NOT L3)

compartment
<compartment spatialDimensions=“3” units=“ ” />
Assumes units according to the spatialDimensions attribute
L1/L2 predefined L3 from attribute on model
length (m) lengthUnits
area (m2) areaUnits
volume (l) volumeUnits
In L3 possible for the unit to be undeclared

Appropriate values for substanceUnits attribute
dimensionless substance (predefined in L1/L2 NOT L3)
mole
<unit kind=“mole” exponent=“1”/>
item
<unit kind=“item” exponent=“1”/>
kilogram
<unit kind=“kilogram” exponent=“1”/>
gram
<unit kind=“gram” exponent=“1”/>
avogadro (L3 ONLY)
<unit kind=“avogadro” exponent=“1”/>
species

<species substanceUnits=“ ” />
L1/L2 predefined L3 from attribute on model
substance (mol) substanceUnits
In L3 possible for the substanceUnit to be undeclared
species
Assumes substance units

<species substanceUnits=“mole” hasOnlySubstanceUnits=“true” />
species
Units of the species are those of substance ONLY

<species substanceUnits=“mole” hasOnlySubstanceUnits=“false”
compartment=“c” />
species
Substance units are as given for the species
BUT
Species has units of concentration
[ ] [ ]
[ ]tcompartmencontainingof
speciesofunits
units
nitssubstanceU
=

model
<model lengthUnits=“” areaUnits=“” volumeUnits=“”
substanceUnits=“”
extentUnits=“”
timeUnits=“” >
L3 ONLY

checkConsistency()
Warning Line 25 Column 88: (SBML Validation Rule #20608) The value of a
<species>'s 'units' attribute is restricted. Reference: L3V1 Section 4.6.5 The
value of a <species>'s 'substanceUnits' attribute can only be one of the
following: 'substance', 'mole', 'item', 'gram', 'kilogram', 'dimensionless',
'avogadro' or the identifier of a <unitDefinition> derived from 'mole' (with
an 'exponent' of '1'), 'item' (with an 'exponent' of '1'), 'gram' (with an
'exponent' of '1'), 'kilogram' (with an 'exponent' of '1'), 'avogadro' (with an
'exponent' of '1') or 'dimensionless'.

UnitDefinition::isVariantOfArea()
UnitDefinition::isVariantOfLength()
UnitDefinition::isVariantOfMass()
UnitDefinition::isVariantOfVolume()
UnitDefinition::isVariantOfDimensionless()
UnitDefinition::isVariantOfSubstance()

Checking units of expressions
<assignmentRule variable=“S”>
<math xmlns=“http://www.w3.org/1998/Math/MathML”
<apply>
<times/>
<ci> T </ci>
<ci> K </ci>
</apply>
</math>
</assignmentRule>

KT
dt
dS
*= rateRule
assignmentRule/initialAssignment/
eventAssignment
KTS *=
KT *
time
extent
=





kineticLaw
[ ] KT *time = delay
[ ] KT *essdimensionl = priority

If all units have been declared
- know the units of S, T and K
- can work out the units of ‘T * K’ (RHS)
- can verify that the units of LHS match the units of RHS

BUT

If all units have been declared
- know the units of S, T and K
- can we work out the units of RHS
- can verify that the units of LHS match the units of RHS

Is the math correct ????
divide
T
Abstract Syntax Tree
T ÷ K
K
Are the number of arguments correct ?

Class of function Number of arguments Example
unary one sin
binary two divide
nary zero or more times
at_least_two two or more equals
special can vary piecewise
minus
root
log

checkConsistency()
Error Line 5 Column 12: (SBML Validation Rule #10218) A MathML operator
must be supplied the number of arguments appropriate for that operator.
Reference: L3V1 Section 3.4.1 The formula 'piecewise()' in the math
element of the Constraint has an inappropriate number of arguments.

eq
T
T == K
K
Are the types of arguments correct ?
For example:
3.4 == false
3.4 && false
sin(false)
are all INVALID

Class of function Type of arguments Example
numeric numeric divide
logical boolean and
special either logical or numeric but must all be same type equals
piecewise conditional must be boolean
optional returns must be same type

checkConsistency()
Error Line 12 Column 15: (SBML Validation Rule #10212) The types of
values within <piecewise> operators must all be consistent: the set of
expressions that make up the first arguments of the <piece> and
<otherwise> operators within the same <piecewise> operator should all
return values of the same type. Reference: L3V1 Section 3.4.9 The
piecewise formula in the math element of the AlgebraicRule returns
arguments which have different value types from the first element 'p * 6'.

if not UNIT
checking will
fail

plus
T
T + K
K
units of arguments MUST be IDENTICAL
are the units appropriate
for the math ??

times
T
T * K
K
no restrictions
for the math ??

sin
T
sin(T) units of argument MUST be DIMENSIONLESS
for the math ??

checkConsistency()
Warning Line 16 Column 23: (SBML Validation Rule #10501) The units of
the expressions used as arguments to a function call are expected to match
the units expected for the arguments of that function. The formula 'p + p1'
in the math element of the AlgebraicRule can only act on variables with
the same units.

math number of arguments
math types of arguments
units of arguments

times
T
T * K
K
Units of this node:
units of T times the units of K

times
T
T * K
K
Units of this node:
units of T times the units of K
creates a UnitDefinition that represents the
units of the node
and caches it to reduce computation time

plus
T
T + K
K
Units of this node:
units of T

plus
T
T + K
K
Units of this node:
units of TWARNING: if units
of T are not
identical to the
units of K this
expression is illegal

plus
T
T + K
K
Units of this node:
units of T
OR if T has no units declared
node will have units of K
records whether an expression has
undeclared units and whether they
can be ignored

Class of node Units returned Example
dimensionless dimensionless sin/and
same units identical to the arguments plus/abs
calculated units must be calculated for the expression times
divide
power
root
determined units will be returned by certain arguments piecewise
delay
numbers undeclared (L3 can declare them)
variables units appropriate to the component represented id of
species

plus
T Kroot
2 K
piece
wise
S Ktimes
T S
geq
G 2
floor
T

Checking units of the model
loops through whole model
creates data structure for each element
Member in structure Stores information about
UnitReferenceId identifier that relates the data structure to the SBML
component
ContainsUndeclaredUnits records whether an expression contained variables or
numbers for which there were no units available
true if it does
CanIgnoreUndeclaredUnits determines whether the unit of an expression with
undeclared units is accurate or not
true if the units are accurate
UnitDefinition a unitDefinition element that represents the units
PerTimeUnitDefinition UnitDefinition with the addition of a per time unit

tests the units for each expression by retrieving the
unitDefinitions for the RHS and the LHS and checking
that they are equivalent/identical
remove scale from any units (change to multiplier)
2 * 102 m == 20 * 101 m == 200 m
<unit kind=“metre” scale=“0” multiplier=“200” exponent=“1”/
Identical BUT do not want to compare two figures

tests the units for each expression by retrieving the
unitDefinitions for the RHS and the LHS and checking
that they are equivalent/identical
convert both unitDefinitions to base SI
loop thru the units and check they are equivalent/identical
remove scale from any units (change to multiplier)
simplify and order the units alphabetically

LHS RHS
<listOfUnits>
<unit kind=“newton” exponent=“1”/>
<unit kind=“metre” exponent=“1”/>
<listOfUnits>
<unit kind=“watt” exponent=“1”/>
<unit kind=“second” exponent=“1”/>
NOTE: multiplier = 1 scale = 0 for all units here

LHS RHS
<listOfUnits>
<unit kind=“newton” exponent=“1”/>
<listOfUnits>
<unit kind=“watt”
exponent=“1”/>
<unit kind=“second”
exponent=“1”/>
LHS

LHS RHS
<listOfUnits>
<unit kind=“second” exponent=“-2”/>
<listOfUnits>
exponent=“1”/>
exponent=“1”/>
Convert to base SI

LHS RHS
<listOfUnits>
<listOfUnits>
exponent=“1”/>
exponent=“1”/>
Simplify

LHS RHS
<listOfUnits>
<listOfUnits>
exponent=“1”/>
exponent=“1”/>
Reorder based on kind

LHS RHS
<listOfUnits>
<unit kind=“kilogram”
exponent=“1”/>
<unit kind=“metre”
exponent=“2”/>
exponent=“-2”/>
<listOfUnits>
<unit kind=“watt” exponent=“1”/>
RHS

LHS RHS
<listOfUnits>
exponent=“1”/>
exponent=“2”/>
exponent=“-2”/>
<listOfUnits>
Convert to base SI

LHS RHS
<listOfUnits>
exponent=“1”/>
exponent=“2”/>
exponent=“-2”/>
<listOfUnits>
Simplify

LHS RHS
<listOfUnits>
exponent=“1”/>
exponent=“2”/>
exponent=“-2”/>
<listOfUnits>
Reorder based on kind

LHS RHS
<listOfUnits>
<listOfUnits>
NOTE: multiplier = 1 scale = 0 for all units here
Are the number of units the same ?
For each position is kind == kind
exponent == exponent
multiplier == multiplier
Note: scale == scale since it was ‘removed’

LHS RHS
<listOfUnits>
<listOfUnits>
identical

LHS RHS
<listOfUnits>
exponent=“1”
multiplier=“1000”/>
<listOfUnits>
exponent=“1”
x km = y m
1 km = 1000 m
Difference is a numerical ‘scaling factor’

LHS RHS
<listOfUnits>
exponent=“1”
<listOfUnits>
exponent=“1”
x km = y m
1 km = 1000 m
kind == kind
exponent == exponent
multiplier != multiplier

LHS RHS
<listOfUnits>
exponent=“1”
<listOfUnits>
exponent=“1”
x km = y m
1 km = 1000 m
equivalent

KT
dt
dS
*= rateRule
eventAssignment
KTS *=
KT *
time
extent
=





kineticLaw
equivalent

KT
dt
dS
*= rateRule
eventAssignment
KTS *=
KT *
time
extent
=





kineticLaw
identical

checkConsistency()
Error Line 16 Column 25: (SBML Validation Rule #10513) When the
'variable' in an <assignmentRule> refers to a <parameter>, the units of the
rule's right-hand side are expected to be consistent with the units declared
for that parameter. Reference: L2V3 Section 4.11.3 Expected units are
metre (exponent = 1, multiplier = 1, scale = 0) but the units returned by the
<assignmentRule>'s <math> expression are metre (exponent = 1.33333,
multiplier = 1, scale = 0).

Lessons learnt
only allow base SI units
use only multiplier NOT multiplier and scale
enforce units on everything including numbers
If unit
consistency is
desired

Checking units in libSBML

Recomendados

Recomendados

Mais conteúdo relacionado

Semelhante a Checking units in libSBML

Semelhante a Checking units in libSBML (20)

Último

Último (20)

Checking units in libSBML