MathSBML Array Support

MathSBML Home Page MathSBML Site Map

Support for arrays in MathSBML is limited and experimental. It is based on Finney A, Gor V, Bornstein B & Mjolsness E, Systems Biology Markup Language (SBML) Level 3 Proposal: Array Features, Nov 3, 2003. it only provides only a partial implementation (and deviates in some places, as specified below) to satisfy the requirements of The Computable Plant Project


Model Builder Support for Arrays

dimensionToSBML
dimensionToSymbolicSBML
foreach
indexToSBML
indexToSymbolicSBML
indicesToSBML
indicesToSymbolicSBML
initialAssignmentRule
matrixToSBML
matrixToSymbolicSBML
variableLink
vectorToSBML
vectorToSymbolicSBML

The model builder allows users to add arrays to Level 2 SBML models. Even though the proposal is for a level 3 enhancement, only Level 2 models with arrays will be generated. To use any array features, the option Arrays -> True must be selected when newModel is invoked. If Arrays -> False then all subsequent array options will be ignored.

By default array information is encapsulated in annotations. This may be turned off by setting ArraysAreAnnotations -> False. Details about setting the appropriate namespace are given at the MathSBML annotations page.

Options for newModel


Option Default Description
Arrays False Must be set to True to allow Arrays.
ArraysAreAnnotations True Determines if array information is to be enclosed in annotation tags.

The following option is used to define a variable as an array. This option is valid for addx or xToSBML, where x is one of compartment, species, parameter, rule, reaction*, event*: (*coming)

ArrayDimensions->{i->{imin,imax}, j->{jmin,jmax}, k->{kmin,kmax},...}
Option Description
i,j,k,... Any valid identifier (SId). The first identifier is the name of the first index, the second is the name of the second index, etc. These variables are local in scope to the array declaration.
imin,imax Minimum and maximum value of specified array dimension.

Example

Define a species x with a single-dimension array with indices going from 5 to 10

Input: setAnnotationPackage["arrays"];
       setAnnotationURL["http://www.foo.com"];
       speciesToSBML[x, compartment -> C, ArrayDimensions -> {foo -> {5,10}}]
Output: <species id="x"  
                 name="x" 
                 compartment="C" 
                 boundaryCondition="false" 
                 constant="false"
                 substanceUnits="substance" 
                 hasOnlySubstanceUnits="false">
          <annotation xmlns:arrays="http://www.foo.com">
           <listOfDimensions>
            <dimension id="foo" lowerLimit="1" upperLimit="5"/>
           </listOfDimensions>
          </annotation>
        </species>

To define a parameter x as a 5 x 6 x 10 array with indices starting at zero:

Input: parameterToSBML[x, ArrayDimensions -> {foo -> {0, 4}, 
                                              moo -> {0, 5}, 
                                              goo -> {0, 9}}]

Output: <parameter id="x" name="x"">
          <annotation xmlns:arrays="http://www.foo.com">
           <listOfDimensions>
            <dimension id="foo" lowerLimit="0" upperLimit="4"/>
            <dimension id="moo" lowerLimit="0" upperLimit="5"/>
            <dimension id="goo" lowerLimit="0" upperLimit="9"/>
           </listOfDimensions>
          </annotation>
         </parameter>

foreach

Parameters can be associated with compartments using the foreach option:

Input:  newModel[Arrays -> True,id->"ArrayExample", name->"Example of foreach option"];
        setAnnotationPackage["foo"];
        setAnnotationURL["http://www.myfoo.com"];
        addCompartment[Q, ArrayDimensions -> {i -> {1, 100}}];
        addParameter[Viscosity, foreach -> Q];
        createModel[]

Output: <?xml version="1.0" encoding="UTF-8"?>
        <!-- Generated 22-September-2004 16:50:11.645986 -->
        <!-- Generated by MathSBML 2.4.0 (20-September-2004) -->
        <sbml xmlns="http://www.sbml.org/sbml/level2" level="2" version="1">
         <model id="ArrayExample" name="Example of forEach Option">
          <listOfCompartments>
           <compartment id="Q" name="Q" spatialDimensions="3" units="volume">
            <annotation xmlns:foo="http://www.myfoo.com">
             <listOfDimensions>
              <dimension id="i" lowerLimit="1" upperLimit="100"/>
             </listOfDimensions>
            </annotation>
           </compartment>
          </listOfCompartments>
          <listOfParameters>
           <parameter id="Viscosity" name="Viscosity" foreach="Q"/>
          </listOfParameters>
         </model>
        </sbml>


variableLink

The variableLink field for rules is used as in the following example, which defines the array of rate rules (d/dt)X[i,k]=Z[i+k]

Input: ruleToSBML[type -> "rateRule",  variable -> X, 
        variableLink -> {X -> {i, k}, Z -> {i}}, 
        ArrayDimensions -> {i -> {1, 5}}, math -> Z[[i + k]]]

Output: <rateRule>
         <annotation xmlns:foo="http://www.myfoo.com">
          <listOfDimensions>
           <dimension id="i" lowerLimit="1" upperLimit="5"/>
          </listOfDimensions>
         </annotation>
         <variableLink object="X">
          <listOfIndices>
           <math xmlns="http://www.w3.org/1998/Math/MathML">
            <ci>i</ci>
           </math>
           <math xmlns="http://www.w3.org/1998/Math/MathML">
            <ci>k</ci>
           </math>
          </listOfIndices>
         </variableLink>
         <variableLink object="Z">
          <listOfIndices>
           <math xmlns="http://www.w3.org/1998/Math/MathML">
            <ci>i</ci>
           </math>
          </listOfIndices>
         </variableLink>
         <math xmlns="http://www.w3.org/1998/Math/MathML">
          <apply>
           <ci>selector</ci>
           <ci>Z</ci>
           <apply>
            <plus/>
            <ci>i</ci>
            <ci>k</ci>
           </apply>
          </apply>
         </math>
        </rateRule>


initialAssignmentRule

A special rule type initialAssignmentRule is used to assign data values to an array variable.

Input:  ruleToSBML[type -> "initialAssignmentRule", 
        variable -> u,
        data -> {{2, 4, 6}, {3, 6, 9}}]
Output: <initialAssignmentRule variable="u">
         <math xmlns="http://www.w3.org/1998/Math/MathML">
          <matrix>
           <matrixrow>
            <cn>2</cn>
            <cn>4</cn>
            <cn>6</cn>
           </matrixrow>
           <matrixrow>
            <cn>3</cn>
            <cn>6</cn>
            <cn>9</cn>
           </matrixrow>
          </matrix>
         </math>
        </initialAssignmentRule>


dimensionToSBML, dimensionToSymbolicSBML

dimensionToSBML[var,min,max] or
dimensionToSBML[var->{min,max}] returns a single dimension:

Input:  dimensionToSBML[i->{5,10}
Output: <dimension id="i" lowerLimit="5" upperLimit="10">

dimensionToSBML[{var1->{min,max},var2->{min2,max2},...}]returns a list of dimensions

Input:  dimensionToSBML[{i->{5,10},j-> {12,99}}]
Output: <listOfDimensions>
         <dimension id="i" lowerLimit="5" upperLimit="10"/>
         <dimension id="j" lowerLimit="12" upperLimit="99"/>
        </listOfDimensions>

MathML expressions are returned if the values are not numeric:

Input:  dimensionToSBML[i-> {10*j,10*j+5}]
Output: <dimension id="i">
          <upperLimit>
           <math xmlns="http://www.w3.org/1998/Math/MathML">
            <apply>
             <plus/>
             <apply>
              <times/>
              <cn type="integer">10</cn>
              <ci>j</ci>
             </apply>
             <cn type="integer">5</cn>
            </apply>
           </math>
          </upperLimit>
          <lowerLimit>
           <math xmlns="http://www.w3.org/1998/Math/MathML">
            <apply>
             <times/>
             <cn type="integer">10</cn>
             <ci>j</ci>
            </apply>
           </math>
          </lowerLimit>
         </dimension>


Input:  dimensionToSymbolicSBML[i->{5,2*j}]
Output: XMLElement["dimension", {"id" -> "i", "lowerLimit" -> "5"}, 
         {XMLElement["upperLimit", {}, {XMLElement["math", 
            {"xmlns" -> "http://www.w3.org/1998/Math/MathML"}, 
            {XMLElement["apply", {}, {XMLElement["times", {}, {}], XMLElement["cn", {"type" -> 
              "integer"}, {"2"}], XMLElement["ci", {}, {"j"}]}]}]}]}] 
              
              
Input:  dimensionToSBML[i->{5,2*j}]
Output: <dimension id="i" lowerLimit="5">
         <upperLimit>
          <math xmlns="http://www.w3.org/1998/Math/MathML">
           <apply>
            <times/>
            <cn type="integer">2</cn>
            <ci>j</ci>
           </apply>
          </math>
         </upperLimit>
        </dimension>
        

indexToSBML, indexToSymbolicSBML
indicesToSBML,IndicesToSymbolicSBML

indexToSBML[i] returns SBML for a single index

indexToSBML[i,j,k,,,] returns a listOfIndices

The syntax of the index differs somewhat from the proposal, as illustrated below:

Input:  indexToSBML[foo]
Output: <index id="foo" type="ci">

Input:  indexToSBML[27]
Output: <index id="27" type="cn">

Input:  indexToSymbolicSBML[1]
Output: XMLElement["index",{"id"->"q","type"->"ci"},{}]

Input:  indicesToSBML[i,j,k]
Output: <listOfIndices>
         <index id="i" type="ci"/>
         <index id="j" type="ci"/>
         <index id="k" type="ci"/>
        </listOfIndices>

Input:  indicesToSymbolicSBML[i,j,k]
Output: XMLElement["listOfIndices", {}, 
        {XMLElement["index", {"id" -> "i", "type" -> "ci"}, {}], 
         XMLElement["index", {"id" -> "j", "type" -> "ci"}, {}],
         XMLElement["index", {"id" -> "k","type" -> "ci"}, {}]}]

matrixToSBML,matrixToSymbolicSBML,vectorToSBML,vectorToSymbolicSBML

Input:  vectorToSBML[{1,2,5}]
Output: <math xmlns="http://www.w3.org/1998/Math/MathML">
         <vector>
          <cn>1</cn>
          <cn>2</cn>
          <cn>5</cn>
         </vector>
        </math>

Input:  matrixToSBML[{{3,6},{9,12}}]
Output: <math xmlns="http://www.w3.org/1998/Math/MathML">
         <matrix>
          <matrixrow>
           <cn>3</cn>
           <cn>6</cn>
          </matrixrow>
          <matrixrow>
           <cn>9</cn>
           <cn>12</cn>
          </matrixrow>
         </matrix>
        </math>

Input:  vectorToSymbolicSBML[{1, 2, 5}]
Output: XMLElement["math", {"xmlns" -> "http://www.w3.org/1998/Math/MathML"}, 
          {XMLElement["vector", {}, {XMLElement["cn", {}, {"1"}], 
                                     XMLElement["cn", {}, {"2"}], 
                                     XMLElement["cn", {}, {"5"}]}]}] 

Input:  matrixToSymbolicSBML[{{5,10},{15,20}}]
Output: XMLElement["math", {"xmlns" -> "http://www.w3.org/1998/Math/MathML"}, 
          {XMLElement["matrix", {}, {XMLElement["matrixrow", {}, {XMLElement["cn", {}, {"5"}], XMLElement["cn", {}, {"10"}]}], 
                                     XMLElement["matrixrow", {}, {XMLElement["cn", {}, {"15"}], XMLElement["cn", {}, {"20"}]}]}]}]