SBML

SBML has three main purposes:

• enable the use of multiple software tools without having to rewrite models to conform to every tool's idiosyncratic file format;
• enable models to be shared and published in a form that other researchers can use even when working with different software environments;
• ensure the survival of models beyond the lifetime of the software used to create them.

SBML is not an attempt to define a universal language for quantitative models. SBML's purpose is to serve as a lingua franca—an exchange format used by different present-day software tools to communicate the essential aspects of a computational model.[12]

SBML can encode models consisting of entities (called species in SBML) acted upon by processes (called reactions). An important principle is that models are decomposed into explicitly-labeled constituent elements, the set of which resembles a verbose rendition of chemical reaction equations (if the model uses reactions) together with optional explicit equations (again, if the model uses these); the SBML representation deliberately does not cast the model directly into a set of differential equations or other specific interpretation of the model. This explicit, modeling-framework-agnostic decomposition makes it easier for a software tool to interpret the model and translate the SBML form into whatever internal form the tool actually uses.

A software package can read an SBML model description and translate it into its own internal format for model analysis. For example, a package might provide the ability to simulate the model by constructing differential equations and then perform numerical time integration on the equations to explore the model's dynamic behavior. Or, alternatively, a package might construct a discrete stochastic representation of the model and use a Monte Carlo simulation method such as the Gillespie algorithm.

SBML allows models of arbitrary complexity to be represented. Each type of component in a model is described using a specific type of data structure that organizes the relevant information. The data structures determine how the resulting model is encoded in XML.

In addition to the elements above, another important feature of SBML is that every entity can have machine-readable annotations attached to it. These annotations can be used to express relationships between the entities in a given model and entities in external resources such as databases. A good example of the value of this is in BioModels Database, where every model is annotated and linked to relevant data resources such as publications, databases of compounds and pathways, controlled vocabularies, and more. With annotations, a model becomes more than simply a rendition of a mathematical construct—it becomes a semantically-enriched framework for communicating knowledge.[13][14]

SBML is defined in Levels: upward-compatible specifications that add features and expressive power. Software tools that do not need or cannot support the complexity of higher Levels can go on using lower Levels; tools that can read higher Levels are assured of also being able to interpret models defined in the lower Levels. Thus new Levels do not supersede previous ones. However, each Level can have multiple Versions within it, and new Versions of a Level do supersede old Versions of that same Level.

There are currently three Levels of SBML defined. The current Versions within those Levels are the following:

• Level 3 Version 2 Core, for which the final Release 2 specification was issued 26 April 2019
• Level 2 Version 5 Release 1
• Level 1 Version 2

Open-source software infrastructure such as libSBML and JSBML allows developers to support all Levels of SBML their software with a minimum amount of effort.

The SBML Team maintains a public issue tracker where readers may report errors or other issues in the SBML specification documents. Reported issues are eventually put on the list of official errata associated with each specification release. The lists of errata are documented on the Specifications page of SBML.org.

Development of SBML Level 3 has been proceeding in a modular fashion. The Core specification is a complete format that can be used alone. Additional Level 3 packages can be layered on to this core to provide additional, optional features.

The Hierarchical Model Composition package, known as "comp", was released in November 2012. This package provides the ability to include models as submodels inside another model. The goal is to support the ability of modelers and software tools to do such things as (1) decompose larger models into smaller ones, as a way to manage complexity; (2) incorporate multiple instances of a given model within one or more enclosing models, to avoid literal duplication of repeated elements; and (3) create libraries of reusable, tested models, much as is done in software development and other engineering fields. The specification was the culmination of years of discussion by a wide number of people.

The Flux Balance Constraints package (nicknamed "fbc") was first released in February, 2013. Import revisions were introduced as part of Version 2,[15] released in September, 2015. The "fbc" package provides support for constraint-based modeling,[16] frequently used to analyze and study biological networks on both a small and large scale.[17] This SBML package makes use of standard components from the SBML Level 3 core specification, including species and reactions, and extends them with additional attributes and structures to allow modelers to define such things as flux bounds and optimization functions.

The Qualitative Models or "qual" package for SBML Level 3 was released in May 2013. This package supports the representation of models where an in-depth knowledge of the biochemical reactions and their kinetics is missing and a qualitative approach must be used. Examples of phenomena that have been modeled in this way include gene regulatory networks [18] and signaling pathways,[19] basing the model structure on the definition of regulatory or influence graphs. The definition and use of some components of this class of models differ from the way that species and reactions are defined and used in core SBML models. For example, qualitative models typically associate discrete levels of activities with entity pools; consequently, the processes involving them cannot be described as reactions per se, but rather as transitions between states. These systems can be viewed as reactive systems whose dynamics are represented by means of state transition graphs (or other Kripke structures [20]) in which the nodes are the reachable states and the edges are the state transitions.

The SBML layout package originated as a set of annotation conventions usable in SBML Level 2. It was introduced at the SBML Forum in St. Louis in 2004.[21] Ralph Gauges wrote the specification [22] and provided an implementation that was widely used. This original definition was reformulated as an SBML Level 3 package, and a specification was formally released in August, 2013.

The SBML Level 3 Layout package provides a specification for how to represent a reaction network in a graphical form. It is thus better tailored to the task than the use of an arbitrary drawing or graph. The SBML Level 3 package only deals with the information necessary to define the position and other aspects of a graph's layout; the additional details necessary to complete the graph—namely, how the visual aspects are meant to be rendered— are the purview of the separate SBML Level 3 package called Rendering (nicknamed "render"). As of November 2015, a draft specification for the "render" package is available, but it has not yet been officially finalized.[23]

Development of SBML Level 3 packages is being undertaken such that specifications are reviewed and implementations attempted during the development process. Once a specification is stable and there are two implementations that support it, the package is considered accepted. The packages detailed above have all reached the acceptance stage. The table below gives a brief summary of packages that are currently in the development phase.

A model definition in SBML Levels 2 and 3 consists of lists of one or more of the following components:

• Function definition: A named mathematical function that may be used throughout the rest of a model.
• Unit definition: A named definition of a new unit of measure, or a redefinition of an existing SBML default unit. Named units can be used in the expression of quantities in a model.
• Compartment Type (only in SBML Level 2): A type of location where reacting entities such as chemical substances may be located.
• Species type (only in SBML Level 2): A type of entity that can participate in reactions. Examples of species types include ions such as Ca²⁺, molecules such as glucose or ATP, binding sites on a protein, and more.
• Compartment: A well-stirred container of a particular type and finite-size where species may be located. A model may contain multiple compartments of the same compartment type. Every species in a model must be located in a compartment.
• Species: A pool of entities of the same species type located in a specific compartment.
• Parameter: A quantity with a symbolic name. In SBML, the term parameter is used in a generic sense to refer to named quantities regardless of whether they are constants or variables in a model.
• Initial Assignment: A mathematical expression used to determine the initial conditions of a model. This type of structure can only be used to define how the value of a variable can be calculated from other values and variables at the start of simulated time.
• Rule: A mathematical expression used in combination with the differential equations constructed based on the set of reactions in a model. It can be used to define how a variable's value can be calculated from other variables or used to define the rate of change of a variable. The set of rules in a model can be used with the reaction rate equations to determine the behavior of the model with respect to time. The set of rules constrains the model for the entire duration of simulated time.
• Constraint: A mathematical expression that defines a constraint on the values of model variables. The constraint applies at all instants of simulated time. The set of constraints in the model should not be used to determine the behavior of the model with respect to time.
• Reaction: A statement describing some transformation, transport or binding process that can change the amount of one or more species. For example, a reaction may describe how certain entities (reactants) are transformed into certain other entities (products). Reactions have associated kinetic rate expressions describing how quickly they take place.
• Event: A statement describing an instantaneous, discontinuous change in a set of variables of any type (species concentration, compartment size or parameter value) when a triggering condition is satisfied.

SBML shorthand is a specification and associated Python tooling to interconvert SBML and the shorthand notation. The format was developed by the UK Newcastle systems biology group sometime before 2006.[24] Its aim was to enable modelers to more rapidly create models without having to either write raw XML or use GUI tools. Two Python tools are provided, mod2sbml.py and sbml2mod.py. The libSBML package for Python is required to assist in the conversion. Currently, SBML-shorthand supports SBML Level 3, version 1.

The following code is an example of SBML-shorthand being used to describe the simple enzyme-substrate mechanism.

@compartments
 cell=1
@species
 cell:Substrate=10
 cell:Enzyme=5
 cell:Complex=0
 cell:Product=0
@parameters
 k1=1
 k1r=2
@reactions
@rr=Binding
 Substrate+Enzyme -> Complex
 k1*Substrate*Enzyme-k1r*Complex
@r=Conversion
 Complex -> Product + Enzyme
 kcat*Complex : kcat=3

Antimony is based on an earlier DSL implemented in the Jarnac modeling application.[25] That, in turn, was based on the SCAMP modeling application[26] which ultimately drew inspiration from the DSL language developed by David Garfinkel for the BIOSIM simulator.[27]

Like SBML-shorthand, Antimony provides a simplified text representation of SBML. It uses a minimum of punctuation characters which renders the text easier to read and understand. It also allows users to add comments. Antimony is implemented using C/C++[28] and Bison as the grammar parser. However, the distribution also includes Python bindings which can be installed using pip to make it easy to use from Python. It is also available via the Tellurium package.[29] More recently, a JavaScript/WASM version[30] has been generated which allows the Antimony language to be used on the web. The website tool makesbml uses the Javascript version.[31] Antimony supports SBML Level 3, version 2. Antimony also supports the following SBML packages: Hierarchical Model Composition, Flux Balance Constraints, and Distributions.

The following example illustrates Antimony being used to describe a simple enzyme-kinetics model:

  binding:    Substrate + Enzyme -> Complex; k1*Substrate*Enzyme - k1r*Complex;
  Conversion: Complex -> Product + Enzyme;   kcat*Complex;

  // Species initializations
  Substrate = 10;
  Enzyme = 5;
  Complex = 0;
  Product = 0;

  // Variable initializations
  k1 = 1;
  k1r = 2;
  kcat = 3;