SBML.org — the global portal for all things SBML

Definition of the instances and pools of instances

Once the multistate and multi-component types of entities used by the model have been described, using SpeciesTypes and Selectors, one needs to define quantitatively actual states and connectivity of the elementary components within the Species of the SBML core. The new entity pool instances will then be used either as initial conditions or in any SBML constructs referring to Species. In order to specify these states and partnerships, we extend Species to link to SpeciesTypeInstances, themselves refering to a list of Selectors. A SpeciesTypeInstance describes an entity that fulfills all the listed Selectors. A Species is effectively the ensemble of all the SpeciesTypeInstances belonging to the same compartment. Note that it is the responsibility of the person or software generating the SBML file to ensure that the selectors used to precise the SpeciesTypeInstances are not incompatible. The initial conditions, that is the intial states and connectivities of each species have to be fully specified.

Note that a "filtered" species is also an entity pool, and therefore is located in a given compartment. However, this species subset can be generated, selected, with a Selector that is using several SpeciesTypes instantiated by species in different compartments. Another species, located in another compartment, could be selected by a different "portion" of the same selector. This provides a mechanism to build multi-compartment entities.


Species and all the associated classes of multi version 1.
Species and all the associated classes of multi version 1.


Contents

Species

In order to encode the structures needed to refine entity pools based on their state and connectivity, we precise instances of which SpeciesType compose the Species. The element Species is then linked to a list of SpeciesTypeInstances, each of one describing an entity part of a different pool.

Defintion of the extended version of Species and its relation with SBase.
Defintion of the extended version of Species and its relation with SBase.
<species id="species1" 
         name="LGIC" 
         sboTerm="SBO:0000245"
         boundaryCondition=false" 
         hasOnlySubstanceUnit=false" 
         constant=false"
         xmlns:multi="http://www.sbml.org/sbml/level3/version1/multi/version1"
         multi:speciesType="speciesType1" >
  <multi:listOfSpeciesTypeInstances>
    <!-- some definition of subpools -->
  </multi:listOfSpeciesTypeInstances>
</species>

SpeciesTypeInstance

A SpeciesTypeInstance is identified by an id and an optional name . A SpeciesTypeInstance is linked to a list of SelectorReferences. When used in the SBML model, the id represent the either the size of the pool formed by all the SpeciesTypeInstances that fulfill the selection, or the species type restriction. The context decides. As all elements derived from SBase, it can link to Notes and Annotation, and carry a metaid , and an sboTerm . In addition, a SpeciesTypeInstance may precise the size of the pool as an initialAmount or an initialConcentration . If neither initialAmount nor initialConcentration are specified, the instance is not to be used for initial conditions.

Definition of the extended version of SpeciesInstance and its relation with SBase.
Definition of the extended version of SpeciesInstance and its relation with SBase.
<multi:speciesTypeInstance 
       xmlns:multi="http://www.sbml.org/sbml/level3/version1/multi/version1"
       multi:id="SpeciesTypeInstance_1"
       multi:name="LGIC_open"
       multi:initialAmount="1" >
  <multi:listOfSelectorReferences>
    <!-- selectors to combine to filter out the instance -->
  </multi:listOfSelectorReferences>
</multi:speciesTypeInstance>

Image:Warning.gif Note that because an instance can fulfill several selectors, the selectors used to create instances used as initial conditions may overlap. As a consequence, the sum of all the initial quantities may be larger than the initial quantity specified on the Species. It is up to the modeler generating the description to make sure there is no ambiguity and that whatever procedure is used to create the instances result in the same distribution.

SpeciesTypeInstances defined in a Species inherit the value of the attribute hasOnlySubstanceUnit carried by the Species. In other words, regardless of the presence of the attributes initialAmount and initialConcentration carried by a SpeciesTypeInstance, when used in a context requiring a quantity its id represents an amount if the species' hasOnlySubstanceUnit is set to true.

SelectorReference

As all elements derived from SBase, a SelectorReference can link to Notes and Annotation, and carry a metaid , and an sboTerm . It targets a Selector through its selector attribute. A boolean attribute negation allows to precise that the entities fulfilling the rules described in the selector are NOT selected.

Definition of the extended version of SelectorReference and its relation with SBase.
Definition of the extended version of SelectorReference and its relation with SBase.

<multi:selectorReference 
       xmlns:multi="http://www.sbml.org/sbml/level3/version1/multi/version1"
       multi:selector="selector1"
       multi:negation="true" />

Complete description of a species with pools of instances

The example below describes the encoding of two instances of the species type speciesType1.

<species id="species1"
         boundaryCondition=false" 
         hasOnlySubstanceUnit=false" 
         constant=false"
         compartment="compartment1" 
         initialAmount="1000"
         xmlns:multi="http://www.sbml.org/sbml/level3/version1/multi/version1"
         multi:speciesType="speciesType1" >
  <multi:listOfSpeciesTypeInstances>
    <multi:speciesTypeInstance 
           id="speciesTypeInstance1"
           initialAmount="1" >
      <multi:listOfSelectorReferences>
        <multi:selectorReference selector="selector1" />
      </multi:listOfSelectorReferences>
    </multi:speciesTypeInstance>
    <multi:speciesTypeInstance id="speciesTypeInstance2">
      <multi:listOfSelectorReferences>
        <multi:selectorReference selector="selector2" />
        <multi:selectorReference selector="selector3" negation="true" />
      </multi:listOfSelectorReferences>
    </multi:speciesTypeInstance>
  </multi:listOfSpeciesTypeInstances>
</species>
Procedure to build speciesTypeInstances from a speciesType and selectors. The dashed rectangle represent all the instances of a species, in all possible states and connectivity. Selector1 is used to generate the entity pool SpeciesTypeInstance1. Selector2 and Selector3 are used in combination to generate SpeciesTypeInstance2.
Procedure to build speciesTypeInstances from a speciesType and selectors. The dashed rectangle represent all the instances of a species, in all possible states and connectivity. Selector1 is used to generate the entity pool SpeciesTypeInstance1. Selector2 and Selector3 are used in combination to generate SpeciesTypeInstance2.


Back to start page



Please use our issue tracking system for any questions or suggestions about this website. This page was last modified 11:00, 29 November 2010.