libSBML C++ API  5.20.2
Classes
Layout

The libSBML “layout” extension implements support for the SBML Level 3 Layout package. It can be used in SBML Level 3 Version 1 and Version 2 documents.

Introduction

The layout of a reaction network diagram should be described as a graphical representation of species and reactions, and not as an 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.

Authors

The primary authors of the SBML Level 3 Layout specification are Ralph Gauges, Ursula Rost, Sven Sahle, Katja Wengler and Frank T. Bergmann.

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). we apologise that our known issues pages are under reconstruction.

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

Classes

class  BoundingBox
 
class  CompartmentGlyph
 
class  CubicBezier
 
class  Curve
 
class  Dimensions
 
class  GeneralGlyph
 
class  GraphicalObject
 
class  Layout
 
class  LayoutExtension
 
class  LayoutModelPlugin
 
class  LayoutPkgNamespaces
 
class  LayoutSBMLDocumentPlugin
 
class  LayoutSpeciesReferencePlugin
 
class  LayoutValidator
 
class  LineSegment
 
class  ListOfCompartmentGlyphs
 
class  ListOfGraphicalObjects
 
class  ListOfLayouts
 
class  ListOfLineSegments
 
class  ListOfReactionGlyphs
 
class  ListOfReferenceGlyphs
 
class  ListOfSpeciesGlyphs
 
class  ListOfSpeciesReferenceGlyphs
 
class  ListOfTextGlyphs
 
class  Point
 
class  ReactionGlyph
 
class  ReferenceGlyph
 
class  SpeciesGlyph
 
class  SpeciesReferenceGlyph
 
class  TextGlyph
 

Detailed Description

The libSBML “layout” extension implements support for the SBML Level 3 Layout package. It can be used in SBML Level 3 Version 1 and Version 2 documents.

Introduction

The layout of a reaction network diagram should be described as a graphical representation of species and reactions, and not as an 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.

Authors

The primary authors of the SBML Level 3 Layout specification are Ralph Gauges, Ursula Rost, Sven Sahle, Katja Wengler and Frank T. Bergmann.

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). we apologise that our known issues pages are under reconstruction.

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