Correct the use of units and unit definitions

[draeger]

In input files, reactions are usually given in millimole per gram dry weight per hour (mmol / gDW / h).

The given unit needs to be decomposed into its parts:

• The extent unit mmol / gDW that characterizes the extent of all reactions per time unit.
• The substance unit mmol = 10^-3 · mol for all reacting species and their hasOnlySubstanceUnits attribute should be set to false, so that species implicitly inherit the 'concentration unit' mmol / gDW.
• The size unit gDW for all compartments that are the containers, in which substances reside.
• The time unit hour = 3600 · s.

Declare the default units on the model for each unit category: extentUnit, substanceUnit, timeUnit.

We cannot set any of the size units on the model though, because gDW is neither a volume, nor area, nor length unit. Hence, all compartments must be individually declared to be in gDW.

It is important that the given unit is programmatically decomposed rather than predefining a certain unit. In case that an input model is given with a deviating unit, say nanomole per gDW per day, this must be analogously decomposed rather than being replaced by the default unit.

[draeger]

At the moment, it is not entirely clear what the correct units in COBRA models would be. This issue is being discussed amongst the SBML editors. As an intermediate solution, ModelPolisher version 1.2 defines compartment units as dimensionless if these are undefined and uses mmol/gDW as substanceUnit for all species, even though this is currently not supported by the libSBML validator.

[matthiaskoenig]

Hi Andreas,
if there is a solution for this please let me know. I mainly run in the same issue and unclear how to handle this.
M

[draeger]

@matthiaskoenig this is still not fully solved. The upcoming HARMONY meeting could be a good occasion to discuss this topic within a broader circle.

[mephenor]

Are there any news with regard to this issue?

[draeger]

@matthiaskoenig it seems, we should set this on our agenda for discussion at HARMONY 2020.

[matthiaskoenig]

@draeger
I am not sure if this is resolved in libsbml-experimental. I will check what is going on there with some examples (I also want to have the exact validation rule with the error message which fails). I can do this on the weekend, and will bring this up during HARMONY if there is no solution at the moment.

[Schmoho]

The most important issue I see with this is that JSBML - and if I'm not mistaken SBML itself - does not have a notion of a growth unit (definition).

That is, any deviating units, e.g. "nmol / gDW / sec" would need to be identified some other way.

We could do some best effort parsing here, but right now I cannot see a "correct" solution to the issue of identifying and decomposing growth units.

[draeger]

The genome-scale metabolic model of Corynebacterium glutamicum could serve as an example model that libSBML validates correctly. It uses multiple unit definitions and also declares the sizes of compartments and their default units.

[Schmoho]

For reference, this is the relevant data from said bacterium:

<listOfUnitDefinitions>
      <unitDefinition id="hour" metaid="meta_hour" name="hour">
        <annotation>
          <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:bqbiol="http://biomodels.net/biology-qualifiers/">
            <rdf:Description rdf:about="#meta_hour">
              <bqbiol:is>
                <rdf:Bag>
                  <rdf:li rdf:resource="https://identifiers.org/UO:0000032" />
                </rdf:Bag>
              </bqbiol:is>
            </rdf:Description>
          </rdf:RDF>
        </annotation>
        <listOfUnits>
          <unit exponent="1" kind="second" multiplier="3600" scale="0" />
        </listOfUnits>
      </unitDefinition>
      <unitDefinition id="fL" metaid="meta_fL" name="femto litres">
        <annotation>
          <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:bqbiol="http://biomodels.net/biology-qualifiers/">
            <rdf:Description rdf:about="#meta_fL">
              <bqbiol:is>
                <rdf:Bag>
                  <rdf:li rdf:resource="https://identifiers.org/UO:0000104" />
                </rdf:Bag>
              </bqbiol:is>
            </rdf:Description>
          </rdf:RDF>
        </annotation>
        <listOfUnits>
          <unit exponent="1" kind="litre" multiplier="1" scale="-3" />
        </listOfUnits>
      </unitDefinition>
      <unitDefinition id="mmol_per_gDW" name="millimoles per gram dry weight">
        <listOfUnits>
          <unit exponent="1" kind="mole" multiplier="1" scale="-3" />
          <unit exponent="-1" kind="gram" multiplier="1" scale="0" />
        </listOfUnits>
      </unitDefinition>
      <unitDefinition id="mmol_per_gDW_per_hr" name="millimoles per gram dry weight per hour">
        <listOfUnits>
          <unit exponent="1" kind="mole" multiplier="1" scale="-3" />
          <unit exponent="-1" kind="gram" multiplier="1" scale="0" />
          <unit exponent="-1" kind="second" multiplier="3600" scale="0" />
        </listOfUnits>
      </unitDefinition>
    </listOfUnitDefinitions>
    <listOfCompartments>
      <compartment size="NaN" spatialDimensions="3" id="c" name="cytosol" constant="true"/>
      <compartment size="NaN" spatialDimensions="3" id="p" name="periplasm" constant="true"/>
      <compartment size="NaN" spatialDimensions="3" id="e" name="extracellular space" constant="true"/>
    </listOfCompartments>

[draeger]

Also the declaration of default units in the model:

extentUnits="mmol_per_gDW" substanceUnits="mmol_per_gDW" timeUnits="hour" volumeUnits="fL"