SBML.org — the global portal for all things SBML

Selector

We are currently updating this wiki page. Only the UML diagrams are up to date, but NEITHER the description text NOR the examples.

A selector is a mask describing rules to build an entity, made of different components, carrying StateFeatures and displaying BindingSites involved in bonds or not. The selector when applied to a pool of entities, permit to filter it, and to obtain a further more refined entity pool. A selector can be reused in various places of a model, to restrict the application of a procedure to a certain set of topologies and states. Selectors can be used in Species, where they allow the refinement of initial conditions, for instance to specify the initial distribution of different states and topologies. They can also be used in Reaction to decide if a this reaction happens, or to modulate its velocity.

Principle idea selector

The above selector accepts everything containing a blue crystal, but rejects the red face and the isolated green crystal.

A selector defines the list of components composing the mask, the speciesTypeStates, with the various relevant StateFeatures. In addition to the components, the selector describes the bonds as well as the unboundBindingSites.

Definition of classes Selector, Bond, and BindingSiteReference, as well as the container classes ListOfSpeciesTypeState, ListOfBounds and ListOfUnboundBindingSites. The class SpeciesTypeState, in blue, is described below.
Definition of classes Selector, Bond, and BindingSiteReference, as well as the container classes ListOfSpeciesTypeState, ListOfBounds and ListOfUnboundBindingSites. The class SpeciesTypeState, in blue, is described below.


<selector id="selector_1" xmlns="http://www.sbml.org/sbml/level3/version1/multi/version1">
  <listOfSpeciesTypeStates>
    ...
  </listOfSpeciesTypeStates>
  <listOfBonds>
    ...
  </listOfBonds>
  <listOfUnboundBindingSites>
    ...
  </listOfUnboundBindingSites>
</selector>
Structure of the selector

SpeciesTypeState

A speciesTypeState describes an ensemble of states a speciesType can be into, in order to fulfill the requirements of the selector. A speciesTypeState can contain other speciesTypeStates, that have to be declared in the selector also. A speciesTypeState is then defined by the values of the different stateFeatures carried by the speciesType, the list of speciesTypeStates it "contains", and their topology.

Definition of classes SpeciesTypeState, StateFeatureInstance, StateFeatureValue, and ContainedSpeciesType, as well as the container classes ListOfStateFeatureInstance, ListOfStateFeatureValues and ListOfContainedSpeciesType.
Definition of classes SpeciesTypeState, StateFeatureInstance, StateFeatureValue, and ContainedSpeciesType, as well as the container classes ListOfStateFeatureInstance, ListOfStateFeatureValues and ListOfContainedSpeciesType.

The following code contains a portion of selector describing two SpeciesTypeStates, "speciesTypeState_1" and "speciesTypeState_2". SpeciesTypeState_1 has a feature stateFeature_1 that can take the values "possibleValue_1" or "possibleValue_1" to pass the selection. In addition speciesTypeState_2 contains 4 instances of speciesTypeState_2 (more exactly between 4 and 4 ...).

  <listOfSpeciesTypeStates>
    <speciesTypeState id="sts1" speciesType="st1">
      <listOfStateFeatureInstances>
        <stateFeatureInstance stateFeature="sf1">
          <listOfStateFeatureValues>
            <stateFeatureValue possibleValue="pv1" />
            <stateFeatureValue possibleValue="pv2" />
          </listOfStateFeatureValues>
        </stateFeatureInstance>
      </listOfStateFeatureInstances>
    </speciesTypeState>
    <speciesTypeState id="sts2" speciesType="st2">
      <listOfContainedSpeciesTypes>
        <containedSpeciesType speciesTypeState="sts1" 
                              minOccur="4" maxOccur="4" connex="true" saturated="true" />
      </listOfContainedSpeciesTypes>
    </speciesTypeState>
  </listOfSpeciesTypeStates>

The boolean attributes connex and saturated precises the topology of a multimeric assembly of the same component (same speciesTypeState, that is same speciesType with the same values allowed for their stateFeatures) within a containing speciesTypeState. One can then declare the component only once, and each of the bond type or unbound binding site only once. Note that in the case of "top-level" multimers, that is not contained in another speciesTypeState, all the monomers have to be enumerated. That is, one has to create several speciesTypeStates corresponding to the same speciesType with the same stateFeature values, and one has to enumerate all the bonds. (Of course one can also use this procedure with the contained species type states).

Here are examples of the difference possibilities:

Connexity and saturation

Handling of binding sites

In a selector, bindingSites can be referred to when they are involved in bonds, or explicitly listed as unbound. As a result a bindingSite can be used in four different contexts:

  • In a declared explicit bond, with another specific interactor (represented by a bond linking two entities in the example graphs).
<bond occurrence="rquired">
  <bindingSiteReference speciesTypeState="sts1" bindingSite="bs1" />
  <bindingSiteReference speciesTypeState="sts2" bindingSite="bs2" />
</bond>
  • In a declared bond without another specific interactor, meaning any interactor (represented by a "*" in the example graphs).
<bond occurrence="allowed">
  <bindingSiteReference speciesTypeState="sts1" bindingSite="bs1" />
</bond>
  • Declared as explicitly unbound (represented by a bond with a dangling end in the example graphs).
<listOfUnboundBindingSites>
  <bindingSiteReference speciesTypeState="sts1" bindingSite="bs1" />
</listOfUnboundBindingSites>
  • Undeclared, meaning that one does not care if it is bound or not (represented by a "?" in the example graphs).

A given bindingSite can only be bound to another bindingSite. If three speciesTypeStates are bound together, they have to be bound through different bindingSites.

The attribute prohibited, in combination with explicit, generic and undeclared bonds, provides for a complete boolean logic to select the context of bindinSites. Note that the attribute prohibited is only present on bond. In order to prohibit a dangling end, we create a generic bond (to say that x cannot be free is equivalent to say that x had to be bound to something, whatever it is).

To exemplify this boolean logic, let's take the example of a SpeciesTypeState "st1" with a binding site X interacting with a SpeciesTypeState "st2" with binding sites A, B or C.

In the following code, X is not declared at all, therefore X can be bound to A, B, C or be unbound:

<selector id="selector" xmlns="http://www.sbml.org/sbml/level3/version1/multi/version1">
  <listOfSpeciesTypeStates>
    <speciesTypeState id="sts1" speciesType="st1" />
    <speciesTypeState id="sts2" speciesType="st2" />
  </listOfSpeciesTypeStates>
</selector> 

With the following code X can only be bound to A:

<selector id="selector" xmlns="http://www.sbml.org/sbml/level3/version1/multi/version1">
  <listOfSpeciesTypeStates>
    <speciesTypeState id="sts1" speciesType="st1" />
    <speciesTypeState id="sts2" speciesType="st2" />
  </listOfSpeciesTypeStates>
  <listOfBonds>
    <bond prohibited="false">
      <bindingSiteReference speciesTypeState="sts1" bindingSite="X" />
      <bindingSiteReference speciesTypeState="sts2" bindingSite="A" />
  </bond>
  </listOfBonds>
</selector>

With the following code X can only be bound either to A or B:

<selector id="selector" xmlns="http://www.sbml.org/sbml/level3/version1/multi/version1">
  <listOfSpeciesTypeStates>
    <speciesTypeState id="sts1" speciesType="st1" />
    <speciesTypeState id="sts2" speciesType="st2" />
  </listOfSpeciesTypeStates>
  <listOfBonds>
    <bond prohibited="false">
      <bindingSiteReference speciesTypeState="sts1" bindingSite="X" />
      <bindingSiteReference speciesTypeState="sts2" bindingSite="A" />
    </bond>
    <bond prohibited="false">
      <bindingSiteReference speciesTypeState="sts1" bindingSite="X" />
      <bindingSiteReference speciesTypeState="sts2" bindingSite="B" />
    </bond>
  </listOfBonds>
</selector>

The following code defines a generic bond with X, which mean that X can be bound to A, B or C, but has to be bound to something:

<selector id="selector" xmlns="http://www.sbml.org/sbml/level3/version1/multi/version1">
  <listOfSpeciesTypeStates>
    <speciesTypeState id="sts1" speciesType="st1" />
    <speciesTypeState id="sts2" speciesType="st2" />
  </listOfSpeciesTypeStates>
  <listOfBonds>
    <bond prohibited="false">
      <bindingSiteReference speciesTypeState="sts1" bindingSite="X" />
    </bond>
  </listOfBonds>
</selector>


The following code says that X cannot be bound to C (The bond X-C is prohibited), and therefore has to be bound to A or B or unbound.

<selector id="selector" xmlns="http://www.sbml.org/sbml/level3/version1/multi/version1">
  <listOfSpeciesTypeStates>
    <speciesTypeState id="sts1" speciesType="st1" />
    <speciesTypeState id="sts2" speciesType="st2" />
  </listOfSpeciesTypeStates>
  <listOfBonds>
    <bond prohibited="true">
      <bindingSiteReference speciesTypeState="sts1" bindingSite="X" />
      <bindingSiteReference speciesTypeState="sts2" bindingSite="C" />
    </bond>
  </listOfBonds>
</selector>

The following code says that X cannot be bound to C (The bond X-C is prohibited), however a generic bond specifies that X has to bound to soemthing, therefore effectively to A or B.

<selector id="selector" xmlns="http://www.sbml.org/sbml/level3/version1/multi/version1">
  <listOfSpeciesTypeStates>
    <speciesTypeState id="sts1" speciesType="st1" />
    <speciesTypeState id="sts2" speciesType="st2" />
  </listOfSpeciesTypeStates>
  <listOfBonds>
    <bond prohibited="false">
      <bindingSiteReference speciesTypeState="sts1" bindingSite="X" />
    </bond>
    <bond prohibited="true">
      <bindingSiteReference speciesTypeState="sts1" bindingSite="X" />
      <bindingSiteReference speciesTypeState="sts2" bindingSite="C" />
    </bond>
  </listOfBonds>
</selector>


The following case is overdetermined, since the impossibility for X to bind C is implicit in the restriction of its binding to A or B.

<selector id="selector" xmlns="http://www.sbml.org/sbml/level3/version1/multi/version1">
  <listOfSpeciesTypeStates>
    <speciesTypeState id="sts1" speciesType="st1" />
    <speciesTypeState id="sts2" speciesType="st2" />
  </:listOfSpeciesTypeStates>
  <listOfBonds>
    <bond prohibited="false">
      <bindingSiteReference speciesTypeState="sts1" bindingSite="X" />
      <bindingSiteReference speciesTypeState="sts2" bindingSite="A" />
    </bond>
    <bond prohibited="false">
      <bindingSiteReference speciesTypeState="sts1" bindingSite="X" />
      <bindingSiteReference speciesTypeState="sts2" bindingSite="B" />
    </bond>
    <bond prohibited="true">
      <bindingSiteReference speciesTypeState="sts1" bindingSite="X" />
      <bindingSiteReference speciesTypeState="sts2" bindingSite="C" />
    </bond>
  </listOfBonds>
</selector> 


The complete example below selects the following structure:

<selector id="selector" xmlns="http://www.sbml.org/sbml/level3/version1/multi/version1">
  <listOfSpeciesTypeStates>
    <speciesTypeState id="sts2" speciesType="st2">
    <speciesTypeState id="sts1" speciesType="st1">
      <listOfStateFeatureInstances>
        <stateFeatureInstance stateFeature="sf1">
          <listOfStateFeatureValues>
            <stateFeatureValue possibleValue="pv1" />
            <stateFeatureValue possibleValue="pv2" />
          </listOfStateFeatureValues>
        </stateFeatureInstance>
      </listOfStateFeatureInstances>
      <listOfContainedSpeciesTypes>
        <containedSpeciesType speciesTypeState="sts2" 
                              minOccur="4" maxOccur="4" connex="true" saturated="true" />
      </listOfContainedSpeciesTypes>
    </speciesTypeState>
  </listOfSpeciesTypeStates>
  <listOfBonds>
    <bond occurrence="required">
      <bindingSiteReference speciesTypeState="sts2" bindingSite="a" />
      <bindingSiteReference speciesTypeState="sts2" bindingSite="b" />
    </bond>
  </listOfBonds>
  <listOfUnboundBindingSites>
    <bindingSiteReference speciesTypeState="sts1" bindingSite="c" />
  </listOfUnboundBindingSites>
</selector>


How to use the Selector element



Please use our issue tracking system for any questions or suggestions about this website. This page was last modified 18:13, 5 October 2009.