LibSBML features
LibSBML is an application programming interface (API) library for
reading, writing and manipulating files and data streams containing content
in SBML (Systems Biology Markup Language) format. Developers can embed the
library in their applications, saving themselves the work of implementing
their own parsing, manipulation and validation software. At the API level,
the library provides the same interface to data structures independently of
whether the model originated in SBML Level 1, 2 or 3. LibSBML also
fully supports all accepted SBML Level 3 packages.
Why not simply use a generic XML parsing library? After all, SBML is
usually expressed in XML, and there exist plenty of XML parsers, so why not
simply tell people to use one of them, rather than develop a specialized
library? The answer is: while it is true that developers can use
general-purpose XML libraries, there are many reasons why using a system such
as libSBML is a vastly better choice. Here are just some of the features
offered by libSBML:
- Full SBML Support. All constructs in SBML Level 1, 2
and 3 Core are supported, as are the constructs defined in the
officially ratified SBML Level 3 packages.
- Unified SBML Level 3, Level 2 and Level 1 object
models. All objects have
getSBMLDocument(),
getModel(), getLevel(), and
getVersion() methods, among other things.
- Full XML and SBML Validation. LibSBML offers extensive
validation against the SBML specifications; this helps verify the
correctness of SBML models in a way that goes beyond simple schema-based
validation. All XML warnings and errors are logged with line and column
number information and may be retrieved and manipulated programmatically.
LibSBML also does not force applications to read and write valid
models: SBML validation is something that must be invoked explicitly, which
allows callers to do such things as store incomplete models during
editing.
- Dimensional analysis and unit checking. LibSBML implements a
thorough system for dimensional analysis and checking units of quantities
in a model. The validation rules for units that are specified in SBML
Level 2 Version 2 and Version 3, as well as the equivalent
warnings defined in SBML Level 2 Version 4 and Level 3
Version 1, are fully implemented, including checking units in
mathematical formulas.
- Support for both MathML and text-string mathematical
formulas. LibSBML offers facilities for manipulating mathematical
expressions in both MathML form and a text-string format. It uses an
Abstract Syntax Trees (AST) representation of mathematical formulas,
supporting both in-memory operations and the ability to parse and write
either text-string or MathML representations. It also supports
extensibility by plug-ins for SBML Level 3 packages.
- Facilities for converting and transforming SBML. LibSBML
provides various facilities that include such important functionality as
converting between SBML Levels and Versions (when possible). LibSBML can
also transform within-SBML constructs, such as to expand all user-defined
functions in-line, replace reactions with explicit differential equations,
and many other transformations. This makes many general SBML models
accessible to software systems that do not directly support certain SBML
constructs, or can only read certain Level/Version combinations of SBML.
- Other domain-specific facilities. LibSBML provides many other
useful facilities relevant to developing models in SBML. Examples of such
operations include obtaining a count of the number of boundary condition
species, determining the modifier species of a reaction (assuming the
reaction provides kinetics), and constructing the stoichiometric matrix for
all reactions in a model.
- Access to SBML annotations and notes as XML objects. LibSBML
offers an API to facilitate the creation and addition of MIRIAM-compatible RDF annotations
inside SBML
<annotation> elements. Both these kinds of
annotations and the related SBML <notes> element content
can be read and manipulated as XML structures or text strings.
- Support for SBO. LibSBML provides API methods for adding and
working with Systems Biology Ontology
(SBO) terms in SBML models. Annotating a model with SBO terms adds
semantic information that can permit better software interpretation of the
model's mathematical structure and (potentially) the ability to translate a
model between different mathematical frameworks.
- Support for compressed SBML files. If an SBML file name ends
in
.gz, .zip or .bz2, libSBML will
automatically uncompress the file upon reading it. Similarly, if the file
to be written has one of those extensions, libSBML will write it out in
compressed form.
- XML parser abstraction. LibSBML relies on third-party XML
parser libraries, but thanks to its implementation of an abstraction layer,
libSBML can use any of three different popular XML parser libraries: Expat, Apache Xerces-C++, and libxml2. LibSBML provides
identical functionality and checking of XML syntax is available no matter
which one is used. SBML Documents are parsed and manipulated in the
Unicode codepage for efficiency; however, strings are transcoded to the
local code page for SBML structures.
- Interfaces for C, C++, C#, Java, JavaScript, MATLAB, Octave, Perl, PHP,
Python, R and Ruby (as mentioned above). The C and C++ interfaces are
implemented natively; the C#, Java, JavaScript, Perl, PHP, Python, R and Ruby
interfaces are implemented using SWIG,
the Simplified Wrapper Interface Generator; and the MATLAB and Octave
interfaces are implemented through custom hand-written code.
- Small memory footprint and fast runtime. The parser is
event-based (SAX2) and loads SBML data into C++ structures that mirror the
SBML specification.
- Portability. LibSBML is written in ISO standard C++ and C and is
highly portable. It currently runs on the Linux, Mac OS X, and
Microsoft Windows operating systems, but it has been known to run under
FreeBSD, Solaris and iOS with little or no modifications.
- Support for both CMake and GNU
autoconf and
make. For core libSBML, both build systems are
supported, allowing programmers greater flexibility in configuring and
embedding libSBML in their software.
- Extensive testing. LibSBML has several thousand unit tests
containing a total of over tens of thousands of individual assertions. In
addition to these tests, libSBML contains over 4400 hand-written SBML XML
files containing different variations of both correctly and incorrectly
written SBML and XML syntax.
- Extensive documentation. Complete API documentation is
available in the "docs" subdirectory, with individual API manuals for the
different programming languages support by libSBML.
Users of libSBML often find its features convenient to use for more
than simply supporting SBML. For example, many software packages provide
users with the ability to express mathematical expressions for such things as
reaction rate expressions, and these packages' interfaces often let users
type in the formulas directly as text strings. LibSBML's API for
mathematical formulas, with its support for text-string based input, thus
saves application programmers the work of developing their own formula
manipulation and translation facilities.
LibSBML is distributed in both source-code form and as precompiled
dynamic libraries for the Microsoft Windows, Linux and Apple
Mac OS X operating systems; they are available from the SBML project site
on SourceForge.net.
