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
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
SpeciesTypeInstance describes an entity that fulfills all the listed
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
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.
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.
<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 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
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
initialConcentration are specified, the instance is not to be used for initial conditions.
<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>
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
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
As all elements derived from
SelectorReference can link to
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.
<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
<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>