SBML Level 3 package: Groups, Version 1 Release 1.

Biological models often contain components that have relationships with each other, or that modelers want to treat as belonging to groups with common characteristics or shared metadata. The SBML Level 3 Version 1 Core specification does not provide an explicit mechanism for expressing such relationships, but it does provide a mechanism for SBML packages to extend the Core specification and add additional syntactical constructs. The SBML Groups package for SBML Level 3 adds the necessary features to SBML to allow grouping of model components to be expressed. Such groups do not affect the mathematical interpretation of a model, but they do provide a way to add information that can be useful for modelers and software tools. The SBML Groups package enables a modeler to include definitions of groups and nested groups, each of which may be annotated to convey why that group was created, and what it represents.

1 Introduction

The SBML Level 3 Groups package offers a more flexible mechanism for indicating that components of an SBML model are related in some way. The nature of the relationship is left up to the modeler, and can be clarified by means of annotations on model components. Groups may contain either the same or different types of SBML objects, and groups may be nested if desired. There are no predefined behavioral semantics associated with groups.

1.1 Proposal corresponding to this package specification

This specification for Groups in SBML Level 3 Version 1 is based on the proposal located at the following URL:

https://sbml.svn.sf.net/svnroot/sbml/trunk/specifications/sbml-level-3/version-1/groups/proposal

The tracking number in the SBML issue tracking system (SBML Team, 2010) for Groups package activities is 2847474. The version of the proposal used as the starting point for this specification is the version of June, 2012 (Hucka, 2012).

1.2 Package dependencies

The Groups package has no dependencies on other SBML Level 3 packages.

1.3 Document conventions

UML 1.0 (Unified Modeling Language; Eriksson and Penker 1998; Oestereich 1999) notation is used in this document to define the constructs provided by this package. Colors in the diagrams carry the following additional information for the benefit of those viewing the document on media that can display color:

■ Black: Items colored black in the UML diagrams are components taken unchanged from their definition in the SBML Level 3 Core specification document.

Items colored green are components that exist in SBML Level 3 Core, but are extended by this package. Class boxes are also drawn with dashed lines to further distinguish them.

Items colored blue are new components introduced in this package specification. They have no equivalent in the SBML Level 3 Core specification.

The following typographical conventions distinguish the names of objects and data types from other entities; these conventions are identical to the conventions used in the SBML Level 3 Core specification document:

: Abstract classes are never instantiated directly, but rather serve as parents of other classes. Their names begin with a capital letter and they are printed in a slanted, bold, sans-serif typeface. In electronic document formats, the class names defined within this document are also hyperlinked to their definitions; clicking on these items will, given appropriate software, switch the view to the section in this document containing the definition of that class. (However, for classes that are unchanged from their definitions in SBML Level 3 Core, the class names are not hyperlinked because they are not defined within this document.)

Class: Names of ordinary (concrete) classes begin with a capital letter and are printed in an upright, bold, sans-serif typeface. In electronic document formats, the class names are also hyperlinked to their definitions in this specification document. (However, as in the previous case, class names are not hyperlinked if they are for classes that are unchanged from their definitions in the SBML Level 3 Core specification.)

SomeThing, otherThing: Attributes of classes, data type names, literal XML, and tokens other than SBML class names, are printed in an upright typewriter typeface.

For other matters involving the use of UML and XML, this document follows the conventions used in the SBML Level 3 Core specification document.

2 Background and context

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 the introduction of these two classes of objects was the expected introduction of a facility for defining generalized reactions, a scheme that would have allowed 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, the existence of just two types was never satisfactory in Level 2, because it did not satisfy the occasional desire to have other types of objects, such as parameters. For these reasons, when SBML Level 3 was developed, CompartmentType and SpeciesType were removed, with the expectation that SBML Level 3 packages would be developed to take their place.

The SBML Level 3 Groups package is intended to fill, in at least some capacity, the gaps left by the absence of CompartmentType and SpeciesType from SBML Level 3 Version 1 Core, while also offering a more flexible mechanism for indicating that components of an SBML model are related. The nature of the relationship is left up to the modeler. The Version 1 definition of this SBML Level 3 package, cannot, unfortunately, entirely take the place of SBML Level 2’s SpeciesType, since the definition of SpeciesType includes usage and validation rules that are not present the final Version 1 of the Groups package. Constructs providing the ability to define such validation rules have been designed, but ultimately were removed from the Version 1 specification because (1) their implementation proved to be a challenge and (2) none of the developers who implemented preliminary support for the Groups specification voiced a need or desire for these additional capabilities. Those constructs have been removed from the final Version 1 of the Groups package, but the potential remains to add them back in a Version 2 specification.

The term groups is used in this package rather than types, because the latter would imply stronger behavioral constraints on objects than what Groups provides. This package only provides a way of conceptually grouping components of a model. It does not provide a way to define types in the computer science sense; therefore, a different term is appropriate.

2.1 Prior work

The earliest relevant work is the development of the CompartmentType and SpeciesType object classes in SBML Level 2 beginning with Version 2 (Finney et al., 2006). 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 (Finney, 2004). The SpeciesType and CompartmentType classes were included in SBML Level 2 Version 2; however, a community vote held in 2006 (SBML Editors, 2006b) resulted in the decision that corresponding changes to Reaction be postponed to SBML Level 3. Level 2 was thus left only with the typing mechanism for species and compartments. Eventually, further work on generalized reactions and rule-based modeling was moved to an SBML Level 3 package, and SpeciesType and CompartmentType were removed from the core of SBML Level 3. This left the SBML Level 3 core without an explicit mechanism for defining species types or any other types.

The first version of the Groups proposal was produced by the first author in 2009 (Hucka, 2006), after discussions with the SBML Editors during the 2009 SBML Hackathon held at the European Bioinformatics Institute (Juty et al., 2009). The original proposal differed from the current proposal in several respects. The most notable architectural difference is that membership in groups was done in an inverted fashion compared to the current specification: model entities contained structures that indicated which groups they belonged to, rather than the current scheme, in which group definitions include lists of their members. The current scheme was developed during discussions with the SBML Editors during HARMONY 2011 in New York City (Anwar et al., 2011) and HARMONY 2012 in Maastricht, The Netherlands (Kutmon et al., 2012).

The idea for using an attribute to indicate the type of a group (i.e., a whether it is a classification, partonomy or simply a collection) was put forward by Nicolas Le Novère during the discussions at HARMONY 2012. The resulting attribute kind on the Group object class solved this problem.

3 Package syntax and semantics

This section contains a definition of the syntax and semantics of the Groups package for SBML Level 3 Version 1 Core. The Groups package involves four new object classes, Group, Member, ListOfMembers and ListOfGroups, as well as a simple extension of the existing Model object class. Section 5 on page 13 contains complete examples of using the constructs in SBML models.

3.1 Namespace URI and other declarations necessary for using this package

Every SBML Level 3 package is identified uniquely by an XML namespace URI. For an SBML document to be able to use a given Level 3 package, it must declare the use of that package by referencing its URI. The following is the namespace URI for this version of the Groups package for SBML Level 3 Version 1 Core:

“http://www.sbml.org/sbml/level3/version1/groups/version1”

In addition, SBML documents using a given package must indicate whether the package can be used to change the mathematical interpretation of a model. This is done using the attribute required on the element in the SBML document. For the Groups package, the value of this attribute must be “ false”, because the use of the Groups package cannot change the mathematical meaning of a model.

The following fragment illustrates the beginning of a typical SBML model using SBML Level 3 Version 1 Core and this version of the Groups package:

3.2 Primitive data types

The Groups package uses a number of the primitive data types described in Section 3.1 of the SBML Level 3 Version 1 Core specification, including SId, clarified below, and adds the GroupKind type.

3.2.1 Type GroupKind

The GroupKind primitive data type is used in the definition of the Group class. GroupKind is derived from type string and its values are restricted to being one of the following possibilities: “ classification”, “ partonomy”, and “ collection”. Attributes of type GroupKind cannot take on any other values. The meaning of these three values is discussed in the context of the Group class’s definition in Section 3.3.

3.2.2 Type SId

The SId primitive data type is used here unchanged from its description in SBML Level 3 Version 1 Core. When used as the type of a groups:id attribute, that identifier is added to the core SId namespace, and must continue to follow the same SId rules for uniqueness: that is, no groups:id may duplicate any other groups:id, nor the id of any Model, FunctionDefinition, Compartment, Species, Reaction, SpeciesReference, ModifierSpeciesReference, Event, or Parameter, nor the package:id of any other SBML Level 3 package element that is also defined as being in the SId namespace.

3.3 The Group class

The first and most central class in the Groups package is the Group class. Figure 1 on the following page provides the UML diagram of its definition. The Group class provides an optional identifier and name, one required attribute ( kind), and one child: a list of members of the group, described below.

Figure 1

The definition of the Group, ListOfMembers, and Member classes.

Since Group is derived from SBase, and SBase provides the ability to attach SBO terms as well asMIRIAM annotations, the semantics of a given group in a model can be made more precise by reference to external controlled vocabularies and ontologies. This capability is discussed further in Section 4 on page 11.

3.3.1 The id and name attributes

The optional id attribute on the Group object class serves to provide a way to identify a group. The attribute takes a value of type SId. Note that the identifier of a group carries no mathematical interpretation and cannot be used in mathematical formulas in a model. Group also has an optional name attribute, of type string. The name attribute may be used in the same manner as other name attributes on SBML Level 3 Version 1 Core objects; please see Section 3.3.2 of the SBML Level 3 Version 1 Core specification for more information.

3.3.2 The kind attribute

Group has one required attribute, kind, of type GroupKind. This attribute is used to indicate the nature of the group defined by a Group instance. The kind attribute must always have one of the three possible values of GroupKind; these values have the following meanings:

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.

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.

collection

The grouping 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.

3.3.3 Group membership

If an SBML element is referenced by a Group’s child Member (directly or indirectly—see below), it is considered to be a member of that Group. If the same element is referenced by multiple Member objects, this is equivalent to including it just once. It is considered best practice to avoid this, but does not make for an invalid SBML document. Children of referenced elements are not considered to be members of the Group: the KineticLaw object within a referenced Reaction object is not itself a Group member. Even the membership of SBML container classes (ListOfSpecies, ListOfCompartments, etc.) do not imply inclusion of their children as members of the Group. The sole exception to this rule is the ListOfMembers class, described below.

3.4 The ListOfMembers class

The ListOfMembers class is defined in Figure 1 on the preceding page, and must have one or more Member children. Since ListOfMembers is derived from , it inherits the sboTerm and metaid attributes, as well as the optional children Notes and Annotation. Unlike most lists of objects in SBML, however, the sboTerm attribute and the Notes and Annotation children are taken here to apply directly to every SBML element referenced by each child Member of this ListOfMembers, if that referenced element has no such definition. Thus, if a referenced element has no defined sboTerm, child Notes, or child Annotation, that element should be considered to now have the sboTerm, child Notes, or child Annotation of the ListOfMembers.

If multiple ListOfMembers have child Member elements that reference the same SBML element, and more than one ListOfMembers or Member has a value for an sboTerm attribute, Notes, or Annotation element, those Member elements should be consistent with each other: the sboTerm attributes should either be identical, or one should inherit from the other; Notes should say the same or similar things; and Annotation elements should not conflict. Interpreters may choose to resolve any such conflicts arbitrarily.

3.4.1 The id and name attributes

The optional id attribute of the ListOfMembers object class serves to provide a way to reference the collection by its elements instead of as a collection. The id attribute on a Group is used for the latter, when you need to refer to the group as a group; conversely, the id of the ListOfMembers is used when you need a short-hand way of referring to all the elements of a group at once. The attribute takes a value of type SId. Note that this identifier carries no mathematical interpretation and cannot be used in mathematical formulas in a model.

ListOfMembers also has an optional name attribute, of type string. The name attribute may be used in the same manner as other name attributes on SBML Level 3 Version 1 Core objects; please see Section 3.3.2 of the SBML Level 3 Version 1 Core specification for more information.

3.5 The Member class

The Member class is defined in Figure 1 on the previous page. It has four optional attributes: id and name, which identify the element, and idRef and metaIdRef which reference the identifiers of other elements. There must be exactly one (and only one) method used to reference another element: either idRef or metaIdRef may be defined, but not both. (Multiple attributes are needed to account for the different types of identifiers that a given object may have.) The referenced object (including, potentially, another Group object) is thus made a member of the group in which the Member object is contained.

Since Member is derived from and, as mentioned above, 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.

The meaning and purpose of the attributes on the object class are described below.

3.5.1 The id and name attributes

The optional id attribute on the Member object class serves to provide a way to identify the member reference. The attribute takes a value of type SId. Note that the identifier of a member reference carries no mathematical interpretation and cannot be used in mathematical formulas in a model. Member also has an optional name attribute, of type string. The name attribute may be used in the same manner as other name attributes on SBML Level 3 Version 1 Core objects; please see Section 3.3.2 of the SBML Level 3 Version 1 Core specification for more information.

3.5.2 The idRef attribute

The attribute idRef on the Member class has type SIdRef, and must be defined if the Member has no defined metaIdRef attribute, and must not be defined otherwise. The value must be the identifier of an object elsewhere in the Model. (Object identifiers are usually set by attributes named id; thus, the idRef value will usually be the id value of an object in the Model.) An example value of idRef might be the identifier of a species in the model, or the identifier of another group. The namespace in which the SId is to be found is the SId namespace of the Model to which the Group belongs. This may include elements from SBML packages that define elements with id values that are part of the SId namespace of the Model. A few examples are the Deletion elements from the SBML Level 3 Hierarchical Model Composition package, FluxBound elements from the Flux Balance Constraints package, and Group and Member elements from this Groups package.

Conversely, elements with id values that are not part of the SId namespace may not be referenced by this idRef attribute. In SBML Level 3 Version 1 Core, this includes the Unit and LocalParameter elements. For any SBML package, the same rule applies, such as for the Port elements from the Hierarchical Model Composition package.

3.5.3 The metaIdRef attribute

The Member attribute metaIdRef takes a value of type IDREF. The attribute must be defined if the Member has no defined idRef attribute, and must not be defined otherwise. This attribute is used to refer to a metaid attribute value on any other object in the Model, for cases where the object being referenced does not have an identifier in the Model SId namespace. (This is the case with, for example, rules in SBML Level 3 Version 1 Core.) Since meta identifiers are optional attributes of , all SBML objects have the potential to have a meta identifier value, including most elements from other SBML packages.

Note that even if used in conjunction with the SBML Level 3 Hierarchical Model Composition package, this attribute is not allowed to reference elements that reside within other Model objects in the same SBML Document. Referenced elements must be normal members of the parent Model containing the Member object, and submodel elements may be normally accessed by creating replacements.

3.5.4 Members referencing other Groups and Members

If a Member references a Group, it is the Group itself that is considered to be a member of the parent Group, not the corresponding referenced element (or elements). This is also true for elements from other packages that point to other elements, such as SBaseRef elements from the SBML Level 3 Hierarchical Model Composition package. However, if instead a Member references a ListOfMembers object, it is the elements referenced in that list that are considered to be part of the parent Group.

The implication of this is that all the rules in this specification that apply to members of a group (such as how the kind attribute functions, and the application of sboterm attributes on a ListOfMembers restrictions, described below) apply to the child group when referenced by the Group id, and to the members of the child group when referenced by the ListOfMembers id. In an example situation where a parent group includes two Species plus a Group which itself contains three other Species, if the parent group’s ListOfMembers is given an sboterm, that term applies to the two species and the group, not to the three child species members of the second group. Note that the parent group’s kind would also almost certainly be “ collection” or “ partonomy”, and not “ classification”, as two species and a group are very unlikely to be classified as the same thing. In contrast, in the situation where a parent group includes two Species plus a ListOfMembers which contains three other Species, the parent group’s ListOfMembers sboterm would apply to the five Species, and could be more reasonably marked as a “ classification”.

In a future version of this specification, it may be possible to perform set operations on groups, but for now, this type of union is the only set operation that is possible. For more detail, see Section 4 on page 11.

Finally, groups are not permitted to be circular: no Member may reference itself, its parent ListOfMembers, nor its parent Group. If a Member references a Group, the same restrictions apply to that subgroup’s children: they may not reference the Member, its parent ListOfMembers, nor its parent Group, and if any of those children reference a Group, the same restrictions apply to them, etc.

3.5.5 Members referencing other namespaces

If a Member has a idRef or metaIdRef attribute which references an object from a namespace that is not understood by the interpreter of the SBML model, that Member must be ignored—the referenced object will not be understood by the interpreter, and therefore has no need to become a member of the group. If an interpreter cannot tell whether a referenced object does not exist or if exists in an unparsed namespace, it may choose to produce a warning.

3.5.6 Example

As mentioned above, exactly one of the attributes idRef and metaIdRef must have a value in a given Member object instance. There are no restrictions on mixing the attributes used across multiple members of the same group, however. The following artificial example illustrates the use of heterogeneous and nested groups. The group “ all_species” references only species, but the group “ all_entities” references the compartment, the group of species, and the rule (the last through the use of the metaIdRef attribute):

3.6 The extended Model class

The Groups package extends SBML Level 3 Version 1 Core’s Model class to add one list, ListOfGroups, for holding group definitions. Figure 2 provides the UML diagram for the extension.

Figure 2

The extensions of the Model class. Group is defined in Section 3.3 on page 5. In other respects, Model remains defined as in the SBML Level 3 Version 1 Core specification.

3.6.1 The list of groups

Figure 2 shows that the extension of Model by the Groups package involves adding an optional listOfGroups subcomponent for holding a ListOfGroups container object. If present, the ListOfGroups instance must contain at least one Group object (Section 3.3 on page 5). In common with other ListOf classes in SBML, ListOfGroups is derived from SBase. It inherits SBase’s attributes metaid and sboTerm, as well as the subcomponents for Annotation and Notes, but does not add any new attributes of its own.

4 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 object. The group can be given an optional identifier (i.e., a value for its id attribute), 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 ListOfGroups instance of G, or by listing the identifier of a ListOfMembers object of a group to which X belongs as a Member object of G (thus ’nesting’ the subgroup members). The following is an example of an unnested structure:

For any given group, the meaning of group membership is determined by the value of the attribute kind on the Group object instance. Examples of possible meanings are given in Section 3.3.2 on page 6.

The meaning of a group can be further refined by using annotations (either SBO terms or the Annotation element) on the group, or the list of members. This possibility raises the question of how the annotations should be interpreted across the group members. The following are the possibilities defined by the Groups package (summarizing Section 3.3 on page 5, Section 3.4 on page 7, and Section 3.5 on page 7):

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 about the Member itself, and not about its referenced element.

If the annotation or SBO term is on ListOfMembers, it is a short-hand that means the annotation applies to each individual referenced member, as if the annotation were put on the referenced SBML elements directly.

Similar rules apply to nested groups:

If a Group object is referenced by a Member, it is the group itself that is included in that Member’s parent Group, not its individual members.

If a Member object is referenced by another Member, it is that member that is included in the parent Group, and not the referenced SBML element to which the Member points.

If a ListOfMembers object is referenced by a Member, all of the referenced SBML elements from that ListOfMembers are included in the parent Group. It is equivalent to including all of the referenced elements directly.

The following example uses the rules described above to nest the members of “ group1” inside “ group2”, using the “ group1_list” ListOfMembers id:

The intended meaning of nested groups can be made more precise by annotating the group and list of members with appropriate annotations using controlled vocabulary terms that describe the meaning.

4.1 Semantic restrictions

The current definition of this package is such that the use of Groups constructs has no impact on the mathematics of a model. As a consequence of this, this package is not required for proper interpretation of a model. The document must use the required=“ false” flag on the declaration of the package on the element in a file.

5 Examples

This section contains examples employing the Groups package for SBML Level 3.

5.1 Simple species typing via annotations

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).

In this example, both “ ATPc” and “ ATPm” are intended to be pools of ATP, but located in different compartments. To indicate that they are both conceptually the same kind of molecular entity, the model includes a group definition of the “ classification” variety. The two species “ ATPc” and “ ATPm” are both listed as members of the same group. The ListOfMembers is given the sboTerm “ SBO:0000248” to indicate that both species are small molecules. This group definition could be enhanced further by including an annotation on the ListOfMembers that references the ChEBI database entry for ATP; we omit that detail here in order to concentrate on the Groups constructs.

5.2 Example using meta identifiers

In the next example, two rules both influence a model in the same way, so a group is used to collect the rules and annotate them.

The key point of this example is the use of meta identifiers for SBML entities (in particular, rules) that do not have regular identifiers (i.e., id attributes).

5.3 Example using nested groups

In this example, ATP is grouped as ATP in the organelles, and all ATP, with the former being a subgroup of the latter. Because the intent of the group is to capture the ATP elements themselves, a reference to the first group’s ListOfMembers is used.

In this example, all five ATP Species are effectively labeled with SBO term “ SBO:0000248” to indicate they are all small molecules. An annotation added to “ ATP_all_list” to additionally specify the ChEBI database entry for ATP would have likewise applied to all five ATP Species.

Had the second group referenced “ ATP_organelle” instead, the SBO term would have been incorrect (since a group is not a small molecule), and the kind for the group should have been collection instead of classification.