SBML.org — the global portal for all things SBML

tmp package development page Lucian

Contents

Guidelines for SBML Level 3 Package Development

As packages are developed, the package developers are in general free to make whatever decisions they feel are best for their package, within the following guidelines. When voters and editors are called upon to judge a package, they are to use these guidelines, and only these guidelines, in their evaluation.

The guidelines themselves are drawn from the principles that have guided SBML core development over the years. When compiling this list, many of them were lifted from the 'Introduction' section of the SBML Level 3 specification. Other guidelines have been drawn from online and in-person discussions of the community and of the editors.

  • Biology oriented: SBML is oriented towards describing biological processes, but may encompass any number of topics within that broader framework.
  • XML-encoded: SBML is defined neutrally, but must be encodable in XML.
  • Analysis-neutral: Any modeling approach should be able to take the information in an SBML model and perform its analysis on it, but still be able to exchange it with another tool that takes a different approach.
  • Community developed: SBML is developed as a community.
  • Implementable: The SBML specifications should be described clearly enough to implement.
  • Useful: The SBML concepts should be useful enough for a tool to want to implement it and make use of it.
  • Coherent: Taken together, SBML Level 3 and all its packages should encode each concept only once, in a way that can be used if needed by any new package. No package should redefine a concept already covered by another package or by Level 3 core.

In addition, there are some design principles for the specification that should be used when applicable to package development:

  • No defaults: No attribute or element of SBML should have a 'default value', defined in the specification, that could have been explicitly encoded in the model instead.
  • Syntactic validity: SBML package constructs, when stripped from a model, should leave behind a valid, if not semantically understandable, model.

If a package developer believes that their package should not or can not follow these principles, they must provide a compelling argument as to why that is.

Voting and Acceptance of Packages

There are two stages, as defined in the SBML Level 3 Development Process, where the community judges a package proposal. The first is at the stage when the general approach of the package can be approved by a community-wide vote, and the second is at the final stage, when the full specification can be approved by the current editors. In both cases, the above principles shall be the standard against which the proposal is judged. The idea is not to get caught up in the minutiae about whether a certain attribute should be an integer or a double, or whether the name of a particular element should be changed. Those questions can and should be brought up by the package working group as the proposal is developed. At the approval stage, only the above principles should be considered.

As such, the voting form for the packages will consist of several statements based on the above applicable principles (not all of which are relevant at this early stage of package development), each of which the voter agrees or disagrees with as follows:

The statements will be as follows: (Not all of the above principles are applicable at this early stage of package development, so not all are included.)

  • Biology oriented: The proposal describes a need in the biological community best addressed by an SBML package.
    • []Mostly []Not yet [] Not enough information provided to comment
  • Analysis-neutral: The information the package proposes to store can be used by all known approaches of analyzing or otherwise utilizing that data.
    • []Mostly []Not yet [] Not enough information provided to comment
  • Useful: The information the package proposes to store will enable tool writers to solve the need the proposal addresses.
    • []Mostly []Not yet [] Not enough information provided to comment
  • Coherent: The package extends SBML in a way that follows naturally from Level 3 Core and other packages, re-using concepts as needed, and integrating new concepts naturally into existing frameworks.
    • []Mostly []Not yet [] Not enough information provided to comment

Then we have one final statement:

  • Conclusion: Based on the above criteria, the package has reached the point where further detailed development is appropriate.
    • []Agree []Disagree []Need more information to judge []Abstain

The meaning of the final votes are as follows:

  • Agree: The proposed approach is in line with the stated principle.
  • Disagree: The proposed approach is not in line with the stated principle.
  • Need more information to judge: The proposal is insufficiently clear or explicit enough for an informed user to be able to tell whether the proposed approach is in line with the stated principle or not.
  • Abstain: The voter does not consider themselves to be able to properly judge whether the proposed approach is in line with the stated principle or not.

No specifics are provided as to the length of a proposed package approach, except to say that the members of the SBML community will be judging it based on the above statements. Some packages may be simple enough that a few paragraphs may suffice. Some may need more detailed write-ups. All write-ups should include a statement about the need their proposal addresses, and the approach they are taking to meet that need.

Any proposal that is not approved by the community (where the majority of non-abstaining voters did not vote 'Agree' on the final statement) may re-write and re-present their proposal after a minimum period of XXX [Three? -LPS] months have passed. Proposers are advised to consider the reason the vote failed the first time--if it was because more people voted 'Disagree' and 'Not yet', a new approach is probably called for, while if people voted 'Not enough information', more detail may be all that is needed. Comment boxes will be provided to voters so that more detailed feedback may be provided.

The Package Working Group

As the "Community" principle states, SBML is developed by a community of users and tool-writers. For packages, this is most directly addressed by the formation of a package working group after the proposal has been approved by the community as a whole. Package developers should strive to solicit feedback from this group, and to keep the group abreast of package developments in a timely manner, so that concerns can be addressed quickly, and new ideas can be incorporated early on in the process.

As far as the other principles and guidelines here go, it is the job of the package working group to make sure they are being followed as the package is developed. Within those guidelines, they are free to make whatever decisions they deem necessary. Each package working group will have an editor assigned to that group to provide assistance and guidance when needed.

For the format of the specification itself, the following recommendations are made:

  • To follow the format of the SBML Level 3 core specification, when appropriate.
  • To use UML diagrams to describe XML elements, but to also have a full description of the elements in the text.
  • To use color to distinguish between Level 3 core elements, Level 3 core elements that have been extended by the package, and new elements introduced by the package.
  • To use color to highlight changes in new versions of the specification.

Final approval

There are two requirements for a package specification to become officially part of SBML. First, it must be implemented by at least two tools. Secondly, it must be approved by the SBML Editors.

'Implemented by two tools' means:

  • The tools in question must be tools that process the information in some way, not just store and retrieve the information. For this reason, libsbml does not qualify as 'a tool', though it may be used by tools.
  • The two tools must each implement manipulation of the majority of the features of the package.
  • Every feature of the package must be implemented and be manipulatable by at least one tool.

Exactly what 'the majority of the features' and 'manipulatable' means is left to the package working group to decide.

Approval by the SBML Editors means that the package will be judged according to its adherence to the guidelines and principles listed above. In particular, the editors will be asking themselves the following questions:

  • Biology oriented: This was approved by the community at the beginning; has the focus changed since then?
  • XML-encoded: Does the specification describe an XML structure? Does it follow XML 'best practices'? If there is an appropriate XML construct for a particular concept, is it used, or is there a good reason why it is not used?
  • Analysis-neutral: What are the various ways one can analyze the data stored with this package? Are they all accommodated by this package? Is there a bias in favor of a particular approach?
  • Community developed: Was the package working group consulted along the way as key decisions were made? Are there any lingering community issues that have not been resolved around this package?
  • Implementable: Do the two implementations work?
  • Useful: This was approved by the community at the beginning, and the two implementations also imply a degree of usefulness, so hopefully this principle is already clearly met.
  • Coherent: Are there concepts in this package that are already encoded in a different package? If so, could they be synchronized? Are the new constructs tied, where appropriate, to Level 3 core concepts, or to other package constructs?

From a design standpoint:

  • No defaults: Can you encode the same model by including and not including a particular element or attribute? If so, is there a clear reason, stated in the spec, why this is superior?
  • Syntactic validity: When this package is stripped from a model, is the remaining model valid SBML? Conversely, if other packages are stripped from the model, are this package's constructs still valid? If not, is there a clear reason, stated in the spec, why this is so?

Retrieved from "http://sbml.org/Community/Wiki/tmp_package_development_page_Lucian"

This page was last modified 00:41, 4 August 2011.



Please use our issue tracking system for any questions or suggestions about this website. This page was last modified 00:41, 4 August 2011.