Groups Proposal Updated (2012-06)
Engineering and Applied Science
California Institute of Technology
Pasadena, CA 91125
Proposal tracking number
Number 2847474 in the SBML issue tracking system.
Version number and date of public release
This is version 3 of the Groups proposal, released 28 June 2012.
Version 1 of this proposal had a substantially different object model. Version 2 of the proposal simplified the object model and did not allow certain group membership structures that were deemed undesirable in the previous version of the proposal. Version 3 added the attribute
kind after discussions led by Nicolas Le Novère at the SBML Editors' meeting during HARMONY 2012.
URL for this version of the proposal
URL for the previous version of this proposal
Introduction and motivation
SBML Level 2 versions 2–4  provides two object classes, CompartmentType and SpeciesType, meant to allow the definition of types of compartments and species. The original motivation for their introduction was in anticipation of introducing generalized reactions, a scheme that would allow reactions to be defined on whole classes of entities in a compact format. However, generalized reactions never ended up being introduced in SBML Level 2, and the notion of generalized reactions has been superceded by the effort to support rule-based models using the Level 3 Multistate and Multicomponent Species package. Moreover, if there are compartment types and species types, why aren't there also parameter types, rule types, event types, reaction types, etc.? In view of these considerations, and the fact that few models seemed to have taken advantage of SpeciesType and CompartmentType so far, the approach taken in Level 3 was to remove SpeciesType and CompartmentType, with the intention of creating a separate package for providing the ability to define types.
This is the proposal for that package, with the modification that the concept has been changed from "types" to "groups". The reason for the change is that the word "types" would imply stronger behavioral constraints on objects than what this package would provide. This package really only provides a means of defining groups of entities, not types in the computer science sense, therefore a different term is more appropriate.
Problems with current SBML approaches
In SBML Level 2, as mentioned in the introduction above, the CompartmentType and SpeciesTypes constructs are only a partial solution to object typing or grouping. They only address the problem of putting types on compartments and species, respectively, and do not address types/groups/sets of other model objects such as parameters. In SBML Level 3 Core, there is no built-in typing mechanism. A package to add this functionality is therefore desirable.
Past work on this problem or similar topics
The most relevant work on this topic is the development of the CompartmentType and SpeciesType object classes in the SBML Level 2 specification beginning with Version 2 . The original design was based on Andrew Finney's proposal for these object classes, which was made in the context of Finney's proposal for multicomponent species for SBML Level 3 . The SpeciesType class was included in the draft SBML Level 2 Version 2 to lay the groundwork for multicomponent species in Level 3, but CompartmentType was not; instead, a community vote was held in 2006  on the question of whether CompartmentType should also be added to SBML Level 2 Version 2. The original expectation was to also introduce generalized reactions, and a community vote was held on this topic , but the result of the vote was that generalized reactions should be postponed to SBML Level 3 and not introduced in Level 2. Importantly, no one voted against generalized reactions outright, suggesting that a general typing mechanism for grouping species, compartments and reactions was something desired by the SBML community.
Proposed syntax and semantics
The Groups package involves four simple new object classes, Group, Member, ListOfMembers and ListOfGroups, as well as a simple extension of the existing Model object class in SBML Level 3 Core.
The following is the UML diagram defining Group, ListOfMembers, and Member. The blue color indicates new constructs; black indicates existing constructs defined in SBML Level 3 Core:
As shown above, the definition of Group is simple—it only provides an identifier and name, and one required attribute,
kind, that indicates the nature of the group . The
kind attribute has type
GroupKind; this type is a
string type whose values are restricted to take on one of the following three:
"collection". The meanings of these values are the following:
classification: the group is a class, and its members have an is-a relationship to the group
partonomy: the group is a collection of parts, and its members have a part-of relationship to the group
collection: the grouping is one of convenience, without an implied relationship
Since Group is derived from SBase and SBase provides both the ability to attach SBO terms as well as MIRIAM annotations, the semantics of a given "group" in a model can be made more precise by reference to external controlled vocabularies and ontologies.
Likewise, Member is also very simple, defining one required attribute whose value must be the identifier of an object elsewhere in the model. An example value of
symbol might be the identifier of a species in the model, or a compartment, or a parameter. Since Member is also derived from SBase and, as mentioned above, SBase provides both the ability to attach SBO terms as well as MIRIAM annotations, the semantics of a given "member" in a model can be made more precise by reference to external controlled vocabularies and ontologies.
Finally, below is the UML diagram showing the extension of Model to add a new list of groups. A model can define any number of groups in the
<listOfGroups> within the
Semantics of "groups"
A group G is defined by declaring an instance of a Group class object within the
<listOfGroups> element of a
<model>. The group can be given an optional
id value, but even if the group does not have an identifier, the act of declaring a group has the effect of creating it.
An entity X in the model is declared to be part of group G by listing the identifier of X in a Member object within the
<listOfMembers> element of G. The following is an example to illustrate the structure:
<model id="model_1"> <listOfSpecies> <species id="s1" .../> <species id="s2" .../> <species id="s3" .../> <species id="s4" .../> </listOfSpecies> ... <listOfReactions> <reaction id="r1" ...> ... </reaction> <reaction id="r2" ...> ... </reaction> <listOfReactions> ... <listOfGroups xmlns="http://www.sbml.org/sbml/level3/version1/groups/version1"> <group id="some_species_group" kind="collection"> <listOfMembers> <member symbol="s1"/> <member symbol="s3"/> </listOfMembers> </group> <group id="some_reaction_group" kind="collection"> <listOfMembers> <member symbol="r1"/> <member symbol="r2"/> </listOfMembers> </group> </listOfGroups> </model>
The meaning of group membership is determined by the attribute
kind on the
<group> object, as follows:
kind="classification", the group represents a class, and its members have an is-a relationship to the group. For example, the group could represent a type of molecule such as ATP, and the members could be species located in different compartments, thereby establishing that the species are pools of the same molecule in different locations.
kind="partonomy", the group represents a collection of parts, and its members have a part-of relationship to the group. For example, the group could represent a cellular structure, and individual compartments could be made members of the group to indicate they represent subparts of that cellular structure.
kind="collection", the group is merely a collection for convenience, without an implied relationship between the members. For example, the group could be used to collect together multiple disparate components of a model—species, reactions, events—involved in a particular phenotype, and apply a common annotation rather than having to copy the same annotation to each component individually.
Group meanings can be further refined by using annotations (either SBO terms or the
<annotation> element) on the group, or the list of members. The following are the interpretations:
- If the annotation or SBO term is on a
<group>object, it is an annotation about the group itself, not the individual members.
- If the annotation or SBO term is on a
<member>object, it is an annotation specifically about that member, and not about any other member nor the group overall.
- If the annotation or SBO term is on
<listOfMembers>, it is a short-hand that means the annotation applies to each individual member, as if the annotation were put on the individual members directly.
Groups may refer to other groups, leading to the possibility of group hierarchies. To indicate a group is part of another group, one simply needs to include the first group's identifier as a member of the second group:
<model id="model_2"> ... <listOfGroups xmlns="http://www.sbml.org/sbml/level3/version1/groups/version1"> <group id="group1"> <listOfMembers> <member symbol="..."/> <member symbol="..."/> </listOfMembers> </group> <group id="group2"> <listOfMembers> <member symbol="group1"/> <member symbol="..."/> <member symbol="..."/> </listOfMembers> </group> </listOfGroups> </model>
The intended meaning can be made more precise by annotating the group and members with appropriate MIRIAM annotations using controlled vocabulary terms that describe the meaning.
The way that this package is formulated now, its use would have no impact on the mathematics of a model. There are no semantic restrictions necessary. Further, as a consequence of this, this package would not be required for proper interpretation of a model. Models could use the
required=false flag on the declaration of the package on the
<sbml> element in a file.
This package does not depend on any other SBML Level 3 package.
Use-cases and examples
The following is a simple example of using this proposed grouping facility to do something similar to the SpeciesType example shown in Section 4.6.3 of the SBML Level 2 Version 4 specification (p. 43).
<sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" level="3" version="1" xmlns:groups="http://www.sbml.org/sbml/level3/version1/groups/version1" groups:required="false"> ... <model> ... <listOfSpecies> <species id="ATPc" compartment="cytosol" initialConcentration="1"/> <species id="ATPm" compartment="mitochon" initialConcentration="2"/> </listOfSpecies> ... <listOfCompartments> <compartment id="cytosol"/> <compartment id="mitochon"/> </listOfCopartments> ... <listOfGroups xmlns="http://www.sbml.org/sbml/level3/version1/groups/version1"> <group id="ATP" sboTerm="SBO:0000248" kind="classification"> <member symbol="ATPc"/> <member symbol="ATPm"/> </group> </listOfGroups> </model> </sbml>
The Groups package, and the example above, does not accomplish one aspect of SpeciesType: the package does not impose the restriction that two Species objects having the same SpeciesType cannot have the same
compartment attribute value.
Draft implementations of package code for libSBML is currently being released in the folder named
"experimental" associated with a given release of libSBML. As of June 2012, a draft implementation of the Groups package code is available on SourceForge. The groups-5.5.0-beta-1 implementation is complete except for the
kind attribute on Group. We expect to implement support for the attribute in future updates of libSBML 5.5.0.
Translation to SBML Level 2
There are two foreseable methods for translating a Level 3 model using Groups to a Level 2 model:
- If the group in question contains only Species objects, and if the group has
kind="classification", then it would be possible to translate the model to one using SpeciesType in Level 2. The group in the Level 3 version of the model would become an instance of a SpeciesType in the Level 2 version of the model, and the Level 2 Species object's
speciesTypeattributes would be set to the identifier of the SpeciesType object thus created.
- If the group in question does not solely contain Species objects, then the model can be translated to Level 2 by encoding the group relationship (and any annotations associated with the group) using annotations in Level 2. One approach to doing this would be to place annotations on each individual member, expressing that the member has a certain property (e.g., that it is a member of a class or partonomy).
Since groups can be nested, a translation to SBML Level 2 form may require an interative procedure that employs a mix of solutions (1) and (2).
None at this time.
- ↑ 1.0 1.1 Finney, A., Hucka, M., Le Novère, N. (2006) Systems Biology Markup Language (SBML) Level 2: Structures and Facilities for Model Definitions. (The SBML Level 2 Version 2 specification.) Available online at http://sbml.org/Documents/Specifications/All_Releases_and_Versions_of_SBML_Level_2 .
- ↑ Hucka, M., Finney, A., Hoops, S., Keating, S. M., Le Novère, N. (2007) Systems Biology Markup Language (SBML) Level 2: Structures and Facilities for Model Definitions. (The SBML Level 2 Version 3 Release 2 specification.) Available online at http://sbml.org/Documents/Specifications/All_Releases_and_Versions_of_SBML_Level_2 .
- ↑ Hucka, M., Hoops, S., Keating, S. M., Le Novère, N., Sahle, S., Wilkinson, D. J. (2008) Systems Biology Markup Language (SBML) Level 2: Structures and Facilities for Model Definitions. (The SBML Level 2 Version 4 Release 1 specification.) Available online at http://sbml.org/Documents/Specifications/All_Releases_and_Versions_of_SBML_Level_2 .
- ↑ Finney, A. (2004) Multicomponent Species: A proposal for SBML Level 3. Available online at http://sbml.org/images/1/19/20041015-finney-multicomponent.pdf .
- ↑ http://sbml.org/Forums/index.php?t=tree&goto=3057&rid=2
- ↑ The SBML Editors. (2006) SBML L2v2 specification vote #9: Introducing Generalized Reactions. Available online at http://sbml.org/Forums/index.php?t=tree&goto=3026&rid=0 .
- ↑ The SBML Editors. (2006) Results of L2v2 specification vote #9: Introducing Generalized Reactions. Available online at https://utils.its.caltech.edu/pipermail/sbml-discuss/2006-February/001564.html .