libSBML Python API  5.11.0
Modules
Here is a list of all modules:
 Core libSBML

SBML Level 3 introduced a modular architecture, in which SBML Level 3 Core is usable in its own right (much like SBML Levels 1 and 2 before it), and optional SBML Level 3 Packages add features to this Core. To support this architecture, libSBML is itself divided into a core libSBML and optional extensions.

Differences between core libSBML and extensions to libSBML

Core libSBML corresponds to the features of SBML Levels 1 to 3 Core; they are always available, and do not require applications to understand more than the SBML core specifications. The classes listed on the rest of page constitute libSBML's implementation of SBML Levels 1–3, without any SBML Level 3 packages.

By contrast, the libSBML extensions are plug-ins that each implement support for a given SBML Level 3 package. Separate pages of this API manual describe the libSBML extensions for those SBML Level 3 packages that are supported at this time. They are grouped under the section titled Level 3 Extensions. The stable releases of libSBML only include extensions for officially-released package specifications; additional, experimental extensions may be available for other Level 3 packages that may not yet have been finalized by the SBML community. You can find copies of these experimental extensions at the download site for libSBML on SourceForge.net.

Summary of core SBML objects implemented in libSBML

Each type of component in a plain SBML model (i.e., one that does not use any SBML packages) is described using a specific type of SBML data object that organizes the relevant information. The top level of an SBML model definition consists of lists of these components, with every list being optional. The next table enumerates the lists and objects defined by core SBML; also shown are the SBML Level+Version combinations for which they are valid.

SBML components and corresponding libSBML objects. The meaning of expressions such as “L2V4” is as follows: “Lx” = SBML Level x, and “Vy” = Version y within a given SBML Level.
Level & Version LibSBML container object LibSBML data object(s)
L2V1+ ListOfFunctionDefinitionsFunctionDefinition
L2V1+ ListOfUnitDefinitionsUnitDefinition
L2V2–L2V4 ListOfCompartmentTypesCompartmentType
L1+ ListOfCompartmentsCompartment
L2V2–L2V4 ListOfSpeciesTypesSpeciesType
L1+ ListOfSpeciesSpecies
L1+ ListOfParametersParameter
L2V2+ ListOfInitialAssignmentsInitialAssignment
L1+ ListOfRulesAssignmentRule, AlgebraicRule, RateRule
L2V2+ ListOfConstraintsConstraint
L1+ ListOfReactionsReaction
L2V1+ ListOfEventsEvent

The list of classes below constitutes the public API of core libSBML. The list includes classes that are not defined in any SBML specification; these utility classes are provided by libSBML to implement various kinds of functionality useful in the context of working with SBML content.

 Flux Balance Constraints

The libSBML “fbc” extension implements support for the SBML Level 3 Flux Balance Constraints package.

Introduction

Constraint based modeling is a widely accepted methodology used to analyze and study biological networks on both a small and whole organism (genome) scale. Typically these models are underdetermined and constraint based methods (e.g. linear, quadratic optimization) are used to optimize specific model properties. This is assumed to occur under a defined set of constraints (e.g. stoichiometric, metabolic) and bounds (e.g. thermodynamic, experimental and environmental) on the values that the solution fluxes can obtain.

Perhaps the most well known (and widely used) analysis method is Flux Balance Analysis (FBA), which is performed on Genome Scale Reconstructions. When using FBA, a target flux is optimized (e.g., to maximize a flux to biomass or minimize ATP production) while other fluxes can be bounded to simulate a selected growth environment or specific metabolic state.

As constraint based models are generally underdetermined, i.e., few or none of the kinetic rate equations and related parameters are known, it is crucial that a model definition includes the ability to define optimization parameters such as objective functions, flux bounds and constraints. This is not well-supported in SBML Level 3 Core. The question of how to best encode constraint-based models in SBML is not new. However, advances in the methods used to construct genome scale constraint-based models and the wider adoption of constraint based modeling in biotechnological/medical applications have led to a rapid increase in both the number of models being constructed and the tools used to analyze them.

Faced with such growth, both in number and diversity, the need for a standardized data format for the definition, exchange and annotation of constraint based models has become critical. As the core model components (e.g., species, reactions, stoichiometry) can already be efficiently described in SBML, the Flux Balance Constraints (FBC) package is designed to extend SBML Level~3 Core by adding the elements necessary to encode current and future constraint-based models.

The specification for this SBML package

This API documentation for libSBML does not provide a complete explanation of the SBML Level 3 Flux Balance Constraints (“fbc”) package. If you are developing software that uses “fbc”, you are strongly urged to read the actual specification for the package. A link to the specification document current is provided below, along with a link to the page of known issues (if any).

Specification for SBML Level 3 Flux Balance Constraints, current at the time of this libSBML release (5.11.0). Note: an Internet connection is required to access these documents.
Specification (in PDF format) Known issues
Flux Balance Constraints package, Version 1 Release 1 Errata page
 Hierarchical Model Composition

The libSBML “comp” extension implements support for the SBML Level 3 Hierarchical Model Composition package.

Introduction

In the context of SBML, hierarchical model composition refers to 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. SBML Level 3 Version 1 Core, by itself, has no direct support for allowing a model to include other models as submodels. The Level 3 Hierarchical Model Composition package adds the missing capabilities. The figure below illustrates some of the scenarios targeted by this package.

Two examples of model configuration supported by the “comp” package: (left) a model composed of a submodel that is itself composed of submodels; (right) a model composed of submodels, one of which is defined in an external file.

The specification for this SBML package

This API documentation for libSBML does not provide a complete explanation of the SBML Level 3 Hierarchical Model Composition (“comp”) package. If you are developing software that uses “comp”, you are strongly urged to read the actual specification for the package. A link to the specification document current is provided below, along with a link to the page of known issues (if any).

Specification for SBML Level 3 Hierarchical Model Composition, current at the time of this libSBML release (5.11.0). Note: an Internet connection is required to access these documents.
Specification (in PDF format) Known issues
Hierarchical Model Composition package, Version 1 Release 3 Errata page
 Layout

The libSBML “layout” extension implements support for the SBML Level 3 Layout package.

Introduction

The layout of a reaction network diagram should be described as graphical representations of species and reactions (and not as arbitrary drawing or graph). This means that existing languages for the description of vector drawings (SVG) or general graphs cannot be used. While it may seem unnecessary to invent a new language when an existing one like SVG could in principle be used to describe the layout of a reaction network, there are good reasons to have a language tailored specifically for the layout of SBML models. Presumably, most programs that will use this SBML extension are primarily programs dealing with biochemical models. Internally, they will have data structures for species and reactions, so it will be natural for them to describe the layout of the reaction network also in terms of species and reactions (and not in terms of, e.g., polygons or splines). Thus, the LayoutClass object defined by this SBML Layout package has a similar structure like the SBML Model object and contains lists of graphical representations of compartments, species, and reactions. Additional layout elements and relationships can be represented by using other custom objects defined by this package.

Example of different renderings of the same layout.

Another important question is the level of detail that the description should provide. For simplicity, only the layout (i.e., the position of the different graphical objects) of the diagram is encoded, not the details of how it should be rendered; the latter is left to the SBML Level 3 Render package. The figure at right illustrates this distinction. All three diagrams could be renderings of the same layout and would be described by identical SBML files. No information about colors, line styles, fonts, etc., is present in the layout description.

The next question is how the relation between the model and the layout should be established. There seems to be a consensus that one model element can be represented by several layout elements. For example, it can be useful to have several representations of one species in the layout to avoid crossing lines. This can be accomplished if every layout element has a field that refers to the id of a model element.

There are also cases where a layout element does not correspondent to exactly one model element. One example is when a layout shows a simplified version of a model in which one reaction in the layout corresponds to several reactions and intermediate species in the model. This is the reason why the field in the layout elements that refers to the model elements is optional: to allow layout objects that do not have a specific counterpart in the SBML model.

The result of all this is a way to describe the graphical layout of a reaction network in biochemical terms. This layout can be closely tied to the model. A graphical editor, for example, would typically create a layout that is closely connected (by a one-to-several relation from the model elements to the layout elements) to the model. A more general layout design program could create a layout that is not so closely tied to the model; for example, it could create a layout that shows a simplified version of the model.

Historical considerations

Historically, the SBML Layout package has been used to encode the layout of SBML Level 2 models; indeed, the original version of the package was developed in the context of SBML Level 2. The approach used with Level 2 is to store the layout information as SBML annotations, i.e., using SBML <annotation> elements. The following XML namespace must be used for layout annotations in Level 2 models:

http://projects.eml.org/bcb/sbml/level2

A minimal example in this case would look like the following:

<?xml version="1.0" encoding="UTF-8"?>
<sbml xmlns="http://www.sbml.org/sbml/level2" level="2" version="1">
  <model>
    <annotation>
      <listOfLayouts xmlns="http://projects.eml.org/bcb/sbml/level2">
        ...
      </listOfLayouts>
    </annotation>
  </model>
</sbml>

Special libSBML behavior for Level 2 Layout

Due to the way that the encoding difference discussed above affects legacy applications, libSBML implements special behavior for the Layout package: it always creates a Layout plugin object for any SBML Level 2 document it reads in, regardless of whether that document actually uses Layout constructs. This is unlike the case for SBML Level 3 documents that use Layout—for them, libSBML will not create a plugin object unless the document actually declares the use of the Layout package (via the usual Level 3 namespace declaration for Level 3 packages).

This has the following consequence. If an application queries for the presence of Layout in an SBML Level 2 document by testing only for the existence of the plugin object, it will always get a positive result; in other words, the presence of a Layout extension object is not an indication of whether a read-in Level 2 document does or does not use SBML Layout. Instead, callers have to query explicitly for the existence of layout information.

The special, always-available Level 2 Layout behavior was motivated by a desire to support legacy applications. In SBML Level 3, the Layout package uses the normal SBML Level 3 scheme of requiring declarations on the SBML document element. This means that upon reading a model, libSBML knows right away whether it contains layout information. In SBML Level 2, there is no top-level declaration because layout is stored as annotations in the body of the model. Detecting the presence of layout information when reading a Level 2 model requires parsing the annotations. For efficiency reasons, libSBML normally does not parse annotations automatically when reading a model. However, applications that predated the introduction of Level 3 Layout and the updated version of libSBML never had to do anything special to enable parsing layout; the facilities were always available for every Level 2 model as long as libSBML was compiled with Layout support. To avoid burdening developers of legacy applications with the need to modify their software, libSBML provides backward compatibility by always preloading the Layout package extension when reading Level 2 models. The same applies to the creation of Level 2 models: with the plugin-oriented libSBML, applications normally would have to take deliberate steps to activate package code, instantiate objects, manage namespaces, and so on. LibSBML again loads the Layout package plugin automatically when creating a Level 2 model, thereby making the APIs available to legacy applications without further work on their part.

Testing for Level 2 Layout

The following are examples of code fragments that could be used to test for the presence of layout data in a Level 2 model.
  • For the case of C++:
    // Assume "m" below is a Model object.
    LayoutModelPlugin* lmp = static_cast<LayoutModelPlugin*>(m->getPlugin("layout"));
    unsigned int numLayouts = lmp->getNumLayouts();
    // If numLayouts is greater than zero, then the model uses Layout.
  • For the case of Python:
    1 # Assume "doc" below is an SBMLDocument object.
    2 m = doc.getModel()
    3 if m != None:
    4  layoutPlugin = m.getPlugin('layout')
    5  if layoutPlugin != None:
    6  numLayouts = layoutPlugin.getNumLayouts()
    7  # If numLayouts is greater than zero, then the model uses Layout.
  • For the case of Java:
    // Assume "doc" below is an SBMLDocument object.
    Model m = doc.getModel();
    LayoutModelPlugin lmp = (LayoutModelPlugin) m.getPlugin("layout");
    if (lmp != null)
    {
    int numLayouts = lmp.getNumLayouts();
    // If numLayouts is greater than zero, then the model uses Layout.
    }
  • For the case of C#:
    // Assume "doc" below is an SBMLDocument object.
    Model m = doc.getModel();
    LayoutModelPlugin lmp = (LayoutModelPlugin) m.getPlugin("layout");
    if (lmp != null)
    {
    int numLayouts = lmp.getNumLayouts();
    // If numLayouts is greater than zero, then the model uses Layout.
    }

The specification for this SBML package

This API documentation for libSBML does not provide a complete explanation of the SBML Level 3 Layout (“layout”) package. If you are developing software that uses “layout”, you are strongly urged to read the actual specification for the package. A link to the specification document current is provided below, along with a link to the page of known issues (if any).

Specification for SBML Level 3 Layout, current at the time of this libSBML release (5.11.0). Note: an Internet connection is required to access these documents.
Specification (in PDF format) Known issues
Layout package, Version 1 Release 1 Errata page
 Qualitative Models

The libSBML “qual” extension implements support for the SBML Level 3 Qualitative Models package.

Introduction

Quantitative methods for modeling biological networks require an in-depth knowledge of the biochemical reactions and their stoichiometric and kinetic parameters. In many practical cases, this knowledge is missing. This has led to the development of several qualitative modeling methods using information such as gene expression data coming from functional genomic experiments.

The qualitative models contemplated in this SBML Level 3 package for Qualitative Models are essentially based on the definition of regulatory or influence graphs. The components of these models differ from the species and reactions used in current SBML models. For example, qualitative models typically associate discrete levels of activities with entity pools; 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 representing, in the form of a graph, which nodes are the reachable states and in which the edges are the state transitions). In this context, logical regulatory networks (Boolean or multi-valued) and standard Petri nets are the two formalisms mostly used in biology that give rise to such behaviors. Published models using these approaches cover, far from exhaustively, gene regulatory networks, signalling pathways and metabolic pathways.

Despite differences from traditional SBML models, it is desirable to bring these classes of models under a common format scheme. The purpose of this Qualitative Models package for SBML Level 3 is to support encoding qualitative models in SBML.

The specification for this SBML package

This API documentation for libSBML does not provide a complete explanation of the SBML Level 3 Qualitative Models (“qual”) package. If you are developing software that uses “qual”, you are strongly urged to read the actual specification for the package. A link to the specification document current is provided below, along with a link to the page of known issues (if any).

Specification for SBML Level 3 Qualitative Models, current at the time of this libSBML release (5.11.0). Note: an Internet connection is required to access these documents.
Specification (in PDF format) Known issues
Qualitative Models package, Version 1 Release 1 Errata page