From Frank: We should declare that packages for level 1 are legal in level 2, with the semantic meaning from level 1, i.e. no new semantic meaning is imparted.
Here is a new version of section 3.3.3, "Use of SBML Level 3 Version 1 packages and implications for identifiers":
Packages created and designed for use with SBML Level 3 Version~1 may be used in SBML Level 3 Version~2 documents, and be interpreted in exactly the same manner as before. They may not, however, take full advantage of the new features and constructs in Version~2. This means the following:
Any object class in an SBML Level~3 Version~1 package that inherits from \SBase will not inherit the new {id} and {name} attributes on \SBase.
An object identifier from a SBML Level 3 Version~1 package may not be used in \Math constructs in SBML Level~3 Version~2 Core, nor as the value of any {SIdRef} type attribute in a Core construct.
No object from a SBML Level 3 Version~1 package is considered to have mathematical meaning in core: no such object's {SId} may be used as the target of a rule nor of an assignment, nor may it be used in any MathML outside of that package.
However, if a package defines an {SIdRef} that may refer to any \SBase, it is legal for those references to point to SBML Level 3 Version~2 {SIds}. In particular:
An {SIdRef} defined in a SBML Level 3 Version~1 package may be used to reference an element from SBML Level 3 Version 2 that has an {SId}, but did not have one in Version~1.
An {SIdRef} defined in a SBML Level 3 Version~1 package may be used to reference an element from an SBML Level 3 Version~2 package.
Any \Math object defined in a SBML Level 3 Version~1 package may reference any SBML Level 3 Version~2 package {SId} defined as having mathematical meaning.
The upshot is: SIdRefs can reference l3v2 things; no l3v1 package SId is defined as having mathematical meaning outside of that package.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
We say that math in L3V2 core cannot use something from an L3V1-pkg even if it has mathematical meaning. So fbc and qual cannot use initial assignments/rules etc until they have a L3V2-pkg. Personally I'm not sure I would impose this restriction but I think I am out voted on that. It might be good to come up with a case where this could go wrong and add it to the explanation in the spec :-)
I do see that opening doors without fully explaining the consequences may lead to issues and so it is in some ways safer to say you cannot use L3V1-pkg things in an anyway differently in L3V2-core without specification.
However my reading of the sixth point is that an L3V1-pkg math COULD use something from an L3V2-pkg. But surely this is also a situation where something could be done that has not been explained/thought out etc. So L3v1-pkg objects can have no mathematical meaning in L3V2-core (as it does not know about them) but an L3v2-pkg object can have mathematical meaning in an L3V1-pkg (which also does not know about them!).
I may be misunderstanding the note about SIdRefs that can be any SBase - but that might mean it needs further explanation :-)
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I think the reason we impose the 'l3v2 can't use l3v1-pkg even if it has mathematical meaning' is best illustrated by the fact that 'qual' doesn't have the concept of 'time'. As a result, what exactly would it mean for a Reaction to change the level of a QualitativeSpecies over time? What exactly would it mean for an Event to change a Qualitative rate after 5 seconds have passed? What does 'delay' mean?
For the other way 'round, even in l3v1, a package could change the meaning of a core element with mathematical meaning: comp can change values aribitrarily; spatial even redefines the units of 'reaction'. As such, if a package already defined MathML that could have arbitrary elements from core with mathematical meaning, it would have to deal with l3v1 packages changing those values. It's a small step, then, to allow those packages to simply define their own symbols with their own meaning, and pull them into l3v1 package math.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I see the point about qual BUT you could use an initialAssignment (forget the semantics of the initial part!) so I think we need to be very clear as to why we universally disallow this. I agree it makes sense to not allow things until a pkg has considered the implications for itself but I would be very explicit about why.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Okay I get the l3v2 thing but it is such a niche sort of situation that I think we need to at least provide an example. - Probably for all the second set of bullet points.
Putting money where mouth is:
The L3V1 layout pkg allows an attribute of type SIdRef on a GeneralGlyph object that may point to any SBase object.
An {SIdRef} defined in a SBML Level 3 Version~1 package may be used to reference an element from SBML Level 3 Version 2 that has an {SId}, but did not have one in Version~1. Thus, a GeneralGlyph in L3V1-layout-V1 might now legitimately point to the id of an L3V2 AssignmentRule.
An {SIdRef} defined in a SBML Level 3 Version~1 package may be used to reference an element from an SBML Level 3 Version~2 package. This would allow the GeneralGlyph to point to any object in any L3V2 package (as these will have an id attribute from SBase). This applies to new versions of existing packages and any other packages that are developed to work with L3V2 core
Any \Math object defined in a SBML Level 3 Version~1 package may reference any SBML Level 3 Version~2 package {SId} defined as having mathematical meaning.
..... here I am stuck ... is this what is meant ...
The \Math object within a FunctionTerm in the L3V1-qual-V1 pkg could refer to the id of any object in any L3V2 package that has a defined mathematical meaning; provided the L3V2 package has clearly specified what the use of these ids represents when used in the L3V1-qual-V1 pkg.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
This all sounds reasonable--I'll put together a new version of the text next week so people can look it over.
And yes, your final bullet point about Math matches my current thinking on the issue. However, the l3v2 package would not have to clearly specify what the use of that I meant in qual; merely what it meant in core. It is my hope that this would be sufficient.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
OK, I checked in a version that adds the following paragraph. In general, I tried to go with added clarification instead of added justification, since my sense with the current editors is that we don't need so much of the latter; it clutters up what is otherwise supposed to be a technical document. That said, some justification creeps in around the edges ;-)
"To take some examples: the reference attribute of a SBML Level 3 Version 1 Layout GeneralGlyph is of type SidRef, and was designed to be able to point to aribtrary SBML Level 3 Version 1 core and package elements. If used in a Level 3 Version 2 Core document, it could now point to an AssignmentRule, which it would not have been able to do in a SBML Level 3 Version 1 document. Alternatively, it could point to an SBML Level 3 Version 2 package element that inherited an SId from SBase. Similarly, the Math child of a SBML Level 3 Version 1 Qualitative Models package FunctionTerm, which was designed to be able to contain formulas containing SIdRefs to core SBML Level 3 Version 1 elements with mathematical meaning, but whose meaning might have been changed by a SBML Level 3 Version 1 package, may now skip the middle man and refer directly to SBML Level 3 Version 2 package SIds that have their own mathematical meaning."
Sarah, if you sign off on this, I'll close the tracker item for now. The above text is checked into SVN, and will be incorporated into RC2 of the L3v2 spec.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Personally I don't think it is justification - it is all clarification to me :-)
I did take out the explicit reference to qual FunctionTerm as it sounded like this was actually discussed in qual - which it is not. The sentence makes sense without it and I do think it is a worthwhile clarification. (I originally used qual as it is the one accepted package that adds a new math element so it was hard to find a concrete example that made sense).
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Hmm. I suppose it's not explicit in the qual spec, but it's definitely implicit in the fact that it's using Math in an L3v1 package. It would have had to be explicit if it was not designed to be used in that way. But if you don't want the example to be specific, you were the one who asked that it be specific in the first place, so I'll take that as given that you've changed your mind ;-)
Here's the new text:
"To take some examples: the reference attribute of a SBML Level 3 Version 1 Layout GeneralGlyph is of type SidRef, and was designed to be able to point to aribtrary SBML Level 3 Version 1 core and package elements. If used in a Level 3 Version 2 Core document, it could now point to an AssignmentRule, which it would not have been able to do in a SBML Level 3 Version 1 document. Alternatively, it could point to an SBML Level 3 Version 2 package element that inherited an SId from SBase. Similarly, any Math element in a SBML Level 3 Version 1 package must be designed to be able to contain SIdRefs to SBML Level 3 Version 1 Core elements with mathematical meaning, but whose meaning might have been changed by a SBML Level 3 Version 1 package. These formulas may now skip the middle man and refer directly to SBML Level 3 Version 2 package SIds that have their own mathematical meaning"
Anyone else have an opinion?
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Its not that I changed my mind - qual is the one accepted package that adds a math element. But qual does not discuss interacting with core constructs because at the time packages were very restricted in how they might do this. This has relaxed since qual was discussed ... Your original sentence sounded as though one could look up the qual spec and see how you might do this - which you cannot; hence me removing it.
What worries me is making these statements without concrete examples; which for the math case we do not actually have one. We dont want what we say here to haunt us; we already relaxed the original rules relating to interrelating math between packages/core.
Have we actually ever written the statement: "any Math element in a SBML Level 3 Version 1 package must be designed to be able to contain SIdRefs to SBML Level 3 Version 1 Core elements with mathematical meaning, but whose meaning might have been changed by a SBML Level 3 Version 1 package" anywhere else. ???
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
So, wait. Do existing qual models actually not use any core IDs in FunctionTerm MathML? If they don't and they forgot to mention this in the spec, we should come out with a new version of the spec that says that, because the obvious assumption (to me, anyway) is that any core ID could be used in package Math unless otherwise stated. Your statement "This has relaxed since qual was discussed" does not track with my recollection of the situation, though I was not in on most of the qual discussions, so maybe that's the assumption they were going with? What do you remember the original restrictions as being? (The ones you are saying were relaxed?)
I've been more involved with the spatial discussions, which, while not finalized, do have their own Math objects which have always allowed core IDs in them. This was true from the very first version, as far as I know. What Nicolas objected to was the other way 'round: using package IDs in core Math, which we now relaxed in l3v2. But packages accepting core IDs has always been assumed to be fine.
One explicit example is that the QualitativeSpecies allows a reference to a core Compartment in its 'compartment' attribute. It would be weird if you couldn't refer to the compartment by its mathematical value in the Math of the QualitativeSpecies from that compartment...
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Accepted by common consent at the 2014 HARMONY meeting.
Incorporated into SVN for L3v2, and will be part of the forthcoming release of that specification.
This was approved, but it needs to be clarified more in the spec.
Here is a new version of section 3.3.3, "Use of SBML Level 3 Version 1 packages and implications for identifiers":
Packages created and designed for use with SBML Level 3 Version~1 may be used in SBML Level 3 Version~2 documents, and be interpreted in exactly the same manner as before. They may not, however, take full advantage of the new features and constructs in Version~2. This means the following:
However, if a package defines an {SIdRef} that may refer to any \SBase, it is legal for those references to point to SBML Level 3 Version~2 {SIds}. In particular:
The upshot is: SIdRefs can reference l3v2 things; no l3v1 package SId is defined as having mathematical meaning outside of that package.
OK
Agreed.
OK
The sixth bullet point concerns me.
We say that math in L3V2 core cannot use something from an L3V1-pkg even if it has mathematical meaning. So fbc and qual cannot use initial assignments/rules etc until they have a L3V2-pkg. Personally I'm not sure I would impose this restriction but I think I am out voted on that. It might be good to come up with a case where this could go wrong and add it to the explanation in the spec :-)
I do see that opening doors without fully explaining the consequences may lead to issues and so it is in some ways safer to say you cannot use L3V1-pkg things in an anyway differently in L3V2-core without specification.
However my reading of the sixth point is that an L3V1-pkg math COULD use something from an L3V2-pkg. But surely this is also a situation where something could be done that has not been explained/thought out etc. So L3v1-pkg objects can have no mathematical meaning in L3V2-core (as it does not know about them) but an L3v2-pkg object can have mathematical meaning in an L3V1-pkg (which also does not know about them!).
I may be misunderstanding the note about SIdRefs that can be any SBase - but that might mean it needs further explanation :-)
I think the reason we impose the 'l3v2 can't use l3v1-pkg even if it has mathematical meaning' is best illustrated by the fact that 'qual' doesn't have the concept of 'time'. As a result, what exactly would it mean for a Reaction to change the level of a QualitativeSpecies over time? What exactly would it mean for an Event to change a Qualitative rate after 5 seconds have passed? What does 'delay' mean?
For the other way 'round, even in l3v1, a package could change the meaning of a core element with mathematical meaning: comp can change values aribitrarily; spatial even redefines the units of 'reaction'. As such, if a package already defined MathML that could have arbitrary elements from core with mathematical meaning, it would have to deal with l3v1 packages changing those values. It's a small step, then, to allow those packages to simply define their own symbols with their own meaning, and pull them into l3v1 package math.
I see the point about qual BUT you could use an initialAssignment (forget the semantics of the initial part!) so I think we need to be very clear as to why we universally disallow this. I agree it makes sense to not allow things until a pkg has considered the implications for itself but I would be very explicit about why.
Okay I get the l3v2 thing but it is such a niche sort of situation that I think we need to at least provide an example. - Probably for all the second set of bullet points.
Putting money where mouth is:
The L3V1 layout pkg allows an attribute of type SIdRef on a GeneralGlyph object that may point to any SBase object.
An {SIdRef} defined in a SBML Level 3 Version~1 package may be used to reference an element from SBML Level 3 Version 2 that has an {SId}, but did not have one in Version~1. Thus, a GeneralGlyph in L3V1-layout-V1 might now legitimately point to the id of an L3V2 AssignmentRule.
An {SIdRef} defined in a SBML Level 3 Version~1 package may be used to reference an element from an SBML Level 3 Version~2 package. This would allow the GeneralGlyph to point to any object in any L3V2 package (as these will have an id attribute from SBase). This applies to new versions of existing packages and any other packages that are developed to work with L3V2 core
Any \Math object defined in a SBML Level 3 Version~1 package may reference any SBML Level 3 Version~2 package {SId} defined as having mathematical meaning.
..... here I am stuck ... is this what is meant ...
The \Math object within a FunctionTerm in the L3V1-qual-V1 pkg could refer to the id of any object in any L3V2 package that has a defined mathematical meaning; provided the L3V2 package has clearly specified what the use of these ids represents when used in the L3V1-qual-V1 pkg.
This all sounds reasonable--I'll put together a new version of the text next week so people can look it over.
And yes, your final bullet point about Math matches my current thinking on the issue. However, the l3v2 package would not have to clearly specify what the use of that I meant in qual; merely what it meant in core. It is my hope that this would be sufficient.
OK, I checked in a version that adds the following paragraph. In general, I tried to go with added clarification instead of added justification, since my sense with the current editors is that we don't need so much of the latter; it clutters up what is otherwise supposed to be a technical document. That said, some justification creeps in around the edges ;-)
"To take some examples: the reference attribute of a SBML Level 3 Version 1 Layout GeneralGlyph is of type SidRef, and was designed to be able to point to aribtrary SBML Level 3 Version 1 core and package elements. If used in a Level 3 Version 2 Core document, it could now point to an AssignmentRule, which it would not have been able to do in a SBML Level 3 Version 1 document. Alternatively, it could point to an SBML Level 3 Version 2 package element that inherited an SId from SBase. Similarly, the Math child of a SBML Level 3 Version 1 Qualitative Models package FunctionTerm, which was designed to be able to contain formulas containing SIdRefs to core SBML Level 3 Version 1 elements with mathematical meaning, but whose meaning might have been changed by a SBML Level 3 Version 1 package, may now skip the middle man and refer directly to SBML Level 3 Version 2 package SIds that have their own mathematical meaning."
Sarah, if you sign off on this, I'll close the tracker item for now. The above text is checked into SVN, and will be incorporated into RC2 of the L3v2 spec.
Personally I don't think it is justification - it is all clarification to me :-)
I did take out the explicit reference to qual FunctionTerm as it sounded like this was actually discussed in qual - which it is not. The sentence makes sense without it and I do think it is a worthwhile clarification. (I originally used qual as it is the one accepted package that adds a new math element so it was hard to find a concrete example that made sense).
Hmm. I suppose it's not explicit in the qual spec, but it's definitely implicit in the fact that it's using Math in an L3v1 package. It would have had to be explicit if it was not designed to be used in that way. But if you don't want the example to be specific, you were the one who asked that it be specific in the first place, so I'll take that as given that you've changed your mind ;-)
Here's the new text:
"To take some examples: the reference attribute of a SBML Level 3 Version 1 Layout GeneralGlyph is of type SidRef, and was designed to be able to point to aribtrary SBML Level 3 Version 1 core and package elements. If used in a Level 3 Version 2 Core document, it could now point to an AssignmentRule, which it would not have been able to do in a SBML Level 3 Version 1 document. Alternatively, it could point to an SBML Level 3 Version 2 package element that inherited an SId from SBase. Similarly, any Math element in a SBML Level 3 Version 1 package must be designed to be able to contain SIdRefs to SBML Level 3 Version 1 Core elements with mathematical meaning, but whose meaning might have been changed by a SBML Level 3 Version 1 package. These formulas may now skip the middle man and refer directly to SBML Level 3 Version 2 package SIds that have their own mathematical meaning"
Anyone else have an opinion?
Its not that I changed my mind - qual is the one accepted package that adds a math element. But qual does not discuss interacting with core constructs because at the time packages were very restricted in how they might do this. This has relaxed since qual was discussed ... Your original sentence sounded as though one could look up the qual spec and see how you might do this - which you cannot; hence me removing it.
What worries me is making these statements without concrete examples; which for the math case we do not actually have one. We dont want what we say here to haunt us; we already relaxed the original rules relating to interrelating math between packages/core.
Have we actually ever written the statement: "any Math element in a SBML Level 3 Version 1 package must be designed to be able to contain SIdRefs to SBML Level 3 Version 1 Core elements with mathematical meaning, but whose meaning might have been changed by a SBML Level 3 Version 1 package" anywhere else. ???
So, wait. Do existing qual models actually not use any core IDs in FunctionTerm MathML? If they don't and they forgot to mention this in the spec, we should come out with a new version of the spec that says that, because the obvious assumption (to me, anyway) is that any core ID could be used in package Math unless otherwise stated. Your statement "This has relaxed since qual was discussed" does not track with my recollection of the situation, though I was not in on most of the qual discussions, so maybe that's the assumption they were going with? What do you remember the original restrictions as being? (The ones you are saying were relaxed?)
I've been more involved with the spatial discussions, which, while not finalized, do have their own Math objects which have always allowed core IDs in them. This was true from the very first version, as far as I know. What Nicolas objected to was the other way 'round: using package IDs in core Math, which we now relaxed in l3v2. But packages accepting core IDs has always been assumed to be fine.
One explicit example is that the QualitativeSpecies allows a reference to a core Compartment in its 'compartment' attribute. It would be weird if you couldn't refer to the compartment by its mathematical value in the Math of the QualitativeSpecies from that compartment...
Lucian, the proposed new text with this example looks good, there is just a typo "SidRef".
Thanks--fixed!
Here I am, just having announced the l3v2 spec, and I find a typo here: 'aribtrary', which did indeed make it into the final spec. Sigh.
At any rate, with the release of l3v2, this issue is now resolved!