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.

• 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:

  # Assume "doc" below is an SBMLDocument object.
  m = doc.getModel()
  if m != None:
      layoutPlugin = m.getPlugin('layout')
      if layoutPlugin != None:
          numLayouts = layoutPlugin.getNumLayouts()
          # 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.
  }

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).

Specification for SBML Level 3 Layout, current at the time of this libSBML release (5.18.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

More...

Classes
class	BoundingBox
	layout A bounding box for an item in a diagram. More...
class	CompartmentGlyph
	layout A glyph for an SBML compartment. More...
class	CubicBezier
	layout A Cubic Bézier smooth curve. More...
class	Curve
	layout A curve connecting elements in a diagram. More...
class	Dimensions
	layout Spatial dimensions of a 2D or 3D shape. More...
class	GeneralGlyph
	layout A glyph for miscellaneous items. More...
class	GraphicalObject
	layout Base class of objects that store layouts. More...
class	Layout
	layout The layout of a diagram of an SBML model. More...
class	LayoutExtension
	layout Base extension class for the package. More...
class	LayoutModelPlugin
	layout Extension of Model. More...
class	LayoutPkgNamespaces
	layout SBMLNamespaces extension for the package. More...
class	LayoutSBMLDocumentPlugin
	layout Extension of SBMLDocument. More...
class	LayoutSpeciesReferencePlugin
	layout Extension of SpeciesReference. More...
class	LayoutValidator
	layout Entry point for package validation. More...
class	LineSegment
	layout Representation of a line. More...
class	ListOfCompartmentGlyphs
	layout A list of CompartmentGlyph objects. More...
class	ListOfGraphicalObjects
	layout A list of GraphicalObject objects. More...
class	ListOfLayouts
	layout A list of Layout objects. More...
class	ListOfLineSegments
	layout A list of LineSegment objects. More...
class	ListOfReactionGlyphs
	layout A list of ReactionGlyph objects. More...
class	ListOfReferenceGlyphs
	layout A list of ReferenceGlyph objects. More...
class	ListOfSpeciesGlyphs
	layout A list of SpeciesGlyph objects. More...
class	ListOfSpeciesReferenceGlyphs
	layout A list of SpeciesReferenceGlyph objects. More...
class	ListOfTextGlyphs
	layout A list of TextGlyph objects. More...
class	Point
	layout Representation of a point. More...
class	ReactionGlyph
	layout A glyph for an SBML reaction. More...
class	ReferenceGlyph
	layout Connection between an object and a glyph. More...
class	SpeciesGlyph
	layout A glyph for an SBML species. More...
class	SpeciesReferenceGlyph
	layout A glyph for an SBML species reference. More...
class	TextGlyph
	layout A glyph for a text label. More...

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.

• 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:

  # Assume "doc" below is an SBMLDocument object.
  m = doc.getModel()
  if m != None:
      layoutPlugin = m.getPlugin('layout')
      if layoutPlugin != None:
          numLayouts = layoutPlugin.getNumLayouts()
          # 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.
  }

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).

Specification for SBML Level 3 Layout, current at the time of this libSBML release (5.18.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