This page summarizes the conclusions about different issues reached throughout HARMONY 2012.
Issue: We have a number of known errata in L2v4, including the infamous issue of the missing
rdf:id. The question now is, when should L2v5 be released? Developers who support very thorough implementations of SBML want to support all levels and versions of SBML. To these developers (who are, after all, the biggest supporters of SBML), there is a development cost associated with the introduction of another Version of SBML Level 2. Therefore, we should consider whether the benefits of issuing another Version now (versus later) outweigh the cost to developers. A new version needs to be released eventually, but does it have to be now? If the practical result is that it reduces the time developers have to support other aspects of SBML (e.g., Level 3), then it's worth weigh the pros and cons of introducing another L2 Version now versus waiting to introduce it in the future.
So what are the critical issues in L2v4? They would be issues that affect actual syntax and/or behavioral implementations—basically anything that a developer would potentially have to change. Those appear to be the following:
- The rdf:id issue
- issue 2789288
- issue 2790011
- issue 2790007
- issue 2848164
- issue 2964795
- issue 3529451
Of these, which ones have a high priority? The 4 most significant real issues appear: the
rdf:id issue, issue #2964795 (csymbol delay in function defs), issue #2848164 (agreement of units), and issue #3529451 (constant species in nonconstant compartments).
Decision: Yes, produce L2v5. This decision was difficult. It appears that some software tools already implement the
rdf:id feature, so they would presumably not be significantly affected. The other issues are either minor spec fixes or relatively esoteric behavior issues. In the end, we decided to go ahead and release an L2v5 at the same time as releasing L3v2, so that when developers implement the changes, they can do both at the same time.
We discussed changes planned for a Version 2 of SBML Level 3. (We refer to this version using the nickname "L3v2".)
Changes to be proposed
The following are changes we decided to definitely propose making:
- All L3v1 errata
- Removal of restrictions on required elements. The motivation is to allow the straightforward encoding of annotations even when the components of the reactions are unknown, and to allow a greater range of models to be encoded (specifically, models that do not conform to the classical notion of models and reactions that has been the default assumption in SBML). Rather than keep removing restrictions a little at a time, we decided we should just do it once and for all. This has multiple implications:
- Allow all ListOf's to be empty, instead of requiring at least one element.
- Allow a Reaction to have no reactants or products. If we make all child elements optional, this validation rule is a similar restriction that should be dropped.
<math>elements become optional. This is a long-time request for the mathematics of kinetic laws. Modelers have wanted to put annotations on the kinetic laws even when a reaction has no kinetic law.
<model>becomes optional. To be consistent with the step of removing the other constraints listed above, the model element becomes optional.
- The Trigger on Event objects becomes optional.
- Add an id to particular SBML components.: InitialAssignment, Rule, Trigger, Priority, Delay, EventAssignment, and Constraint elements will be given optional "id" and "name" attributes of type SId and string respectively.
- Rewrite SIdRef rules for the 'variable' attribute of assignments and rules to allow references to SIds from packages: The definition of the 'variable' and 'symbol' attributes of AssignmentRule, RateRule, InitialAssignment, and EventAssignment will be expanded to include, as a valid target of the SIdRef, "the SId of an element defined in a package that has mathematical meaning". It would also declare that software that did not understand the referenced package should ignore the rule/assignment in question.
- Relax SIdRef rules for the
<ci>element in MathML to allow references to SIds from packages: Similar to the items above and below this item, we change the specification to say that SIdRefs in
<ci>elements may refer to package elements with mathematical meaning. It would also declare that software that did not understand the referenced package could not mathematically interpret the given
- Allow full content MathML to be written in SBML models To provide a path for packages to use more MathML constructs, and to allow exchange of models with descriptions of math that cannot be encoded in the current allowed MathML subset, we will allow all of 'content' MathML to be valid in an SBML model, but to provide a list of content elements that have a defined meaning for the mathematical interpretation of such models. The use of elements not on that list would imply that that construct was being used for semantic exchange only, and not mathematical exchange. A given package could then stipulate it gives meaning to one or more of these allowed MathML constructs.
For all items on the above list, we will ask sbml-discuss if anyone has serious objections to implementing them for L3v2, explaining the pros and cons concisely. If any particular item proves controversial, run a vote about it.
The following are changes we discussed but in the end decided not to implement in L3v2:
- List of properties. One of Nicolas Le Novère's suggestions for L4/SBML+ is the addition of a construct for flexibly defining properties of entities. Because this construct is self-contained, we discussed whether it could be added to L3v2. In the end, we decided against it.
idon SBase. A better way to define SIds in general would be to define new subclasses of SBase with required or non-required 'id' attributes of type SId, but such a change is too far-reaching to incorporate into L3v2. The above change (put optional SIds on an explicit list of classes) was chosen instead.
- Allow remaining SIdRef attributes to point to package elements. The 'compartment' attribute of Species and Reaction elements and the 'conversionFactor' attribute of Model and Species elements will not be changed, and must point to core elements as specified.
- New syntax for list of packages. Sarah Keating investigated whether a different syntax for declaring packages would make validation simpler. The results of her tests were that a different syntax for declaring the packages does not in fact simplify validation. Although there is an attribute that is mandatory if a package is present, any validation needs to assess whether the package namespace has been declared and only check for the mandatory attribute is the namespace is present. The only way to make validation simpler would be to make the
requiredattribute optional. Sarah believes we may as well leave the status quo; validation is still possible in the current scheme (although it is awkward to implement).
Miscellaneous guidelines related to L3
- Clarify what rules are available to package writers when they declare 'id' attributes, specifically what it means when they declare that an attribute is of 'type SId' vs. 'type [package]SId'.
- A brief summary: If you define an element that might be referred to by a core element or a package element (such as layout), give it an SId. If you want the element's ID in its own scope, define it as a PackageSId (such as PortSId from comp or SpId from Spatial).
- Encourage adoption of a similar philosophy to L3v2: don't require child elements, and provide id's for most if not all elements.
The following are decisions and results of package development efforts during this HARMONY.
Hierarchical Model Composition
- It was proposed that the current specification change to require all submodel element references to act through submodel ports. It was decided that this is a 'best practices' issue, and that because it is possible to interact with comp this way, and because there are valid scenarios that should not interact with comp this way (such as in a systems biology context, instead of an engineering context), that no change to the spec in this regard should be made.
- An additional restriction on the ReplacedElement and ReplacedBy elements was accepted: to only allow 'like to like' (or 'class to class') replacements, with the exceptions that Parameters could be replaced by any other model element with mathematical meaning (in core: Species, Compartment, Reaction, SpeciesReference), and that any element of a given class could be replaced by an element of that class's subclass.
- Lucian proposed a much-simplified version of conversionFactors: the ReplacedElement still has a conversionFactor attribute, and must be used for all replaced elements that need to be converted. The ReplacedBy element does not have a conversionFactor. The Submodel element now only has a timeConversionFactor and an extentConversionFactor, and apply to all non-replaced elements in that Submodel, including any elements pointed to by ReplacedBy constructs. This proposal was not extensively discussed, but the simplification to the previous specification was appreciated.
A few issues have been undecided from the last time the groups package was discussed. We attempted to settle them all.
- Should the identifier of a group have a mathematical meaning? Decision: no.
- Should the
MetaIdRef? Decision: no, with the assumption that more things like InitialAssignment will be given optional identifiers, so that they can be made group members.
- Do we add an attribute to help groups be used as SpeciesTypes? This is the question of whether there needs to be something like a
<group>.Decision: no. Instead, the combination of (1) adding an attribute for the sense of group (see below), and (2) the ability to annotate groups using normal annotations, was enough. As has been often stated, software that creates a model should figure out whether it is putting species of the same "species type" in a given compartment and prevent that.
- What is the nature of a group? Nicolas Le Novère argued convincingly that there needs to be an attribute on
<group>to indicate whether the group is a classification, a partonomy, or a collection/set. We decided this attribute could simply be a string attribute with three possible values. The name of this required attribute will be
kindand the possible values will be
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
Here is an example of the syntax:
<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 proposal is to declare distributions that one can use in SBML mathematical expressions. Wherever the distribution call appears, it represent a sampling procedure. One can only sample from distributions in the following places:
- Initial Assignments
- Event assignments
The mechanism to refer to distributions becomes simpler. Instead of using UncertML XML, including the use of fake values to declare parameters in
<bvar>, it is decided to only refer to external definitions of the distributions through URIs. These URIs can be UncertML, SBO or other. This point needs further discussion. But whatever is chosen, an appendix of the package specification will describe the distributions and their parameters.
<listOfFunctions> <functionDefinition id="normal" distrib:function="http://identifiers.org/Distribution"> <!-- NB: the identifiers.org is just a placeholder for a suitable URI --> <math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core"> <lambda> <bvar><ci>param1</ci></bvar> <bvar><ci>param2</ci></bvar> <apply> <ci>0</ci> </apply> </lambda> </math> </functionDefinition> </listOfFunctions> <listOfParameters> <parameter id="V_pop" value="0.70" constant="true"/> <parameter id="V_omega" value="0.70" constant="true"/> <parameter id="V" constant="true"/> </listOfParameters> <listOfInitialAssignments> <initialAssignment symbol="V"> <math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core"> <apply> <ci>normal</ci> <ci>V_pop</ci> <ci>V_omega</ci> </apply> </math> </initialAssignment> </listOfInitialAssignments>
Users can define distributions in the model. They are defined as Probability Density Function. However, the value returned by the distribution should be obtained by sampling the distribution so we need to indicate this. One idea would be to indicate this via a URI as in the example below. Note the PDF may not be defined correctly.
Particle representations of data are defined in external multi-dimensional arrays, possibly encoded in NuML, referred to through the distrib:function construct. A PMF is essentially a weighted particle representation.
For univariate distributions, one just need the distrib package. For multivariate distributions, one also needs the array package.
<listOfFunctions> <functionDefinition id="multivariateNormal" distrib:function="http://identifiers.org/probdists/MultivariateNormal"> <math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core"> <lambda> <bvar><ci>meanVector</ci></bvar> <bvar><ci>covarianceMatrix</ci></bvar> <apply> <ci>meanVector</ci> </apply> </lambda> </math> </functionDefinition> </listOfFunctions> <listOfParameters> <parameter id="V" constant="true"/> <parameter id="V_pop" value="105" constant="true"/> <parameter id="V_omega" value="0.70" constant="true"/> <parameter id="Cl" constant="true"/> <parameter id="Cl_pop" value="73" constant="true"/> <parameter id="Cl_omega" value="0.70" constant="true"/> <parameter id="covariance" constant="true"> <listOfDimensions> <dimension id="i" lowerLimit="1" upperLimit="2" /> <dimension id="j" lowerLimit="1" upperLimit="2" /> </listOfDimensions> </parameter> <parameter id="correlated_means" constant="true"> <listOfDimensions> <dimension id="i" lowerLimit="1" upperLimit="2" /> </listOfDimensions> </parameter> <parameter id="correlated_params" constant="true"> <listOfDimensions> <dimension id="i" lowerLimit="1" upperLimit="2" /> </listOfDimensions> </parameter> </listOfParameters> <listOfInitialAssignments> <initialAssignment symbol="covariance"> <math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core"> <matrix> <matrixrow> <apply><times/><ci>V_omega</ci><ci>V_omega</ci></apply> <apply><times/><ci>V_omega</ci><ci>C_omega</ci><ci>V_C_rho</ci></apply> </matrixrow> <matrixrow> <ci>0</ci> <apply><times/><ci>C_omega</ci><ci>C_omega</ci></apply> </matrixrow> </matrix> </math> </initialAssignment> <initialAssignment symbol="correlated_means"> <math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core"> <vector> <ci>V_pop</ci> <ci>C_pop</ci> </vector> </math> </initialAssignment> <initialAssignment symbol="correlated_params" > <math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core"> <apply> <ci>multivariateNormal</ci><ci>correlated_means</ci><ci>covariance</ci> </apply> </math> </initialAssignment> <initialAssignment symbol="Cl"> <math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core"> <apply> <selector/> <ci>correlated_params</ci> <cn type="integer">2</cn> </apply> </math> </initialAssignment> <initialAssignment symbol="V"> <math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core"> <apply> <selector/> <ci>correlated_params</ci> <cn type="integer">1</cn> </apply> </math> </initialAssignment> </listOfInitialAssignments>
It is proposed to separate distrib from the definition of ranges and sampling errors. The proposal is that lower bound, upper bound and stdev are added as optional attributes to the apprtopriate SBML elements (compartment, specie, parameter).
There was a lot of interest in having arrays as soon as possible as it would help several efforts such as the distrib package.
There is still an issue to decide which is whether to add vector/matrix operations to core mathML in L3V2. This would help issues raised by Nicolas in generating general kinetic laws. This would also allow us to avoid needing alternate array math constructs. It would though be an extra burden on simulation tool developers to ignore these constructs.
It was agreed that arrays and dynamic would be separate packages.
Much more thought is needed on the dynamic package. Currently, we are considering special birth/death events but what can exactly be created and destroyed? Only complete sub models or any SBML element?
Flux Balance Constraints
There are two implementations using this package.
Brett is frantically working converting the specification from WIKI to LaTeX document.
Decided to add a metaIdRef to GraphicalObject.
Decided to add a new object called GeneralGlyph which will be similar to reationGlyph. In that, it will include referenceGlyphs which are a generalization of speciesReferenceGlyphs. It will include a role attribute which is an enumerated type that will include at least "forward", "backward", "undirected", and "bidirectional". Its id will be a general SIdRef.
In addition, the GeneralGlyph will include a list of GraphicalObjects which can be of any type and are inferred to be semantically contained within the GeneralGlyph though perhaps not graphically contained.
Sven and Chris will work together to get a specification together.
We hope Frank will incorporate these changes into libSBML.
Specification for render should follow shortly after layout but at a lower priority given limited time and resources.
Many of the issues relating to the qualitative specification were resolved at the recent CoLoMoTo meeting. At this point it was decided that the first version of the specification would only include those elements of the proposal that are already implemented in software. Temporisation has been postponed to a subsequent version. The interchangeable use of levels or symbols is being simplified to use only levels within transitions but allow a qualitativeSpecies to provide a listOfSymbols that correspond to the levels being used. Martijn van Iersel has been working on outlining this.
What remains to be done is the writing of the specification. There are some points that need greater explanation and more examples. Sarah will pursue the relevant people to get this points expanded.
Other Level 3 package work
What counts as "two implementations"?
We discussed what it means for L3 package acceptance to require "two implementations". What exactly does that mean? In the end, we concluded that the current procedure defined in the relevant section of the SBML Development Process is reasonable: it is the package working group (PWG) that defines precisely what it means for their package, and presents their case to the SBML Editors, who then must approve that decision as part of their acceptance of that package.
Promoting/demoting elements to/from packages
We briefly discussed procedures for moving structures between the L3 Core and L3 packages, but did not reach a conclusion on the matter. No procedures or guidelines are currently defined.
Miscellaneous SBML questions, requests and general issues
Resolvable SBO term attributes
Issue: Nick Juty raised this issue: Since identifiers.org allows annotations to be resolvable from the model, could we consider having a syntax for the sboTerm attribute that would take the whole resolvable string instead of just the number?
Decision: Too much code already relies on the current scheme of the
sboTerm attribute being a number. We will leave the definition as-is, but to help at least some users, libSBML will add an API to translate SBO term integers to identifier.org URIs.
IDs and IDRefs
This was rolled into the L3v2 discussion, above, but the basic conclusion is that many examples were found of package SIdRef elements pointing to SIds from other packages (comp and layout being two major ones). A general way to describe this situation should be provided for specification writers to copy when they need to define such an element.
In addition, it may be possible and/or desirable to relax SIdRef restrictions on SBML L3v2 core elements.
The future of SBML
Most of the discussion at HARMONY focused on the present of SBML, and not its future. We did however go over Nicolas's earlier proposals at determine which of them could potentially be incorporated into L3v2.