Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Checking units in libSBML

231 views

Published on

Presentation on how units are encoded in SBML and how libSBML applies unit consistency checking. Given by Sarah Keating at a BioModels Team meeting, EBI June 5th 2013

Published in: Technology, Business
  • Be the first to comment

  • Be the first to like this

Checking units in libSBML

  1. 1. Units in SBMLand how libSBML checks themSarah Keating
  2. 2. Associate units with a variable• Use attributes in the SBML<compartment units=“ ” /><species substanceUnits=“ ” /><parameter units=“ ” />
  3. 3. Associate units with a variable• Values that can be usedampere farad joule lux radian voltavogadro gram katal metre second wattbecquerel gray kelvin mole siemens webercandela henry kilogram newton sievertcoulomb hertz litre ohm steradiandimensionless item lumen pascal tesla
  4. 4. Associate units with a variable• Use attributes in the SBML<compartment units=“litre” /><species substanceUnits=“mole” /><parameter units=“second” />
  5. 5. Associate units with a variable• Values that can be usedampere farad joule lux radian voltavogadro gram katal metre second wattbecquerel gray kelvin mole siemens webercandela henry kilogram newton sievertcoulomb hertz litre ohm steradiandimensionless item lumen pascal tesla
  6. 6. Associate units with a variable• Values that can be usedampere farad joule lux radian voltavogadro gram katal metre second wattbecquerel gray kelvin mole siemens webercandela henry kilogram newton sievertcoulomb hertz litre ohm steradiandimensionless item lumen pascal tesla
  7. 7. Associate units with a variable• Values that can be usedampere farad joule lux radian voltavogadro gram katal metre second wattbecquerel gray kelvin mole siemens webercandela henry kilogram newton sievertcoulomb hertz litre ohm steradiandimensionless item lumen pascal tesla
  8. 8. • Not one of the base unitsAssociate units with a variable
  9. 9. • Not one of the base unitsAssociate units with a variableUnitDefinitionsid of unitDefinition used as unit attribute
  10. 10. Associate units with a variable<unitDefinition id=“my_metre”><listOfUnits><unit kind=“metre” scale=“0” multiplier=“1” exponent=“1”/></listOfUnits></unitDefinition>1 id = (multiplier * 10scale * kind)exponent1 my_metre = (1 * 100 * metre)1 = 1 m• Not one of the base units
  11. 11. Associate units with a variable<unitDefinition id=“milligram”><listOfUnits><unit kind=“gram” scale=“-3” multiplier=“1” exponent=“1”/></listOfUnits></unitDefinition>1 id = (multiplier * 10scale * kind)exponent1 milligram = (1 * 10-3 * gram)1 = 0.001 g• Not one of the base units
  12. 12. Associate units with a variable<unitDefinition id=“minute”><listOfUnits><unit kind=“second” scale=“0” multiplier=“60” exponent=“1”/></listOfUnits></unitDefinition>1 id = (multiplier * 10scale * kind)exponent1 minute= (60 * 100 * second)1 = 60 s• Not one of the base units
  13. 13. Associate units with a variable<unitDefinition id=“metre_squared”><listOfUnits><unit kind=“metre” scale=“0” multiplier=“1” exponent=“2”/></listOfUnits></unitDefinition>1 id = (multiplier * 10scale * kind)exponent1 metre_squared= (1* 100 * metre)2 = 1 m2• Not one of the base units
  14. 14. Associate units with a variable<unitDefinition id=“minute_squared”><listOfUnits><unit kind=“second” scale=“0” multiplier=“60” exponent=“2”/></listOfUnits></unitDefinition>1 id = (multiplier * 10scale * kind)exponent1 minute2= (60* 100 * second)2 = (60 s)2 =3600 s2• Not one of the base units
  15. 15. Associate units with a variable<compartment units=“metre_squared” /><species substanceUnits=“milligram” /><parameter units=“minute” />• Not one of the base units
  16. 16. Associate units with a variable<unitDefinition id=“u0”><listOfUnits><unit kind=“metre” scale=“0” multiplier=“1” exponent=“2”/><unit kind=“second” scale=“0” multiplier=“1” exponent=“-1”/></listOfUnits></unitDefinition>1 id = (m1 * 10s1 * kind1)e1 * (m2 * 10s2 * kind2)e21 u0 = (1* 100 * metre)2 * (1* 100 * second)-1 = 1 m2s-1• Combination of base units
  17. 17. Checking units of variablescompartmentSpatialDimensionsAppropriate values for units attribute0 dimensionless1 metreOR id of unitDefinition with<unit kind=“metre” scale=“ ” multiplier=“ ” exponent=“1”/>OR length (predefined in L1/L2 NOT L3)2 id of unitDefinition with<unit kind=“metre” scale=“ ” multiplier=“ ” exponent=“2”/>OR area (predefined in L1/L2 NOT L3)3 litreOR id of unitDefinition with<unit kind=“litre” scale=“ ” multiplier=“ ” exponent=“1”/>OR id of unitDefinition with<unit kind=“metre” scale=“ ” multiplier=“ ” exponent=“3”/>OR volume (predefined in L1/L2 NOT L3)
  18. 18. Checking units of variablescompartment<compartment spatialDimensions=“3” units=“ ” />Assumes units according to the spatialDimensions attributeL1/L2 predefined L3 from attribute on modellength (m) lengthUnitsarea (m2) areaUnitsvolume (l) volumeUnitsIn L3 possible for the unit to be undeclared
  19. 19. Checking units of variablesAppropriate values for substanceUnits attributedimensionless substance (predefined in L1/L2 NOT L3)moleOR id of unitDefinition with<unit kind=“mole” exponent=“1”/>itemOR id of unitDefinition with<unit kind=“item” exponent=“1”/>kilogramOR id of unitDefinition with<unit kind=“kilogram” exponent=“1”/>gramOR id of unitDefinition with<unit kind=“gram” exponent=“1”/>avogadro (L3 ONLY)OR id of unitDefinition with<unit kind=“avogadro” exponent=“1”/>species
  20. 20. Checking units of variables<species substanceUnits=“ ” />L1/L2 predefined L3 from attribute on modelsubstance (mol) substanceUnitsIn L3 possible for the substanceUnit to be undeclaredspeciesAssumes substance units
  21. 21. Checking units of variables<species substanceUnits=“mole” hasOnlySubstanceUnits=“true” />speciesUnits of the species are those of substance ONLY
  22. 22. Checking units of variables<species substanceUnits=“mole” hasOnlySubstanceUnits=“false”compartment=“c” />speciesSubstance units are as given for the speciesBUTSpecies has units of concentration[ ] [ ][ ]tcompartmencontainingofspeciesofunitsunitsnitssubstanceU=
  23. 23. Checking units of variablesmodel<model lengthUnits=“” areaUnits=“” volumeUnits=“”substanceUnits=“”extentUnits=“”timeUnits=“” >L3 ONLY
  24. 24. Checking units of variablescheckConsistency()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 Thevalue of a <species>s substanceUnits attribute can only be one of thefollowing: substance, mole, item, gram, kilogram, dimensionless,avogadro or the identifier of a <unitDefinition> derived from mole (withan exponent of 1), item (with an exponent of 1), gram (with anexponent of 1), kilogram (with an exponent of 1), avogadro (with anexponent of 1) or dimensionless.
  25. 25. Checking units of variablesUnitDefinition::isVariantOfArea()UnitDefinition::isVariantOfLength()UnitDefinition::isVariantOfMass()UnitDefinition::isVariantOfVolume()UnitDefinition::isVariantOfDimensionless()UnitDefinition::isVariantOfSubstance()
  26. 26. 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>
  27. 27. Checking units of expressionsKTdtdS*= rateRuleassignmentRule/initialAssignment/eventAssignmentKTS *=KT *timeextent=kineticLaw[ ] KT *time = delay[ ] KT *essdimensionl = priority
  28. 28. Checking units of expressionsIf 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
  29. 29. Checking units of expressionsBUT
  30. 30. Checking units of expressionsIf 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
  31. 31. Checking units of expressionsIs the math correct ????divideTAbstract Syntax TreeT ÷ KKAre the number of arguments correct ?
  32. 32. Checking units of expressionsIs the math correct ????Are the number of arguments correct ?Class of function Number of arguments Exampleunary one sinbinary two dividenary zero or more timesat_least_two two or more equalsspecial can vary piecewiseminusrootlog
  33. 33. checkConsistency()Error Line 5 Column 12: (SBML Validation Rule #10218) A MathML operatormust be supplied the number of arguments appropriate for that operator.Reference: L3V1 Section 3.4.1 The formula piecewise() in the mathelement of the Constraint has an inappropriate number of arguments.Checking units of expressions
  34. 34. Checking units of expressionsIs the math correct ????eqTT == KKAre the types of arguments correct ?For example:3.4 == false3.4 && falsesin(false)are all INVALID
  35. 35. Checking units of expressionsIs the math correct ????Are the types of arguments correct ?Class of function Type of arguments Examplenumeric numeric dividelogical boolean andspecial either logical or numeric but must all be same type equalspiecewise conditional must be booleanoptional returns must be same type
  36. 36. checkConsistency()Error Line 12 Column 15: (SBML Validation Rule #10212) The types ofvalues within <piecewise> operators must all be consistent: the set ofexpressions that make up the first arguments of the <piece> and<otherwise> operators within the same <piecewise> operator should allreturn values of the same type. Reference: L3V1 Section 3.4.9 Thepiecewise formula in the math element of the AlgebraicRule returnsarguments which have different value types from the first element p * 6.Checking units of expressions
  37. 37. Checking units of expressionsIs the math correct ????Are the number of arguments correct ?Are the types of arguments correct ?if not UNITchecking willfail
  38. 38. Checking units of expressionsplusTT + KKunits of arguments MUST be IDENTICALare the units appropriatefor the math ??
  39. 39. Checking units of expressionstimesTT * KKno restrictionsare the units appropriatefor the math ??
  40. 40. Checking units of expressionssinTsin(T) units of argument MUST be DIMENSIONLESSare the units appropriatefor the math ??
  41. 41. checkConsistency()Warning Line 16 Column 23: (SBML Validation Rule #10501) The units ofthe expressions used as arguments to a function call are expected to matchthe units expected for the arguments of that function. The formula p + p1in the math element of the AlgebraicRule can only act on variables withthe same units.Checking units of expressions
  42. 42. Checking units of expressionsmath number of argumentsmath types of argumentsunits of arguments
  43. 43. Checking units of expressionstimesTT * KKUnits of this node:units of T times the units of K
  44. 44. Checking units of expressionstimesTT * KKUnits of this node:units of T times the units of Kcreates a UnitDefinition that represents theunits of the nodeand caches it to reduce computation time
  45. 45. Checking units of expressionsplusTT + KKUnits of this node:units of T
  46. 46. Checking units of expressionsplusTT + KKUnits of this node:units of TWARNING: if unitsof T are notidentical to theunits of K thisexpression is illegal
  47. 47. Checking units of expressionsplusTT + KKUnits of this node:units of TOR if T has no units declarednode will have units of Krecords whether an expression hasundeclared units and whether theycan be ignored
  48. 48. Class of node Units returned Exampledimensionless dimensionless sin/andsame units identical to the arguments plus/abscalculated units must be calculated for the expression timesdividepowerrootdetermined units will be returned by certain arguments piecewisedelaynumbers undeclared (L3 can declare them)variables units appropriate to the component represented id ofspeciesChecking units of expressions
  49. 49. Checking units of expressionsplusT Kroot2 KpiecewiseS KtimesT SgeqG 2floorT
  50. 50. Checking units of the modelloops through whole modelcreates data structure for each elementMember in structure Stores information aboutUnitReferenceId identifier that relates the data structure to the SBMLcomponentContainsUndeclaredUnits records whether an expression contained variables ornumbers for which there were no units availabletrue if it doesCanIgnoreUndeclaredUnits determines whether the unit of an expression withundeclared units is accurate or nottrue if the units are accurateUnitDefinition a unitDefinition element that represents the unitsPerTimeUnitDefinition UnitDefinition with the addition of a per time unit
  51. 51. Checking units of the modeltests the units for each expression by retrieving theunitDefinitions for the RHS and the LHS and checkingthat they are equivalent/identicalremove scale from any units (change to multiplier)2 * 102 m == 20 * 101 m == 200 m<unit kind=“metre” scale=“2” multiplier=“2” exponent=“1”/><unit kind=“metre” scale=“1” multiplier=“20” exponent=“1”/><unit kind=“metre” scale=“0” multiplier=“200” exponent=“1”/Identical BUT do not want to compare two figures
  52. 52. Checking units of the modeltests the units for each expression by retrieving theunitDefinitions for the RHS and the LHS and checkingthat they are equivalent/identicalconvert both unitDefinitions to base SIloop thru the units and check they are equivalent/identicalremove scale from any units (change to multiplier)simplify and order the units alphabetically
  53. 53. Checking units of the modelLHS 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
  54. 54. Checking units of the modelLHS RHS<listOfUnits><unit kind=“newton” exponent=“1”/><unit kind=“metre” exponent=“1”/><listOfUnits><unit kind=“watt”exponent=“1”/><unit kind=“second”exponent=“1”/>LHS
  55. 55. Checking units of the modelLHS RHS<listOfUnits><unit kind=“metre” exponent=“1”/><unit kind=“kilogram” exponent=“1”/><unit kind=“second” exponent=“-2”/><unit kind=“metre” exponent=“1”/><listOfUnits><unit kind=“watt”exponent=“1”/><unit kind=“second”exponent=“1”/>Convert to base SI
  56. 56. Checking units of the modelLHS RHS<listOfUnits><unit kind=“metre” exponent=“2”/><unit kind=“kilogram” exponent=“1”/><unit kind=“second” exponent=“-2”/><listOfUnits><unit kind=“watt”exponent=“1”/><unit kind=“second”exponent=“1”/>Simplify
  57. 57. Checking units of the modelLHS RHS<listOfUnits><unit kind=“kilogram” exponent=“1”/><unit kind=“metre” exponent=“2”/><unit kind=“second” exponent=“-2”/><listOfUnits><unit kind=“watt”exponent=“1”/><unit kind=“second”exponent=“1”/>Reorder based on kind
  58. 58. Checking units of the modelLHS RHS<listOfUnits><unit kind=“kilogram”exponent=“1”/><unit kind=“metre”exponent=“2”/><unit kind=“second”exponent=“-2”/><listOfUnits><unit kind=“watt” exponent=“1”/><unit kind=“second” exponent=“1”/>RHS
  59. 59. Checking units of the modelLHS RHS<listOfUnits><unit kind=“kilogram”exponent=“1”/><unit kind=“metre”exponent=“2”/><unit kind=“second”exponent=“-2”/><listOfUnits><unit kind=“metre” exponent=“2”/><unit kind=“kilogram” exponent=“1”/><unit kind=“second” exponent=“-3”/><unit kind=“second” exponent=“1”/>Convert to base SI
  60. 60. Checking units of the modelLHS RHS<listOfUnits><unit kind=“kilogram”exponent=“1”/><unit kind=“metre”exponent=“2”/><unit kind=“second”exponent=“-2”/><listOfUnits><unit kind=“metre” exponent=“2”/><unit kind=“kilogram” exponent=“1”/><unit kind=“second” exponent=“-2”/>Simplify
  61. 61. Checking units of the modelLHS RHS<listOfUnits><unit kind=“kilogram”exponent=“1”/><unit kind=“metre”exponent=“2”/><unit kind=“second”exponent=“-2”/><listOfUnits><unit kind=“kilogram” exponent=“1”/><unit kind=“metre” exponent=“2”/><unit kind=“second” exponent=“-2”/>Reorder based on kind
  62. 62. Checking units of the modelLHS RHS<listOfUnits><unit kind=“kilogram” exponent=“1”/><unit kind=“metre” exponent=“2”/><unit kind=“second” exponent=“-2”/><listOfUnits><unit kind=“kilogram” exponent=“1”/><unit kind=“metre” exponent=“2”/><unit kind=“second” exponent=“-2”/>NOTE: multiplier = 1 scale = 0 for all units hereAre the number of units the same ?For each position is kind == kindexponent == exponentmultiplier == multiplierNote: scale == scale since it was ‘removed’
  63. 63. Checking units of the modelLHS RHS<listOfUnits><unit kind=“kilogram” exponent=“1”/><unit kind=“metre” exponent=“2”/><unit kind=“second” exponent=“-2”/><listOfUnits><unit kind=“kilogram” exponent=“1”/><unit kind=“metre” exponent=“2”/><unit kind=“second” exponent=“-2”/>identical
  64. 64. Checking units of the modelLHS RHS<listOfUnits><unit kind=“metre”exponent=“1”multiplier=“1000”/><listOfUnits><unit kind=“metre”exponent=“1”multiplier=“1”/>x km = y m1 km = 1000 mDifference is a numerical ‘scaling factor’
  65. 65. Checking units of the modelLHS RHS<listOfUnits><unit kind=“metre”exponent=“1”multiplier=“1000”/><listOfUnits><unit kind=“metre”exponent=“1”multiplier=“1”/>x km = y m1 km = 1000 mkind == kindexponent == exponentmultiplier != multiplier
  66. 66. Checking units of the modelLHS RHS<listOfUnits><unit kind=“metre”exponent=“1”multiplier=“1000”/><listOfUnits><unit kind=“metre”exponent=“1”multiplier=“1”/>x km = y m1 km = 1000 mequivalent
  67. 67. Checking units of expressionsKTdtdS*= rateRuleassignmentRule/initialAssignment/eventAssignmentKTS *=KT *timeextent=kineticLaw[ ] KT *time = delay[ ] KT *essdimensionl = priorityequivalent
  68. 68. Checking units of expressionsKTdtdS*= rateRuleassignmentRule/initialAssignment/eventAssignmentKTS *=KT *timeextent=kineticLaw[ ] KT *time = delay[ ] KT *essdimensionl = priorityidentical
  69. 69. checkConsistency()Error Line 16 Column 25: (SBML Validation Rule #10513) When thevariable in an <assignmentRule> refers to a <parameter>, the units of therules right-hand side are expected to be consistent with the units declaredfor that parameter. Reference: L2V3 Section 4.11.3 Expected units aremetre (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).Checking units of the model
  70. 70. Lessons learntonly allow base SI unitsuse only multiplier NOT multiplier and scaleenforce units on everything including numbersIf unitconsistency isdesired

×