SBML.org — the global portal for all things SBML

tmp package development page

Contents

Principles for SBML Level 3 Packages

Developers of SBML Level 3 packages are generally free to make decisions they feel are most appropriate for their packages. Nevertheless, some basic ground rules are worth having so that development of SBML packages and the SBML Core can take place in a reasonably consistent fashion. The following general principles for Level 3 packages are intended to provide basic guidance to package developers. There are two types: architectural principles and structural principles. Collectively, they constitute the basis for voting by the community on the suitability of a package at different stages in its life cycle. The principles¬†have been drawn from the history of SBML, from the specification documents for the SBML Levels 1–3 Core, and from discussions between the SBML Editors and the SBML community at large.

Architectural principles

This group of principles concerns the purpose and general direction of a package. They are also¬†used as the basis for voting on a package proposal (one of the stages of the SBML Level 3 Development Process for Level 3 packages). All package proposals and specifications must be formulated with these points in mind:

  1. Utility: A package should concern itself with a subject or problem area that many SBML users find useful.
  2. Biological orientation: The overall aim of a package should be to support the description of biological processes and phenomena. (However, this does not preclude supporting the description of other phenomena, if doing so serves the overall aim.)
  3. Orthogonality: As a general goal, SBML Level 3 and all its packages should encode every given concept only once. Data and concepts should not be duplicated in multiple components, except in extenuating circumstances or when a package is intentionally proposed as a replacement for another package.
  4. XML compatibility: The constructs defined by the package must, like SBML itself, be encodable in XML.
  5. Implementability: A specification for an SBML package should be described clearly enough that readers can understand how to implement software support for it.

If the developer(s) of a given package believe(s) that the package should not or cannot follow one or more of these principles, they must provide a compelling argument for their case.

Structural principles

Once a package proposal has been accepted and work has begun on a specification for the package, the following additional guidelines should be followed. Image:Fixme.gif [Incomplete—there are surely more of these]

  1. Validity after reduction: When an SBML Level 3 package is stripped from a model, the result left behind should be, at minimum, a syntactically valid SBML model, and preferably a semantically-understandable model.
  2. Explicitness: All of SBML Level 3, including packages, should avoid defining attributes and elements with default values that could potentially be omitted from a syntactically-valid model definition. All attribute and element values should always be written out explicitly.

Voting and acceptance of packages

There are two stages where the SBML community votes on a package. The first is when the proposal for a package is put to a vote; the second is when a full specification for the package is submitted for approval by the current SBML Editors.

Voting and acceptance of package proposals

Any member of the SBML Forum may propose the creation of an SBML Level 3 Package. Whether this proposed package is ultimately accepted as being a desirable addition to the SBML Level 3 collection is a decision made by the SBML Forum. The decision-making process is implemented via electronic voting organized by the SBML Editors.


%%% working

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"

This page was last modified 02:17, 5 August 2011.



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