SBML.org — the global portal for all things SBML

FAQ

Date of last content update: 2015-1-20

This Frequently Asked Questions (FAQ) document answers to some frequent questions about the Systems Biology Markup Language (SBML). This is a non-normative document that does not define any aspect of SBML; rather, it is intended to provide additional information in an easily accessible and readable form.

Contents


FAQ overview

What is this FAQ?

This Frequently Asked Questions (FAQ) document is an attempt to answer common questions on the concepts, structure, and other matters of the Systems Biology Markup Language (SBML). It is in addition to the official SBML specifications. This is not a normative document—it does not define anything about SBML.

Who maintains this FAQ?

The SBML Editors do nearly all of the writing and maintaining of this FAQ.

Can I help?

Ohmygawd, yes. Please use the issue tracker (preferred) or email the editors directly (if you really don't like the tracker) if you have any suggestions. This includes:

  • corrections,
  • questions that you would like to see anwered,
  • questions that you know the answer to and would like to see included,
  • suggestions for how to improve the FAQ,
  • praise.

We really do want your input.

General questions about SBML

What is SBML?

The short answer is this: the Systems Biology Markup Language (SBML) is a machine-readable exchange format for computational models of biological processes. Its strength is in representating phenomena at the scale of biochemical reactions, but it is not limited to that. By supporting SBML as an input and output format, different software tools can operate on the same representation of a model, removing chances for errors in translation and assuring a common starting point for analyses and simulations.

A slightly longer (but still relatively short) answer can be found in the separate Basic Introduction to SBML.

Is SBML free?

Yes. Totally.

Is it open?

Yes, in the sense that there are no restrictions on its use, anyone may contribute proposals, anyone may participate in discussions, there's no secret handshake to get into the meetings, etc.

What does SBML look like?

Ugly. Don't look at it, unless you're developing software, in which case, you have to look at it, and we feel for you. SBML is really not meant to be edited by hand or exposed to users.

But I really want to see an example of SBML

You're persistent, aren't you? Alright, then, have a look at the More Detailed Summary of SBML. Don't blame us if it hurts your eyes, though. We warned you, ok?

How can I find out about the model in an SBML file? It's too hard to read the XML

That's what we keep saying. As a first step, you can use the SBML2LaTeX web service to generate a report summarizing the content of an SBML file. SBML2LaTeX generates output in PDF, TeX and other formats, and provides a detailed, human-readable summary of every part of an SBML model (including the system of equations implied by the model). This nice system allows you to understand what an SBML model is about without having to look at the actual XML content. It's a good debugging tool, too. There is a link to that system from the sbml.org facilities page. SBML2LaTeX was developed by Andreas Dräger, Hannes Planatscher, Dieudonné M. Wouamba and Adrian Schröder, and the web service is kindly provided by the University of Tübingen, Germany, as a service to the SBML community.

A longer list of software that can be used for SBML creation and development as well as visualizion is also available.

What kind of models can you represent in SBML?

This question is difficult to answer directly. One way to get a sense for what can be represented in SBML is to look at the kinds of models that have been represented in SBML. A good starting place for that is BioModels Database.

However, a lot depends on how a modeler chooses to express a model. A common abstraction used when describing cellular phenomena is to describe the system as a set of chemical entities linked by processes (reactions) that can transform one entity into another or transport entities between compartments. A compartment in SBML is a location having a defined size or extent (which may be in terms of volume, area, length, or a point). Every chemical species in an SBML model must be located in a compartment. It is worth noting that compartments do not have to map one-to-one to biological structures; compartments can be conceptual too. But SBML is by no mean limited to encoding biochemical reactions. One can encode any mathematical rule linking quantitative characteristics of the biological system, including, but not limited to, electrical behaviour, growth etc. SBML can also describe discrete events that are triggered by state changes in the modeled system.

For developers working implementing SBML support, or modelers working directly with SBML, it is worth noting that while SBML's data structures are things called "species", "reaction", etc., and people often talk about SBML in those terms (even the specifications historically have done that), SBML is not limited to biochemical species and biochemical reactions. Ed Frank put it nicely in a discussion in 2005:

Most software systems do not have software entities that are one-to-one with the problem domain. Software doesn't work that way. It's almost like the problem domain and software domain are fourier transforms of each other. The problem domain has a bunch of things to be worked on or solved. The software domain has objects and object interrelations that focus on encapsulation, robustness, and extensibility. Not the same! Often systems start off with software entities that look a great deal like the problem domain, e.g., species, modifiers, etc. but in time you discover really they are a bit different and migration-cost pressures keep you from renaming them.

Does SBML have units?

Absolutely, yes. Every quantity in an SBML model can have units of measurement associated with it.

How is SBML different from BioPAX?

While BioPAX is meant to facilitate the exchange of biological pathways, SBML has been designed to facilitate exchange and reuse of quantitative models, not necessarily limited to the biochemical events. SBML models contain information about sizes, amounts and kinetics, that cannot be expressed with BioPAX. Conversely, BioPAX being an ontology, one can define much more precisely the identity of the objects considered, whether physical entities or biochemical events. In SBML, this information may be encoded using annotation with terms from the Systems Biology Ontology (SBO). Although SBML and BioPAX do not fulfill the same purpose, it is nevertheless possible to convert one into another. Examples of tools providing this service are BiNoM and BioModels Database.

How is SBML different from CellML?

CellML is another format to encode quantitative models, based on XML like SBML. CellML is being developed by the Bioengineering Institute at the University of Auckland and collaborating groups. The chief differences between CellML and SBML can be perhaps described in the following ways. While a model encoded in SBML is based on the successive, hierachical, declarations of model constituents, a CellML model is built as a network of components. A component can contain variables, mathematical expressions, metadata etc. In CellML, the biological information is entirely stored in metadata rather than the language elements. In SBML, the language elements were more directly influenced by present-day biochemical network simulation software, and the mathematical expressions are more constrained than what is permitted in CellML's subset of MathML.

A variety of tools exist to translate between SBML and CellML, though not all SBML constructs can be translated to CellML (like events), and while the math remains, semantic information is lost. Conversely, translators from CellML to SBML that do not use the Hierarchical Model Composition package lose the hierarchical information, and result in a 'flat' model. Examples of tools providing this service can be found at http://www.ebi.ac.uk/compneur-srv/sbml/converters/, and other tools can be found by searching the software guide.

Is SBML just an XML format?

Yes and no. The primary encoding of SBML is indeed XML, a popular text-based language for expressing structured data in a generic fashion. However, a design goal of SBML has always been to define it in terms of a language-independent formalism (specifically, using UML) and then map that to XML, so that mappings to other formats may be easier.

Isn't SBML too complicated to write?

Don't write SBML by hand. Instead, use software tools that provide higher-level interfaces to reading, writing, and manipulating SBML. Some provide graphical user interfaces, while others provide textual interfaces where you can write models in terms of chemical reactions. Take a look at our SBML Software Guide for help finding a tool that may be suitable for your needs.

Where is SBML defined?

The Systems Biology Markup Language is formally defined in the specification documents.

Where can I find some already-written, working SBML models?

BioModels Database provides a database of hundreds of published models in SBML format. The models in the database have been checked by humans to correspond to the publication and have been annotated with links to other data resources to make searching easier.

I've developed a model and I'd like to make it public; where can I submit it?

You can submit published models to BioModels Database. Please consult the FAQ for BioModels Database and then the submission page for BioModels Database.

Are there tutorials about SBML?

The SBML Team occasionally puts on tutorials at conferences such as the International Conference on Systems Biology (ICSB), as well as topic-specific tutorials at SBML workshops such as the SBML Hackathons. Please check the Events page and the News page on SBML.org for information about possible upcoming events.

What is the MIME type for SBML?

The MIME media subtype for SBML is application/sbml+xml and it is defined by RFC 3823 . The goal of defining a MIME type for SBML is to enable applications to recognize files and data streams as being in SBML format by virtue of being tagged with the SBML MIME type.

Is there an official logo for SBML?

Yes! Please see The_SBML_Logos_and_Policies_for_Their_Use page. These logos are ideal for putting in web pages, software documentation, and presentations to show your and your software's support of SBML.

Why does the logo resemble the SBGN and SBO logos? Are the projects linked?

Back in the earliest days of SBML and SBW, Hiroaki Kitano anticipated a series of standards for systems biology. He outsourced the creation of an "SB" logo to a designer at the Sony Corporation Design Center in Tokyo, with the intension of using the invariant "SB" part for a variety of efforts. Initially, SBML and the SBI webpages used this logo, and when SBGN and SBO were started, these also ended up using the same logo beginning.

The different projects have some coordination (mainly by virtue of involving a lot of the same people), but there's no tight coupling or official mandate. SBO and SBGN are meant to be useful to everyone, not only the SBML community.

What papers should I cite if I use SBML?

The single best paper to cite at this time is the 2003 paper in Bioinformatics, even though it describes only Level 1 and not the latest Levels/Versions of SBML:

Hucka, M., Finney, A., Sauro, H. M., Bolouri, H., Doyle, J. C., Kitano, H., Arkin, A. P., Bornstein, B. J., Bray, D., Cornish-Bowden, A. , Cuellar, A. A., Dronov, S., Gilles, E. D., Ginkel, M., Gor, V., Goryanin, I. I., Hedley, W. J., Hodgman, T. C., Hofmeyr, J.-H., Hunter, P. J., Juty, N. S., Kasberger, J. L., Kremling, A., Kummer, U., Le Novère, N., Loew, L. M., Lucio, D., Mendes, P., Minch, E., Mjolsness, E. D., Nakayama, Y., Nelson, M. R., Nielsen, P. F., Sakurada, T., Schaff, J. C., Shapiro, B. E., Shimizu, T. S., Spence, H. D., Stelling, J., Takahashi, K., Tomita, M., Wagner, J., Wang, J. (2003). The Systems Biology Markup Language (SBML): A medium for representation and exchange of biochemical network models. Bioinformatics, vol. 19, no. 4, pp. 524–531.

In addition, it would be appropriate to cite the following short paper, which discusses Level 2:

Finney, A., and Hucka, M. (2003). Systems Biology Markup Language: Level 2 and Beyond. Biochemical Society Transactions, vol. 31, part 6.

There are other papers that would be appropriate to cite in other contexts, such as the use of libSBML or the SBML Layout proposal. The relevant pages on this site or in other people's project sites provide information about the publications that describe the work. (These days, there are too many to keep a reliable up-to-date list here.)

Isn't MATLAB a perfectly fine format for representing models?

MATLAB is a fantastic system, but neither "MATLAB" or its scripting language is a model representation format.

A MATLAB file is simply a script written in a proprietary application language. This is similarly true of Mathematica format, custom C++ programs, etc. So in some deep sense, these formats are not like SBML, which aims to describe the semantic components of the model.

Equally important, the reality is that MATLAB and Mathematica scripts are really only fully runnable in only those applications. Some other systems such as Octave will run some MATLAB programs, but for many purposes, a person really has to go to MATLAB. That limits scientists' ability to reproduce each others' results, because using MATLAB or Mathematica ties them to commercial, closed-source systems.

In addition, offering models in unstandardized formats is ultimately a disservice to the consumers of the models, because they will not be able to take advantage of the ecology of software tools that has evolved around SBML and that allows models to be used in many more creative ways than how MATLAB scripts can be.

MATLAB, Mathematica, C++, FORTRAN, etc., are not standard model representation formats. Help improve science by using formats, such as SBML, that are.

Isn't SBML's definition of 'compartment' wrong? A compartment is an amount of substance!

The term compartment is used in at least two ways in modeling of biological processes, sometimes leading to confusion when models from different communities are being discussed.

The first meaning, used in modern multicompartment modeling of the sort that SBML users do, is in the sense of a vessel or container. This kind of compartment typically has the properties of location, size (usually but not always in three dimensions, and usually but not always fixed in size), and a name or identity; importantly, the compartment is not intrinsically associated with a single substance or chemical species, but instead, one or more substances are located inside the compartment. Compartments in this sense are usually assumed to be homogeneous or well-mixed, and the concentration of each species is usually taken to be an individual state variable in the model. (Sometimes, the species are referred to as pools, and the compartments are thus groupings of pools.)

By contrast, the second meaning of compartment is a substance in a location. In this second meaning, there is no notion of a container; rather, each distinct kind of substance in a location (e.g., glucose in the liver) is a compartment. This notion of compartment comes from the "bathtub models" and is still largely in use in ecological modeling or in phamacometrics modeling. For instance "glucose in the liver" and "glucose in blood" are different compartments, but "glucose in blood" and "drug in blood" are also different compartments.

The former sense, used by SBML, is fairly common in systems biology and engineering models today. An advantage of this approach is that it allows for the intuition of identifying compartments with biological structures, then talking about what happens within and between those structures. For example, a model might have compartments corresponding to such things as cytoplasm, nucleus, nuclear membrane, etc., with many different kinds of chemical entities located inside each compartment. This style of compartmental modeling is by no means new; one can find examples going back many decades. Some segments of pharmacometrics today also use compartments as vessels; this is the case for example in Physiologically-based pharmacokinetic modeling.

Finally, in this context, it is worth mentioning that in SBML, there is no requirement for compartment to correspond strictly to cellular structures. Indeed, while SBML uses terms like "species", "reaction", "compartment", it is more of a historical artifact than a limitation of sticking to purely biochemical modeling. SBML is used for more than biochemical models today.

Questions about SBML development

What are the SBML Levels?

Levels in SBML are a way of managing complexity in the continued evolution and enhancement of the language. SBML is being developed in a series of levels, where each level adds new features and fixes problems with the previous level. The lowest-numbered levels provide fundamental features that are common to all biochemical network models. Higher-numbered levels add more features that are specific to particular classes of tools. Any level can be used as a standard for interchanging models.

What are the SBML Levels/Versions/Releases/Revisions about?

As mentioned above, the Levels of SBML represent different stratifications of functionality and complexity in the SBML language. Major architectural changes are only made from level to level.

Real-world experiences with a language definition often lead to new realizations and the identification of problems. In SBML, we adopted a scheme of Versions within levels. Continued refinements and corrections to an SBML Level take place by issuing new Versions. This is why there is an SBML Level 2 Version 1, an SBML Level 2 Version 2, etc.

Within versions, we needed a scheme for handling editorial corrections that do not affect the intended syntax and semantics of an SBML Level+Version specification. This was initiated in SBML Level 2 Version 2 with the introduction of "Revisions". Unfortunately, the term "Revision" caused too much confusion, so we changed the terminology to use the term "Releases" in SBML Level 2 Version 3. The result is that specifications of SBML are now given in terms of a Level, Version, and Release.

SBML Levels are intended to coexist. For example, SBML Level 2 does not render Level 1 obsolete, and Level 1-compatible models and software tools still continue to be used. However, the matter is different within Versions. Changes between Versions within a Level represent important improvements (and in some cases, critical corrections). Consequently, we strongly encourage software developers and modelers to update software and models to conform to the latest Version within an SBML Level.

What are the differences between Levels 1 and 2?

The changes in SBML Level 2 include: replacing SBML Level 1's text-string based format for mathematical expressions with a subset of MathML, introducing support for metadata, introducing support for named function definitions, introducing explicit modifier species such as catalysts in reactions, and introducing new constructs for discrete events and time delays. In Version 2 of Level 2, additional major changes include new constructs for types of species, types of compartments, initial assignments, constraints, and a standard approach for annotating model components with cross-references to terms from ontologies and controlled vocabularies. In Version 3 of Level 2, a number of small but important corrections were introduced, the consistency of the unit system was improved, and the UML notation in the specification document was much improved in clarity. In Version 4 of Level 2, the requirement for unit consistency was removed to comply with a community vote held in 2007, and in addition, a few other restrictions were removed on component ordering in a model, and finally, a number of small corrections and changes were made to the RDF and SBO aspects.

What is SBML Level 3?

SBML Level 3 is the next step up in capability from SBML Level 2. It is designed as a modular language, with a defined core set of features (based largely on SBML Level 2) and topic-specific packages layered on top of the core. This modular approach means that models can declare which feature-sets they use, and likewise, software tools can inform users which packages they support.

Release 1 of the SBML Level 3 Version 1 Core specification was issued on 6 October, 2010. The community wiki on this web site describes the ongoing SBML Level 3 work on packages.

What are the differences between Levels 2 and 3?

The major changes in SBML Level 3 include:

  • The definition of a modular 'package' structure for extensibility.
  • No defaults: all elements of an SBML Level 3 model are either explicitly defined or are undefined.
  • The semantics of events were enriched.

Here is a table that summarizes the main changes in SBML across the different Levels:

SBML Level 1 SBML Level 2 SBML Level 3
predefined math functions user-defined functions user-defined functions
text-string math notation MathML subset MathML subset
reserved namespaces for annotations no reserved namespaces
for annotations
no reserved namespaces
for annotations
no controlled annotation scheme RDF-based controlled
annotation scheme
RDF-based controlled
annotation scheme
no discrete events discrete events discrete events
default values defined default values defined no default values
monolithic monolithic modular

Why are Level 1 and Level 2 still being kept around if Level 3 exists?

There exist tools that either were developed before the creation of SBML Level 3 or for which Level 2 (or 1) is more appropriate. SBML Level 2 therefore continues to have relevance even with the existence of Level 3.

Note that since all Level 1 models can be translated to SBML Level 2 and SBML Level 3, and all Level 2 models can be translated to SBML Level 3, tools that read SBML Level 2 can be made to support Level 3 reasonably easily. Moreover, the availability of libSBML makes it much easier for application developers to support different SBML levels in software applications. Among other features, libSBML has a built-in translation facilities between the various levels and versions.

What are SBML Level 3 'packages'?

An SBML Level 3 package is an extension of SBML, with its own namespace and specification. Each package is designed to extend SBML (and the types of models it can encode) in a particular direction. This allows software to support SBML packages appropriate to its own problem domain, while making it clear what models it will and will not be able to exchange. The first package to be fully developed, implemented, and approved by the SBML community was the Hierarchical Model Composition package, in November of 2012. This package allowed the hierarchical structuring of SBML models. Other packages and their current statuses are listed below.

What is the current status for the Level 3 packages, and how do I get involved?

Each Level 3 package effort has its own detailed status page. Please follow the links below for more information, including any specifications that may be available. This list is in alphabetical order by package label. The information in this table is drawn from the master table for Level 3 package statuses.

Package name
& link to info page
Label Description Status
Arrays arrays Support for expressing arrays of things Draft available
Hierarchical Model Composition comp A means for defining how a model is composed from other models Released
Distributions distrib Support for encoding models that sample values from statistical distributions Draft available
Dynamic Processes dyn Support for creating and destroying entities during a simulation Draft available
Flux Balance Constraints fbc Support for constraint-based (a.k.a. steady-state) models Released
Groups groups A means for grouping elements Released
Layout layout Support for storing the spatial topology of a network diagram; adjunct to the render package Released
Extended Math math A suite of packages that collectively allow MathML beyond the subset allowed in SBML core. Not started
Multistate and Multicomponent Species multi Object structures for representing entity pools with multiple states and composed of multiple components, and reaction rules involving them Draft available
Qualitative Models qual Support for models wherein species do not represent quantity of matter & processes are not reactions per se Released
Rendering render Support for defining the graphical symbols and glyphs used in a diagram of the model; adjunct to the layout package Draft available
Spatial Processes spatial Support for describing processes that involve a spatial component, and describing the geometries involved Draft available
Retired packages
Annotations annot Support for richer annotation syntax than the regular annotations in SBML Level 3 Core Superceded by COMBINE annotations effort
Required Elements req Support for fine-grained indication of SBML elements that have been changed by the presence of another package Retired due to decreased demand


SBML Level 3 package specification documents are written using a standardized LaTeX template developed by the SBML Team for this purpose. The template is freely available for use by other efforts.

Questions about software support of SBML

Is there a list of software that supports SBML?

The list of tools supporting SBML has grown to over 280 at the time of this writing. It is no longer feasible to maintain a list in this FAQ. Instead, we refer readers to the SBML Software Guide, which provides links to known software packages supporting SBML. The guide provides both a compact feature matrix as well as a longer annotated overview.

Where can I find certified SBML software?

There is no certification process for software today.

The SBML Team has been developing a comprehensive SBML Test Suite that makes it possible to test SBML support objectively and helps assess the degree of SBML support in different software packages. There is now also a database of results for different software simulation packages running the SBML Test Suite.

However, it is unlikely there will ever be a full "certification" mechanism for SBML. The development and support of SBML is funded primarily by government grants, and we simply do not have the resources it would take to run a true certification process of the sort common in industry.

Are software libraries available for programming with SBML?

Yes. The SBML Software Guide includes information about known libraries for programming SBML support. The SBML Team itself has developed several free and open-source packages that can be used to support SBML in different environments, including two libraries:

  • libSBML is a portable, embeddable API library providing language interfaces for C, C#, C++, Java, MATLAB, Octave, Perl, Python, and Ruby. It runs on Linux, MacOS and Windows. There is a recent paper describing libSBML too.
  • JSBML is a new pure Java implementation that tries to provide a similar API to libSBML.

Which "Level" of SBML should I use in my software?

As a default, we recommend supporting the highest SBML Level that your software can support, because higher levels tend to fix design problems in lower levels of SBML. However, if your software cannot support some of the features of a higher Level of SBML, a lower SBML Level may be more suitable. Note that within Levels of SBML, you should always support the highest Version of the specification for that Level.

Beyond the default, we do recommend that you make other levels and versions of SBML available for input and output. This will let users of your software more readily exchange their models with older software that might not support the latest level and version.

How many SBML Level 3 "packages" do I need to support in my software?

This can depend a great deal on what kind of software you are creating. In general, supporting as many packages as possible, and supporting translation of those models to core constructs when possible provides the greatest amount of flexibility for your users. Beyond that, preserving package information, even when your software does not understand the constructs it provides, can make your software more useful for a user who needs certain features of a package for one purpose, and to use your software for another purpose.

One of the SBML Team's goals for libSBML is to provide translators to and from package constructs to core constructs, so (for example) your simulator should be able to import a model with Hierarchical Model Composition constructs, and translate it to a model with only core constructs without changing the mathematics of the model. As other packages emerge, different translation paths will also emerge.

What if I can't encode some feature that my software has?

You can try storing the data in SBML's <annotation> elements. These are described in some detail in the SBML specification documents. The <annotation> elements can be enclosed within any SBML element and can contain elements of any namespace. Note that data stored in annotations should not contain data that could be or is encoded already in SBML.

How should I structure annotations?

The annotation data enclosed in a specific SBML element is assumed by other applications to be directly associated with that specific element. Therefore, it is important to decompose and locate annotation data appropriately in an SBML document. Avoid encoding all your annotations in a single top-level attribute. The data associated with, for example, an individual species in a model should be encoded in the <annotation> element enclosed within the SBML <species> element representing that species in the SBML file.

The SBML Level 2 and Level 3 specifications are the most complete source of information about the syntax of annotations in SBML, but it is a complex topic, and certain questions are not addressed directly in the specifications. We therefore provide a separate page with further explanations about annotations in SBML Level 2 and 3.

How should I include database identifiers such as ChEBI identifiers?

Annotations involving database identifiers can be created using the scheme described in Section 6 of the SBML Level 2 and Level 3 specifications. The approach involves using RDF annotations and specific BioModel elements and qualifiers detailed in the SBML specification. You can find examples of models using this approach in BioModels Database.

What should my software do when it encounters incorrect SBML?

Although an application can't be expected to detect all possible errors in an SBML document, it should do as much as it can to detect errors of syntax and self-consistency. Such errors indicate that something is clearly wrong and that whatever (or whoever) wrote the model made an error. You may want to double-check the validity of the model by testing it with the online SBML Validator. If the SBML file fails, the model should be rejected because it cannot be used as-is. (Incidentally, if you encounter consistent differences between an SBML specification and a software package that claims to be compliant with that specification, please report this to the sbml-interoperability mailing list.)

Detecting and handling incorrect SBML is different from detecting and handling an invalid model encoded in SBML.

How can I test whether I've implemented SBML support as intended?

The SBML Test Suite provides a large set of input files and corresponding results, and allow you to test your software's implementation of SBML handling. It contains models from every level and version of SBML, plus models that test some SBML Level 3 packages. At present, it can only test aspects of SBML that affect the numeric results of a simulation, so other constructs (such as Constraints) must be tested in some other way.

Questions about SBML features and their use

Why are non-biochemical features such as explicit equations included in SBML?

The aim of SBML is to enable the construction of quantitative models that describe both the activity of biochemical networks and interaction of biochemical networks and other phenomena. SBML allows the declaration of variables (non-constant parameters) and associated ODEs and DAEs to describe these phenomena. Examples of these phenomena include the mechanical force generated by muscle cells and the electrical potential across a synapse.

Why use MathML? It's much more complicated than text strings

Here is a partial list of motivations for why the switch to MathML was made in SBML Level 2, in no particular order:

  • The list of operators available in the text-string formula notation of Level 1 was judged to be limited. People wanted to expand the mathematical vocabulary to include additional functions (both built-in and user-defined), mathematical constants, logical operators, relational operators and a special symbol to represent time. Rather than growing the simple C-like syntax of Level 1 into something more complicated and esoteric in order to support these features, and consequently having to manage two standards in two different formats (XML and text string formulas), we chose to leverage an existing standard for expressing mathematical formulas in Level 2: the content portion of MathML.
  • There is no standard text-string formula syntax to choose from. The notation in Level 1 was inspired by C, but as many people have pointed out repeatedly, there are differences, and these differences need to dealt with by software tools parsing the infix notation. Thus, this particular problem exists no matter what notation/encoding you choose—the infix text-string notation didn't offer an advantage in this particular regard. Now imagine if we had to grow the syntax to accommodate more operators, user-defined functions, etc. Even more people would complain about differences due to a non-standard mathematical syntax.
  • Related to the above: using MathML means we can avoid having to define reserved words for various language features, such as the time symbol and the delay function. MathML has a mechanism for introducing special terms and operators without having to define new identifiers in the language. Without MathML, we would have had to choose arbitrarily an identifier for each of those quantities, and every new one that was deemed important in the future. Parsing and generating expressions using these identifiers would be problematic in tools that used different built-in symbol values (for example, if a tool uses 't' instead of 'time' for the time symbol).
  • Using MathML allows us to extend SBML without introducing new non-XML syntax. For example if we wanted to introduce some form of modularity we might want a '.' operator in expressions to reference components of submodel instances. We could agree on the introduction of a MathML operator to do this which would be tool neutral rather than again creating an arbitrary syntax, that tools would have to parse, which may or may not be similar to that used within the tools.
  • Whether you parse formulas written as text strings, or parse formulas written as MathML, your software still needs to build up expression trees. Once that's done, there is in principle not much difference between the two.
  • MathML is proper XML, which means that tools using XML parsers can work with it directly. Authors do not have to write a different kind of parser for the text-string infix syntax; they can use a generic XML parser if they wish. Further, libraries specialized for MathML could be used by software developers, possibly saving development time and effort. (Of course, the use of libSBML isolates software tools from all this even further.)
  • Making SBML all-XML means that SBML is more amenable to tools that can process, manipulate and store XML, such as (e.g.) XSLT, XQuery, XPath, and other XML technologies. To give an example of the power of this, it has made it possible to write XSLT transformations to take CellML 1.1 to SBML Level 2. It would have been difficult to construct text-string formulas from CellML reaction definitions using XSLT transformations.

All that said, there are some disadvantages to using MathML in SBML. One is that by introducing MathML part-way through the evolution of SBML, we have created a legacy support problem by having two formula representations with which to contend and interconvert. Another is that people perceive MathML to require greater effort to support, but whether this is true in practice depends on the underlying system. For some applications, it is actually easier to parse and handle MathML than a text-string representation of mathematical formulas, because the MathML expression structure is already made explicit and can be read using available XML software.

The SBML notion of a species seems peculiar, doesn't it?

Well, no, or yes, depending on your definition of "peculiar".

The SBML construct called species represents a pool, that is, a set of "things" that are treated as being indistinguishable from the standpoint of the processes (reactions) in which they participate. When the "same" species (a chemical or other thing) is present in different compartments, each must be treated as a different pool. The reason for this is because the concentrations or partial pressures being different in the various compartments means that the chemical activities are different as well. Also, the pH of different compartments being different, the electrochemical properties of a given chemical entity could be different (think about an enzyme in the cytosol and a lysosome). Analytical software will therefore have to construct different state variables for the different pools, even if the pools contain the same kind of "thing". This is actually a common concept in biochemical simulation, dating back to some of the earliest simulation software.

If you need to express a link between species with different identifiers, you can use the species type construct available in SBML Level 2, or else use the SBML annotation mechanism.

Can I have two species with the same name attribute value?

Yes, this is perfectly legal SBML. Of course, you would only want to do that if the species are actually the same conceptual type of entity—you wouldn't want to give the same names to, say, glucose-6-phosphate and ATP in a model, because it wouldn't make any sense.

Species and compartment identifiers in SBML refer to "things" that can participate in dynamical behaviors, but each identifier does not have to refer to a single unique entity. It is possible that the same conceptual entity appears in multiple contexts in a model. Since a species must be given a unique identifier in each compartment in which it appears (see the answer to the previous question for an explanation of why), it is convenient to give the species definitions all the same names. It will usually make more sense to humans that way, and software can track the separate amounts of species in the different compartments by their identifiers.

In SBML Level 2, there are additional explicit constructs for species types and compartment types. If you are using names to convey the idea that different entities are the same conceptual "thing" despite having different identifiers, you may want to indicate the relationship more strongly by defining common species types or compartment types, and then declaring the species/compartments to be of the appropriate types.

Why don't SBML Level 2 and Level 3 define a default compartment?

Software developers are sometimes bothered by the fact that SBML does not specify a default compartment; all compartments in SBML must be defined explicitly. There are several reasons for this:

  • Not all models use compartments. If SBML defined a default compartment that would be present when no compartment was explicitly defined by a model, then there would be no way for models that did not need compartments to leave it out.
  • The most likely default compartment definition would involve a 3-dimensional compartment of volume 1 in some default unit (e.g., mole). Leaving this implicit (as was possible in Level 1) turned out to be more prone to errors in the construction of models, because modelers would often forget to check the units on the size of the compartment.
  • SBML would have to define a reserved identifier to refer to the default compartment. This is a recipe for an eventual identifier collision when someone, somewhere, accidentally uses the same identifier.
  • A default compartment would only save effort in developing the SBML writing component of a software tool. The writing component is the easy part; reading and interpreting is the harder part. Defining a default compartment would not help readers much, if at all.
  • A default compartment would be a special case which all SBML parsing programs would have to handle specially.

That said, if you wish to create an explicit SBML compartment and flag it as 'the default compartment', this is perfectly acceptable. The SBO term SBO:0000410 is commonly used for this purpose, for exchangeability.

How do you represent models that don't define a compartment?

If the model uses species (in the SBML sense of species), then it will be necessary to create a compartment in the SBML representation of the model, because all species must be located somewhere. One approach is to locate all species in a single compartment with unit volume. When making changes like this to accommodate SBML requirements, it is a good idea to write a note (perhaps stored in a <notes> element inside the top-level <model> element) explaining what has been done. This will help future readers of the SBML file to understand why certain choices were made.

If the model does not use the SBML species construct, then in SBML Levels 2 and 3, no compartment needs to be defined anyway, so it should be no problem to leave out compartments.

Why is there a distinction between "assignment" and "algebraic" rules? Aren't they equivalent?

Although it is typically easy to transform between assignment and algebraic rules, SBML provides separate constructs for them, for the following reasons:

  • Algebraic rules define the point in the model where there is a circular dependency between variables. For instance, the equations x = 2 * y and y = x + 1 have a circular dependency. It is not possible to form such a dependency in scalar rules (see the SBML Level 2 specification). At least one of the example equations would have to be encoded as an algebraic rule in SBML.
  • Many tools are not capable of supporting algebraic rules (DAEs).
  • Those tools that do support algebraic rules make the distinction between assignment rules and algebraic rules.

If some tools don't support algebraic rules, why not just use assignment rules instead?

In a linear system, it will always be possible to write algebraic rules as assignment rules. However, it will often be awkward to do so, particularly when the system involves any more than three dependent variables and equations, making the assignment rule form prone to mistakes, and hard to understand.

In non-linear systems, it may be impossible to write the equations in an assignment rule form. As an example, for one model it might be true that y = ln(x) and that y = k ⋅ x. For some values of k, there will be no solution; for one value of k there will be a single solution; and for other values of k there will be two solutions.

Finally, it is the case that often in the literature, equations may be written as (essentially) algebraic rules. The partial pressure of oxygen in arterial blood is one such example.

Why can't user-defined functions be recursive in Level 2 or Level 3?

Functions definitions in SBML Levels 2 and 3 are designed to allow them to be substituted in place of the function call operator; that is, they are deliberately defined so that software tools can treat them like macros rather than functions. This would not be possible if functions were allowed to be recursive.

Why doesn't SBML provide a way to define constants?

It does. Use the SBML parameter construct and set the attribute constant to true. See the next question.

Are you saying that parameters may not be constant in SBML? That's crazy talk!

Yes, that's what we're saying, but it's not crazy talk. There are at least two reasons for doing it this way:

  • The object data structure defining a variable (other than species or compartment) and a constant would be nearly identical. The only difference is that one would be called constant and the other allowed to vary. SBML simply uses a more parsimonious representation involving the use of just one object, with a flag, constant, indicating whether the symbol value is constant during a simulation.
  • Some modelers and software systems actually do use the concept of time-varying parameters. See, for example, this FAQ item from SAAM II. In SAAM II, "any parameter could in fact be defined as time-varying".

And you probably thought we were just making this stuff up!

Why was the constant attribute on species and compartments introduced?

If a model does not contain algebraic rules, it is possible to infer which components (species, compartment and parameters) are meant to change in value by examining the set of scalar rules, rate rules, and reactions. However, if a model contains algebraic rules, you need information about which symbols are meant to be variables and which constants, to solve the system of equations. The mere occurence of a symbol in an algebraic rule doesn't imply that the symbol is a variable.

OK, you ask, but why have a constant flag on species? Why not define constant species as parameters instead? Well, if you define something as a parameter, you lose information about the nature of that symbol: a parameter has nothing on it that says whether it is meant to be the amount of a species, or a volume of a compartment, or a numeric constant of any other kind. However, such semantic information may be useful in a model—it may be useful for a model interpreter to be able to determine that a particular symbol is meant to be treated as a species amount or concentration. For example, graphical editors may be able to use this information. Defining something as a species says to an SBML reader, "this is a species, not some numerical or physical constant that defines a characteristic of the system". More detailed semantic information can of course be added using SBO labels or other annotations, but these annotations are not widely supported, so SBML provides these very primitive facilities to help software get by.

What is this "boundary condition" business?

The boundaryCondition attribute on <species> codifies the following notion: In some systems of reactions, certain chemical species are unchanged by the reactions in the system. For example, this might happen if there is a vast overabundance of the species compared to the other ones, or the particular species is maintained (buffered) by some external means. In models of such systems, it is important to be able to indicate that the model interpreter should not generate an ODE for that species. In SBML, this is indicated by setting the boundaryCondition attribute of that species to "true".

A critical point in the previous paragraph is the part that says the model interpreter should not generate an ODE from the system of reactions for species that are labeled as boundary conditions. It does not mean that there cannot be an ODE or other constraint generated as a result of a rule in the model. You can have boundaryCondition="true" for a species and that species can still appear on the left-hand side of an ODE if there is an SBML Rule for it.

Summary: boundaryCondition="true" means do not generate an ODE for this species from the stoichiometry matrix of the system of reactions.

Why can't you assign different units of time to (e.g.) event delays?

SBML Level 2 Version 1 provided this capability. It defined unit attributes on various SBML components such as kinetic laws and event delays, letting a model redefine units for individual quantities. Unfortunately, this turned out to introduce serious practical problems. First, one could construct models in which it was impossible, without additional information, to convert quantities to the same consistent units throughout the model (a necessary prerequisite to constructing a system of equations from the model definition). Second, and in practice more important, the freedom to reassign units in so many different contexts may have been convenient for model writers, but it made it hugely more difficult for model readers to interpret a model—it placed a large burden on the software interpreting a model. And third, it was much more error prone, with modelers creating models where they did not realize they had made unintended errors in unit consistency.

SBML Level 2 Version 2 removed most of the places where units could be redefined on individual components, but left some (notably, the time units on event delays). SBML Level 2 Version 3 further removed these attributes. These actions were taken based on the experiences of SBML users and developers. (See, for example, this discussion thread from 2005.)

How can I achieve Level 2 semantics for events using the new event semantics in Level 3?

In SBML Level 2, once fired, all events were (eventually) executed. This behavior is equivalent to setting the new persistent flag on the Trigger to true.

Similarly, in SBML Level 2, no event could fire at the beginning of the simulation (time = 0), as no transition of the Trigger's boolean state could take place at that time. Now that the Trigger's boolean state is defined with the initialValue attribute, a transition from false to true is possible: the old behavior is equivalent to setting the initialValue to true.

Another change in SBML Level 3 is that when multiple events were to be executed at the same time in SBML Level 2, the order in which those events were to fire was left undefined, and was in fact undefinable. In fact, some read the specification to say that not only was the order undefined, the behavior of the simulator was undefined entirely. A clarification was issued to say that it was only the order of event firing that was left undefined in the SBML Level 2 specification, but regardless, we have attempted to be much clearer in this specification as to what exactly is undefined when, and how the modeler may override the old "undefined" behavior with the new Priority object. Level 2 behavior may be replicated by simply not including the new Priority object.

What are the semantics of the new initialValue attribute on Level 3 event Triggers?

The initialValue attribute is a Boolean value added in L3 so that events could trigger at the start of the simulation (time = 0). It is considered to be the value of the trigger before the simulation begins; at the point at which the simulation starts, the value of the trigger changes to its normal value. If this means that the initialValue attribute of the trigger was false but its boolean expression evaluates to true at time = 0, this counts as a false-to-true transition, and the event is triggered.

If a parameter has no units declared, what units does it have?

SBML assumes that the parameter has the units appropriate for its use within a model. In some cases it may be possible to derive these units from a mathematical expression using the parameter; assuming that the units of all other parts of the expression are known.

However, if parameters with undeclared units are used, it makes checking unit consistency difficult if not impossible. It is therefore advisable, where possible, to include units for parameters within a model.

I want to use fractional exponents on units, how can I do this?

The SBML unit construct restricts the attribute exponent to an integer value. Thus, it is not possible to explicitly declare a unit with a fractional exponent. There are also restrictions on the units of expressions to which power or root functions may be applied. These restrictions are required to ensure that parameters and mathematical expressions used within SBML are physically sensible.

It is possible to overcome the restrictions by declaring additional parameters, with appropriate units, that can be used to normalise values within expressions. For example, consider an expression such as [A]^\frac{1}{2} * [B]^\frac{1}{2} where [] denotes a concentration. This would not be a valid expression within SBML since it produces intermediate units of concentration1/2. To correctly encode this, declare a parameter p, with value 1 and units equal to the units of concentration. Using this parameter and rewriting the expression as [\frac{A}{p}]^\frac{1}{2} * [\frac{B}{p}]^\frac{1}{2} * p produces the same numeric result, whilst preserving physically sensible units at all stages of the calculation.

Does the 'same units' in assignments mean dimensionally or actually equivalent?

It means they must actually be the same!

There are several constructs in SBML where a mathematical expression can be used to assign value to a variable (species, compartment or parameter) within the model. The specification states that the units of both sides of the equation should be the same. This refers to the actual physical unit, not the dimensionality—metre is not the same as foot !

Why does SBML Level 2 require an XML declaration?

Readers familiar with XML may note that XML version 1.0 does not require an XML declaration; the requirement was introduced in XML 1.1. Nonetheless, SBML Level 2 requires the declaration. The motivation comes from the practical experiences of SBML software developers, who have found that different XML parsers on different operating systems make different default assumptions if the XML declaration is omitted. Requiring the declaration of the XML version and encoding is an aid to greater compatibility between different systems exchanging SBML.

What is the hasOnlySubstanceUnits attribute for?

Broadly speaking, a value of true for hasOnlySubstanceUnits on a species declaration means that wherever the species' identifier appears in a mathematical formula, its units are to be interpreted as substance units only, and not substance/size (i.e., concentration or density) units. Note that this is regardless of how the species' initial quantity is defined: no matter whether the species is given a concentration or a substance value, if it has hasOnlySubstanceUnits=true, then the identifier of the species always stands for substance units.

This is an admittedly badly-named attribute. A better name might have been "symbolMeansAmount" or "hasSubstanceValue". Despite the poor name, the consensus among SBML people is changing the name is not worth the cost and hassle of backward incompatibilities a name change would create.

What is the symbol for time in SBML?

The way to access time (i.e., the current time in "simulation time") is using the MathML <csymbol> construct. This is probably easiest to explain using an example:

<math xmlns="http://www.w3.org/1998/Math/MathML"> 
  <apply> 
    <plus/> 
      <ci> x </ci> 
      <csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/time"> 
           t 
      </csymbol> 
   </apply> 
</math> 

The expression above encodes the formula x + time, where time signifies the current point in time during a simulation.

Important: there is frequent confusion around the purpose of the content of the <csymbol> element (i.e., the t in the example above). It is meaningless and inaccessible to simulations. The t has no relationship (except perhaps accidental) to whatever symbol might represent time in a given software environment or model. According to the MathML specification, software tools may display this content (again, the t) to users, so very often, the content of the <csymbol> is chosen to be something evocative. But the actual entity representing time in an SBML model is the <csymbol> element itself, not the content of this element. In summary, don't pay attention to t.

Why doesn't SBML require consistent units?

SBML Level 2 Version 4 and SBML Level 3 do not require models to have units declared or to have consistent units—correctness and consistency of units is not a condition for a valid SBML encoding of a model. This may seem strange, so some words of explanation are warranted. The decision to relax requirements of unit consistency was made via a community vote in 2007 and it represents a change from Level 2 Version 3. The realization that this position had to be taken resulted from many people's long experience with encoding models. There are multiple reasons for the decision, but probably the most convincing argument is the following. There exist models in the published literature that have inconsistent units. Regardless of what one thinks about such models, if we want to allow SBML to encode them as published, SBML cannot require consistency of units as a precondition of a valid SBML encoding. If an inconsistency were treated as an error of SBML encoding, then it would be impossible for SBML to encode such models.

Why can't I use the <rem> operator in SBML MathML?

When the decision came about to use MathML instead of infix strings, it was decided to keep the MathML subset allowed in SBML documents as small as possible. The allowed subset mirrors closely what was allowed in the infix format. This was done to ensure rapid adoption of MathML.

Because of these reasons some relatively straightforward MathML operators such as <rem> (remainder) were omitted. It should be noted however that it is relatively easy to implement the missing functions using user-defined functions (i.e., via the SBML functionDefintion construct). On the example of the remainder, we could rewrite the rem operator as:

 a rem b = a - b*floor(a/b)

which in SBML would look like this:

<functionDefinition id="rem" name="remainder">
  <math>
    <lambda>
      <bvar>
        <ci> a </ci>
      </bvar>
      <bvar>
        <ci> b </ci>
      </bvar>
      <apply>
        <minus/>
        <ci> a </ci>
        <apply>
          <times/>
          <ci> b </ci>
          <apply>
            <floor/>
            <apply>
              <divide/>
              <ci> a </ci>
              <ci> b </ci>
            </apply>
          </apply>
        </apply>
      </apply>
    </lambda>
  </math>
</functionDefinition>

in order to use this remainder then in another MathML expression, one would call it like any other user defined function:

<math>
  <apply>
    <ci> rem </ci>
    <ci> a </ci>
    <ci> b </ci>
  </apply>
</math>

Note: Strictly speaking the remainder operator is:

 a rem b = a - b*truncate(a/b) 

where truncate always rounds toward zero. If that would matter for a model above one would replace the <floor/> expression by a piecewise expression:

 piecewise(floor(a/b), gt(a/b, 0), ceil(a/b)) 

to read:

 
<functionDefinition id="rem" name="remainder">
  <math>
    <lambda>
      <bvar>
        <ci> a </ci>
      </bvar>
      <bvar>
        <ci> b </ci>
      </bvar>
      <apply>
        <apply>
          <minus/>
          <ci> a </ci>
          <apply>
            <times/>
            <ci> b </ci>
            <piecewise>
              <piece>
                <apply>
                  <floor/>
                  <apply>
                    <divide/>
                    <ci> a </ci>
                    <ci> b </ci>
                  </apply>
                </apply>
                <apply>
                  <gt/>
                  <apply>
                    <divide/>
                    <ci> a </ci>
                    <ci> b </ci>
                  </apply>
                  <cn type="integer"> 0 </cn>
                </apply>
              </piece>
              <otherwise>
                <apply>
                  <ceiling/>
                  <apply>
                    <divide/>
                    <ci> a </ci>
                    <ci> b </ci>
                  </apply>
                </apply>
              </otherwise>
            </piecewise>
          </apply>
        </apply>
      </apply>
    </lambda>
  </math>
</functionDefinition>

Why have SpeciesType and CompartmentType disappeared in Level 3?

In reality, SpeciesType in SBML Level 2 was a construct intended to support the ability to define "generalized reactions", as well as multicompartment entities. The idea of generalized reactions is to allow easy definition of reactions that take place in different compartments but otherwise are identical; this is essentially the concept of rule-based reactions of a sort found in systems such as BioNetGen. However, while SpeciesTypes and CompartmentTypes were accepted for introduction in SBML Level 2, the SBML community rejected the introduction of generalized reactions. Thus, the primary purpose of the SpeciesType construct was never realized. Moreover, it also turned out that in the 4 years of the existence of SpeciesType and CompartmentType in Level 2, very little software support was developed for them. As a result of these considerations, during the development of SBML Level 3, it was decided that these constructs did not belong in Level 3 Core, and any such constructs should be moved instead to Level 3 packages. (Some discussion of the reasoning can be found on a separate page.)

I used SpeciesType to manage cross-references of similar entities—what do I do now?

Some software systems use SpeciesType as it is intended in SBML Level 2, to represent the class or type of entities that may appear in multiple compartments in a model. Some of those software systems also annotate those types with references to database entries. It may appear that the apparent loss of SpeciesType in Level 3 is a going to be a problem for them. However, consider the following:

  1. SBML Level 2 is not dead. Not only are SBML Levels supposed to co-exist (as mentioned elsewhere in this FAQ), but software supporting Level 2 will continue for many years—after all, just because Level 3 has been introduced does not mean that software will suddently stop supporting Level 2. Software developers are much more likely to only add support for Level 3 while simultaneously maintaining support for Level 2. So models and tools can be fully expected to continue supporting Level 2 for the foreseeable future. If your modeling efforts need Level 2's SpeciesType construct, by all means, continue to read and write Level 2.
  2. SpeciesType are part of the Level 3 Multi package. They will, therefore, be available as soon as the package is finalized.
  3. Another upcoming Level 3 package, Groups, will provide a generalized grouping mechanism that should serve for lumping annotations and other information about similar entities in a model.

Do I have to put assignment rules in any particular order?

A question that arises in SBML Levels 2 and 3 is whether the list of AssignmentRule constructs should be taken as-is or reordered. While ordering doesn't matter mathematically, it does matter for numerical integrators. It is therefore best practice to reorder the list of rules. For example, if a model definition contained rules equivalent to the following:

b = a + 10 {seconds}
a = time

then to make the evaluation rules independent of the steps sizes used by numerical integrators, you will want to reorder the rules thus:

a = time
b = a + 10 {seconds}

Beginning with libSBML version 5.2.0, libSBML provides an API to reorder all the assignment rules in a model. Here is a C++ example of calling this API:

 ConversionProperties props;
 props.addOption("sortRules", true, "sort rules");
 SBMLConverter converter;
 converter.setProperties(&props);
 converter.setDocument(&doc);
 converter.convert();

Why doesn't SBML allow more than one assignment rule for the same symbol?

The set of AssignmentRule constructs in a model can only have one occurrence of a given symbol in the left-hand side of the assignments. The reason is because SBML fundamentally cannot stipulate what algorithms may or may not be applied to a model. Therefore, it cannot define such things as when or how often rules are evaluated. (For instance, SBML doesn't define the order with respect to evaluating reactions.) The implication of that is that rules in SBML must not change the state of a model no matter when, or how often, they might be evaluated. Such a situation might not hold true if SBML allowed more than one assignment rule for a given variable.

If SBML allowed the same symbol to appear in the left-hand side of multiple assignment rules, then it would have to also tell software developers when and how those left-hand sides (and reactions, and events, and etc.) must be evaluated. Imagine the arguments people would have then!

Instead, SBML doesn't limit the solution methods applied to models; it just provides a way to represent the mathematical model. This fact is considered to be a strength of SBML, and has allowed many more applications of SBML than only time-course simulation.

A related question that arises in this context is, "what about the model as the user defined it? What if you want to preserve how they wrote the model, including the ordering of assignments?" This is often asked in reference to software environments that allow users to type models using a script-language interface. The answer to the question is the following. If the software wants to preserve and recreate what the user typed, it can write annotations into the SBML to describe what the user typed literally. Then the software could do the restructuring required to fit the software's object model to SBML's object model, and still have a way to store and recover a view of what the user actually typed.

Some applications have their own native formats and read/write that; this feature allows them to reconstitute more precisely what the user typed. Those applications then read/write SBML solely as an exchange format, with the understanding that it will not be as rich of a representation as the tool's native format.

Questions about the SBML development process

Where did the name "SBML" come from?

When SBML was first conceived, around the year 2000, Hiroaki Kitano suggested the name Systems Biology Markup Language. The name stuck.

What is the overall SBML development process?

SBML development has been and continues to be motivated and directed by the systems biology community. The process is managed by the SBML Editors (see next question), but they do so under the control of the community. The editors collect proposals for changes to SBML from the SBML Working Groups and from other groups and individuals, and then seek to establish a consensus in the community about how to proceed with the proposals. With this information, the editors assemble some of the proposals into a draft specification for a new edition of SBML. After this draft has been reviewed by the community, it becomes a final specification for the new edition of SBML. (Edition in this context can be either a new SBML Level, or a new version of an existing level, or a new release of an existing version.)

Who are the SBML Editors?

The SBML Editors are listed on a separate page on the sbml.org website. There are always five editors, each serving three-year terms.

What are the annual SBML Meetings?

For many years, there were SBML-specific meetings, formally entitled Workshops on Software Platforms for Systems Biology. They were often held as satellite workshops of the annual International Conference on Systems Biology (ICSB), usually in the fall or early winter of every year. SBML Forum meetings allow for significant discussion of new SBML proposals and interoperability issues.

In 2010, the first COMBINE meeting was held, with the intention of including other, parallel standards development groups in systems biology and beyond. These meetings have continued annually since then.

In parallel since 2003, regular hackathons have been held: working meetings where the focus is on software interoperability and developing solutions to issues of SBML support. In 2010, these hackathons were also opened up to the wider biological standards community, and renamed HARMONY (HAckathon on Resources for MOdeliNg in biologY). These meetings have also continued annually since then.

Presentations and other materials from every meeting are archived in the Events area of the SBML.org website.

Why isn't SBML part of a standards process like OMG?

Some time ago, the SBML Editors at the time considered submitting SBML as a proposal to the Object Management Group (OMG) in response to a request for proposals (RFP) for pathways representations. However, the SBML community decided at the 7th Forum meeting that while it would be useful to have the endorsement of a standards body like the OMG, people's time and resources would be better spent working on SBML development rather conforming to all the standards requirements of the OMG process.

This does not rule out the possibility of seeking standards-body recognition sometime in the future.

Note that there is a standard MIME type for SBML; see the relevant separate entry in this FAQ.

How do I report errors and issues in the SBML specifications?

Please use the issue tracking system in the SourceForge project area for SBML. To view reported issues in the tracker, use the Category pull-down menu to select the desired SBML Level+Version (e.g., "SBML Level 3 Version 1"), and then click "Browse".)

How do I propose changes or additions for SBML Level X?

There are several ways, with the first one below being preferred because it's the quickest and easiest:

  1. Start a discussion on the sbml-discuss list/forum. This is sure to provoke a response Image:icon_smile.gif. Doing so also helps find out whether the capability is not already in SBML in some other form, because someone will point out if it is.
  2. You can also attend an SBML event, in particular the annual SBML Forum meetings, where proposed changes to SBML are a major discussion topic.
  3. Finally, if you are shy or just want to pose a question in advance of making public statements, you can send email to the SBML Editors.

SBML development is too slow—can't it be faster?

This is a can't-win situation. The archives of the sbml-discuss mailing list as well as anecdotes from SBML workshops show that for every person who complains about SBML development being too slow, there is another who complains SBML is changing too rapidly. It seems impossible to please everyone.

Where does the funding come from to keep SBML development going?

The initial development of SBML from its inception through the year 2003 was principally funded by the Japan Science and Technology Agency under the ERATO Kitano Symbiotic Systems Project headed by Hiroaki Kitano. Many agencies and commercial organizations supported smaller parts of overall SBML development as well as workshops and travel expenses. Many more academic organizations supported people who spent considerable time working on SBML and related projects despite that it was not an official aspect of their research. Since 2003, the primary source of stable funding has been the National Institute for General Medical Sciences under grant GM070923 to Michael Hucka (Chair of the SBML Editors). A more detailed list of funding acknowledgments is available on a separate page.

What's the history of SBML releases?

SBML has been in active development since the year 2000. The various official SBML releases have been:

  • SBML Level 1 Version 1 March of 2001
  • SBML Level 1 Version 2 August of 2003
  • SBML Level 2 Version 1 June of 2003
  • SBML Level 2 Version 2 September of 2006
  • SBML Level 2 Version 3 June of 2007
  • SBML Level 2 Version 4 September of 2007
  • SBML Level 3 Version 1 October of 2010
  • SBML Hierarchical Model Composition package for SBML Level 3 Version 1 November 2012

Releases since then can be found at Documents/Specifications

The first version of SBML was spearheaded by the Caltech ERATO Team, under the leadership of Hiroaki Kitano, who hosted the 1st Workshop on Software Platforms for Systems Biology in April of 2000. Since then, there have been an average of more than two meetings, hackathons, and workshops a year at which the future of SBML is discussed and implemented, supplemented by continual discussion on the mailing lists. Recent development (in early 2013) has focused on SBML Packages, with several approaching their first releases.

Miscellaneous questions

I have some SBML that hasn't been formatted nicely. Is there a way to clean it up?

LibSBML includes a demo program that simply echoes whatever SBML is given to it, and in the process of writing the output, it does a pretty reasonable job of pretty-printing the XML. The reformatting facility is actually built into libSBML (it's what libSBML does automatically), not the demo program, which means any application you build with libSBML will do it too.

If you want a more general solution with more control over formatting, you may want to look at HTML Tidy, a free, open-source, general-purpose pretty-printer which (despite its name) will work with XML too. It can be embedded into applications. Bruce Shapiro and Mike Hucka have also written a simple shell script to run Tidy from a Linux/Unix command line.

What is the difference between sbml.org and sbml.info?

There is no difference. They are alternative names for the same website, provided as a convenience to SBML users and web searchers. We tend to refer to "the SBML site" or "the SBML portal" as being http://sbml.org, but the other address should work just as well.

Who runs sbml.org?

The SBML Team maintains the server at the BNMC, located at the California Institute of Technology, in Pasadena, California, USA.

What's the difference between all the SBML mailing lists?

The SBML community has a number of mailing lists implemented as Google Groups:

Google Group & archive Purpose of this group/mailing list RSS feeds info page
sbml-announce Low-volume, broadcast-only list for announcements of importance to the SBML community, such as new releases of SBML specifications and upcoming SBML-related events. RSS feeds info
sbml-discuss Main list for SBML development and community interaction. Questions about libSBML or JSBML or other software usage should not be sent here—use one of the other forums listed below. Announcements related to SBML-compatible software are accepted, but no other advertisements are permitted. RSS feeds info
sbml-interoperability Discussions of use and interoperability of all software that supports SBML. LibSBML questions and other topics are perfectly acceptable here. RSS feeds info
libsbml-development Technical discussions specifically about libSBML and its development, including requests for new features and questions about its operation. RSS feeds info
jsbml-development Technical discussions specifically about JSBML (a pure Java SBML library) and its development. RSS feeds info


In addition to the discussion groups above, there is one more mailing list, an automatic notification list hosted by SourceForge.net; it does not have a Google Group equivalent:

Link to subscription page Purpose of list/forum
sbml-svn Automatic broadcast-only list receiving mail whenever a change is committed to the SVN repository. (There is only a single list for all changes to the SBML project. SourceForge.net does not provide facilities for limiting the notifications to a subproject. You may wish to set up your own mail filters to do that.)


Finally, in addition to all of the above, there exist separate mailing lists for the package working groups. The mailing lists for the package working groups are listed above.

Under no circumstances will we willingly divulge the memberships of the mailing lists to third parties.

Does SBML have a Twitter feed?

Yes! It's @sbmlnews.

Does SBML have a Google Plus page?

Yes! It's +SBML.

Where can I find recent presentations and papers about SBML?

One place where material is often posted is on Nature Precedings. If you search for SBML there, it will turn up content that has "SBML" anywhere in it. (The links in this paragraph are set up to do just that—click the preceding links to run the search in Nature Precedings immediately.)

What are some publications that accept SBML format?

We keep a list on a separate page of journals that we know accept submissions of SBML files (e.g., for supplemental files). The list includes many prominent journals such as Nature. The list is unfortunately incomplete because it is difficult to learn when a publication starts supporting SBML.

Retrieved from "http://sbml.org/Documents/FAQ"

This page was last modified 14:48, 20 January 2015.



Please use our issue tracking system for any questions or suggestions about this website. This page was last modified 14:48, 20 January 2015.