SBML.org — the global portal for all things SBML

Modularity In Core

Nicolas Le Novère, 3 October 2007

Here I describe possible modifications of the core that would allow modularity and aggregation. IMHO, this is a prerequisite to any effort toward model composition. The purpose here, is not to allow the construction of models from other models or parts of models, but to build a model in a modular fashion straight from the beginning. Some advantages of moving SBML to a modular structure are (not ranked by importance):

  • Possibility of using variables with different units in different contexts. Currently, the unit conversion is embedded in the "stoichiometry". Most people are confused and think this attribute is equivalent to biochemical stoichiometry. As a result, they do not correct for the unit, forgetting that whatever unit a species is declared with, a kineticLaw always produces the default substance per time.
  • Easier maintenance of large models. The possibility to group conceptually realted compartment, species, reactions etc. is very handy when dealing with very large models.
  • Enhanced compatibility with CellML.
  • Providing an elegant ground to model composition. Whatever you guys are developing, the existence of identified modules in every SBML file makes the work easier. I suspect it will make the work easier for other extensions (layout, multi-component etc.).

Note: Following discussion with SH, it seems that using Xinclude would untie this issue to the issue of 1 SBML document = multiple files, and does not relate to modularity. I still personaly believe that we should import only modules from other files, rather than any random bit of SBML. Much cleaner. If we want to make one species importable, we create a module with only this species. Therefore each bit of SBML should always be included in an sbml element, that could in addition store the signature, timestamps etc. An SBML element would contain a listOfModules.

Description and UML

The main proposed change is that an SBML file is made up of one or more modules. A module is basically the equivalent of a model of Level 2, with an attribute id that is no longer optional. The element model itself is now inherited from module, with an additional list of mappings. Important: the model does NOT contain the modules. They are at the same level. There is no nesting of modules.

Note: Andrew advocates that we do not differentiate between the model and the modules but instead allow any modules to contain a listOfMappings. As a consequence, an SBML document would only be made up of a listOfModules.

A mapping states that two variables of the same type, declared in two different modules, are representing the same entity. A mapping can link two compartments, two species, two parameters or two reactions. There can be many mappings between the same two modules. A given variable can participate to any number of mappings, but there can be only one mapping linking to variables.

SH: The unit conversion has to be made explicit.

NLN: could-we put this in the mappings? Could-we define a unit for the mapping, independent of the units of the two variables.

Simple Example

The following model is made up of 3 modules: 1 model and 2 declared as such. The model A describes the phosphorylation of the MAP kinase kinase and the module B describes the phosphorylation of the MAP kinase, catalyed by the phosphorylated form of MAP kinase kinase. One SBML file lists all the others, and contains the model:

<?xml version="1.0" encoding="UTF-8"?>
<sbml xmlns="http://www.sbml.org/sbml/level3" level="3" version="1">
  <model>
    <listOfMappings>
      <mapping> <!-- THIS MAPPING SAYS THAT THE VARIABLE A.MEKPP and B.MAPKKPP REPRESENT THE SAME ENTITY -->
        <variable module="A" variable="MEKPP" />
        <variable module="B" variable="MAPKKPP" />
      </mapping>
    </listOfMappings>
    <listOfCompartments><!-- THESE COMPARTMENTS WILL BE KNOWN BY EVERYONE -->
      <compartment id="cell" size="1"/>
    </listOfCompartments>
  </model>
  <listOfModules>
    <module id="A">
      <listOfSpecies>  <!-- NOTE THAT UNITS ARE NOT DEFINED. SBML BUILT-IN UNITS ARE USED -->
        <species id="MEK" compartment="cell" initialConcentration="1e-5" />
        <species id="MEKPP" compartment="cell" initialConcentration="1e-5" />
      </listOfSpecies>
      <listOfParameters>
        <parameter id="Vmax" />
        <parameter id="Km" />
      </listOfParameters>
      <listOfReactions>
        <listOfReactants>
          <speciesReference species="MEK"/> 
        </listOfReactants>
        <listOfProducts>
          <speciesReference species="MEKPP" />
        </listOfProducts>
        <kineticLaw>
<!--         ... Vmax * MEK /(Km + MEK) * cell      -->
        </kineticLaw>
      </listOfReactions>
    </module>
    <module id="B">
      <listOfUnitDefinitions> <!-- DEFAULT SUBSTANCE UNIT IS REDEFINED TO MICROMOLE -->
        <unitDefinition id="substance" name="micromole">
          <listOfUnits>
            <unit kind="mole" scale="-6" />
          </listOfUnits>
        </unitDefinition>
      </listOfUnitDefinitions>
      <listOfSpecies>
        <species id="MAPKKPP" compartment="cell" initialConcentration="0" /> <!-- THIS INITIALCONCENTRATION OVERIDE THE ONE DECLARED IN MODULE A -->
        <species id="MAPK" compartment="cell" initialConcentration="1" />
        <species id="MAPKPP" compartment="cell" initialConcentration="0" />
      </listOfSpecies>
      <listOfParameters>
        <parameter id="kcat" />
        <parameter id="Km" />
      </listOfParameters>
      <listOfReactions>
        <listOfReactants>
          <speciesReference species="MAPK" />
        </listOfReactants>
        <listOfProducts>
          <speciesReference species="MAPKPP" />
        </listOfProducts>
        <listOfModifiers>
          <speciesReference species="MAKKPP" />
        </listOfModifiers>
        <kineticLaw>
<!--             ... kcat * MAKKPP * MAPK /(Km + MAPK) * cell     -->
        </kineticLaw>
      </listOfReactions>
    </module>
  </listOfModules>
</sbml>

2nd Example

Where a module contains a reaction depending on a rule and an event from another module:

<?xml version="1.0" encoding="UTF-8"?>
<sbml name="MyModel" xmlns="http://www.sbml.org/sbml/level3">
  <model>
    <listOfMappings>
      <mapping>
        <variable module="Ca" variable="cell" />
        <variable module="KII" variable="cell" />
      </mapping>
      <mapping>
        <variable module="Ca" variable="boundCaM" />
        <variable module="KII" variable="CaCaM" />
      </mapping>
    </listOfMappings>
  </model>
  <listOfModules>
    <module id="Ca">
      <listOfCompartments>
        <compartment id="cell" size="1"/>
      </listOfCompartments>
      <listOfSpecies>
        <species id="freeCaM" initialConcentration="1" compartment="cell">
        <species id="boundCaM" initialConcentration="0" compartment="cell">
      </listOfSpecies>
      <listOfParameters>
        <parameter id="ca" value="0" />
        <parameter id="Kd" value="1" />
        <parameter id="T" value="10" />
      </listOfParameters>      
      <listOfRules>
        <assignmentRule variable="boundCaM">
        <math xmlns="http://www.w3.org/1998/Math/MathML">
          <apply>
            <times/>
            <ci> freeCaM </ci>
            <apply>
              <power>
              <apply>
                <divide/>
                <ci> ca </ci>
                <apply>
                  <plus/>
                  <ci> Kd </ci>
                  <ci> ca </ci>
                </apply>
              </apply>
              <cn type="integer"> 4 </cn>
            </apply>
          </apply>
        </math>
        </assignmentRule>
      </listOfRules>
      <listOfEvents>
        <event id="caEntry">
          <trigger>
            <math xmlns="http://www.w3.org/1998/Math/MathML">
            <apply>
              <gt/>
              <csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/time"> time </csymbol>
              <ci> T </ci>
            </apply>
          </math>
        </trigger>
        <listOfEventAssignments>
          <eventAssignment variable="ca">
            <math xmlns="http://www.w3.org/1998/Math/MathML">
              <cn> 1 </cn>
            </math>
          </eventAssignment>
        </listOfEventAssignments>
        </event>
      </listOfEvents>
    </module>
    <module id="KII">
      <listOfCompartments>
        <compartment id="cell" size="1"/>
      </listOfCompartments>
      <listOfSpecies>
        <species id="CaCaM" initialConcentration="0" compartment="cell">
        <species id="CaMKII" initialConcentration="1" compartment="cell">
        <species id="CaCaM_CaMKII" initialConcentration="0" compartment="cell">
      </listOfSpecies>
      <listOfReactions>
        <reaction id="bindingCaM">
          <listOfReactants>
            <speciesReference species="CaMKII">
            <speciesReference species="CaCaM">
          </listOfReactants>
          <listOfProducts>
            <speciesReference species="CaCaM_CaMKII">
          </listOfProducts>
          <kineticLaw>
            <math xmlns="http://www.w3.org/1998/Math/MathML">
              <apply>
                <times/>
                <ci> CaCaM </ci>
                <ci> CaMKII </ci>
                <ci> kon </ci>
                <ci> cell </ci>
              </apply>
            </math>
            <listOfParameters>
              <parameter id="kon" value="1"/>
            </listOfParameters>
          </kineticLaw>
        </reaction>
      </listOfReactions>
    </module>
  </listOfModules>
</sbml>

Retrieved from "http://sbml.org/Events/Other_Events/SBML_Composition_Workshop_2007/Modularity_In_Core"

This page was last modified 02:37, 27 December 2007.



Please use our issue tracking system for any questions or suggestions about this website. This page was last modified 02:37, 27 December 2007.