libSBML

<h2 id="description">Description</h2>
<p>The Systems Biology Markup Language (<a href="/facts/SBML/f5X3n8Vv">SBML</a>) is an XML-based format for encoding <a href="/facts/Computational_model/dq1CR6us">computational models</a> of a sort common in <a href="/facts/Systems_biology/HTH1z1RA">systems biology</a>.  Although SBML is based upon <a href="/facts/XML/clNgUfWk">XML</a>, and thus software developers <i>could</i> support SBML using off-the-shelf XML parser libraries, libSBML offers numerous advantages that make it easier for developers to implement support for SBML in their software.  The premise behind the development of libSBML is that it is more convenient and efficient for developers to start with a higher-level API tailored specifically to SBML and its distinctive features than it is to start with a plain XML parser library.
</p>
<h3>Significant features of libSBML</h3>
<p>The following is a partial list of libSBML's features:
</p>
<ul><li><i>Supports all Levels and Versions of SBML</i> with common API classes and methods, thus smoothing the differences between different flavors of SBML from the perspective of the application software.</li>
<li><i>Provides facilities for manipulating mathematical formulas</i> in both text-string format and <a href="/facts/MathML/uKRIc3Fy">MathML</a> 2.0 format, as well as the ability to interconvert mathematical expressions between these forms.  Internally, libSBML uses familiar <a href="/facts/Abstract_Syntax_Tree/73AUK1jI">Abstract Syntax Trees</a> (ASTs) to represent formulas, and provides AST-oriented methods for calling applications.</li>
<li><i>Performs validation</i> of XML and SBML at the time of parsing files and data streams.  This helps verify the correctness of models in a way that goes beyond simple syntactic validation.</li>
<li><i>Offers support for dimensional analysis and unit checking</i>.  LibSBML implements a thorough system for dimensional analysis and checking units of quantities in a model.</li>
<li><i>Provides facilities for the creation and manipulation of SBML annotations and notes</i>.  These have a specific format dictated by the SBML specifications.  The formats and standards supported by libSBML include <a href="/facts/MIRIAM/UDEywbzJ">MIRIAM</a> (Minimal Information Requested in the Annotation of a Model) and SBO (the <a href="/facts/Systems_Biology_Ontology/3xdCoWJx">Systems Biology Ontology</a>).</li>
<li><i>Supports transparently reading and writing compressed files</i> in the <a href="/facts/Zip_(file_format)/qDrrYIB9">ZIP</a>, <a href="/facts/GZIP/H23uqvyx">GZIP</a> and <a href="/facts/BZIP/snj608l0">BZIP</a> formats.</li>
<li><i>Provides interfaces for the <a href="/facts/C_(programming_language)/Ky2No763">C</a>, <a href="/facts/C%2B%2B/Et0F2qn9">C++</a>, <a href="/facts/C_Sharp_(programming_language)/UC2gxeyb">C#</a>, <a href="/facts/Java_(programming_language)/9ScgFyAL">Java</a>, <a href="/facts/Python_(programming_language)/YbuGqofa">Python</a>, <a href="/facts/Perl/fx31kjlT">Perl</a>, <a href="/facts/MATLAB/qPjLISCk">MATLAB</a>, <a href="/facts/Octave_(programming_language)/vVVq5evM">Octave</a>, and <a href="/facts/Ruby_(programming_language)/BeYSaPSR">Ruby</a></i> programming languages.  The C and C++ interfaces are implemented natively; the C#, Java, Perl, Python, and Ruby interfaces are implemented using <a href="/facts/SWIG/A8Q6IxLt">SWIG</a>, the Simplified Wrapper Interface Generator; and the MATLAB and Octave interfaces are implemented through custom hand-written code.</li>
<li><i>Provides many convenience methods</i>, such as for obtaining a count of the number of boundary condition species, determining the modifier species of a reaction (assuming the reaction provides kinetics), constructing the stoichiometric matrix for all reactions in a model, and more.</li></ul>
<h3>Manipulation of mathematical formulas</h3>
<p>Some further explanations may be warranted concerning libSBML's support for working with mathematical formulas.  In SBML Level 1, mathematical formulas are represented as text strings using a C-like syntax.  This representation was chosen because of its simplicity, widespread familiarity and use in applications such as GEPASI<a class="footnote-ref" id="fnref:4" href="#fn:4"><sup>4</sup></a> and Jarnac,<a class="footnote-ref" id="fnref:5" href="#fn:5"><sup>5</sup></a> whose authors contributed to the initial design of SBML.  In SBML Levels 2 and 3, there was a need to expand the mathematical vocabulary of Level 1 to include additional functions (both built-in and user-defined), mathematical constants, logical operators, relational operators and a special symbol to represent time.  Rather than growing the simple C-like syntax into something more complicated and esoteric in order to support these features, and consequently having to manage two standards in two different formats (XML and text string formulas), SBML Levels 2 and 3 leverage an existing standard for expressing mathematical formulas, namely the content portion of <a href="/facts/MathML/uKRIc3Fy">MathML</a>.
</p><p>As mentioned above, LibSBML provides an abstraction for working with mathematical expressions in both text-string and MathML form: Abstract Syntax Trees (ASTs).  <a href="/facts/Abstract_Syntax_Tree/73AUK1jI">Abstract Syntax Trees</a> are well known in the computer science community; they are simple recursive data structures useful for representing the syntactic structure of sentences in certain kinds of languages (mathematical or otherwise).  Much as libSBML allows programmers to manipulate SBML at the level of domain-specific objects, regardless of SBML Level or version, it also allows programmers to work with mathematical formula at the level of ASTs regardless of whether the original format was C-like infix or MathML.  LibSBML goes one step further by allowing programmers to work exclusively with infix formula strings and instantly convert them to the appropriate MathML whenever needed.
</p>
<h3>Dependencies</h3>
<p>LibSBML requires a separate library to do low-level read/write operations on XML.  It can use any one of three XML parser libraries: <a href="/facts/Apache_Xerces/BSTPTDee">Xerces</a>, <a href="/facts/Expat_(XML)/hLTatDp3">expat</a> or <a href="/facts/Libxml2/jxWA6GX1">libxml2</a>.  Users can specify which library they wish to use at libSBML compilation time.   LibSBML hides the differences between these parser libraries behind an abstraction layer; it seamlessly uses whichever library against which a given instance of libSBML has been compiled. (However, released binary distributions of libSBML all make use of the <a href="/facts/Libxml2/jxWA6GX1">libxml2</a> library.)
</p>
<h2 id="usage">Usage</h2>
<p>LibSBML uses software objects (i.e., instances of <a href="/facts/Class_(computer_programming)/zvzkSAtE">classes</a>) that correspond to SBML components, with <a href="/facts/Member_variable/BAtCyPVd">member variables</a> representing the attributes of the corresponding SBML objects.  The libSBML API is constructed to provide an intuitive way of relating SBML and the code needed to create or manipulate it with a class hierarchy that mimics the SBML structure.  More information about the libSBML objects is available in the <a href="http://sbml.org/Software/libSBML">libSBML API documentation</a>.
</p>
<h3>Reading and writing SBML</h3>
<p>LibSBML enables reading from and writing to either files or strings. Once an SBML document is read, libSBML stores the SBML content in an SBMLDocument object.  This object can be written out again later. The following is an example written in <a href="/facts/Python_(programming_language)/YbuGqofa">Python</a>:
</p>
>>> import libsbml
>>>
>>> # read a document 
>>> doc = libsbml.readSBMLFromFile(filename)
>>> doc = libsbml.readSBMLFromString(string)
>>>
>>> # helper function that takes either a string 
>>> # or filename as argument
>>> doc = libsbml.readSBML(filename)
>>> doc = libsbml.readSBML(string)
>>>
>>> # write a document
>>> libsbml.writeSBMLToFile(doc, filename)
True
>>>
>>> libsbml.writeSBMLToString(doc)
'<?xml version="1.0" encoding="UTF-8"?>\n
<sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" 
      level="3" version="1">\n  
  <model/>\n
</sbml>\n'

<h3>Creating and manipulating SBML</h3>
<p>The libSBML API allows easy creation of objects and subobjects representing SBML elements and the subelements contained within them.  The following is an example written in <a href="/facts/C%2B%2B/Et0F2qn9">C++</a>:
</p>
void createSBML()
{
  // create an SBML Level 3 Version 1 document
  SBMLDocument* doc = new SBMLDocument(3, 1);

// create the model as a sub element of the document
  Model * model = doc->createModel();

// create a compartment as a sub element of the model
  Compartment * compartment1 = model->createCompartment();

// create an independent compartment and then add it to the model
  Compartment * compartment2 = new Compartment(3, 1);
  model->addCompartment(compartment2);
}

<h3>Accessing attributes</h3>
<p>Each component in SBML has a number of attributes associated with it. These are stored as member variables of a given class, and libSBML provides functions to retrieve and query these values. The syntax of these functions is consistent throughout libSBML. The following is an example written in <a href="/facts/Python_(programming_language)/YbuGqofa">Python</a>:
</p>
>>> import libsbml
>>>
>>> # create an SBML Level 3 Version 1 document
>>> sbmlns = libsbml.SBMLNamespaces(3, 1)
>>> doc = libsbml.SBMLDocument(sbmlns)
>>>
>>> #create the model as a sub element of the document
>>> model = doc.createModel()
>>>
>>> #create a compartment as a sub element of the model
>>> compartment = model.createCompartment()
>>>
>>> # set the attributes on the compartment
>>> # note a return value of 0 indicates success
>>> compartment.setId("cell")
0
>>> compartment.setSize(2.3)
0
>>> compartment.setSpatialDimensions(3)
0
>>> compartment.setUnits("litre")
0
>>> compartment.setConstant(True)
0
>>>
>>> # get the attribute values
>>> compartment.getId()
'cell'
>>> compartment.getSpatialDimensions()
3
>>>
>>> # examine the status of the attribute
>>> compartment.isSetSize()
True
>>> compartment.getSize()
2.3
>>>
>>> #unset an attribute value
>>> compartment.unsetSize()
0
>>> compartment.isSetSize()
False
>>> compartment.getSize()
nan

<h2 id="see-also">See also</h2>
<ul><li><a href="/facts/JSBML/1c14gIQr">JSBML</a></li>
<li><a href="/facts/Libxml2/jxWA6GX1">libxml2</a></li>
<li><a href="/facts/Apache_Xerces/BSTPTDee">Xerces</a></li>
<li><a href="/facts/Expat_(XML)/hLTatDp3">Expat</a></li>
<li><a href="/facts/XML_validation/MqgbRXzc">XML validation</a></li>
<li><a href="/facts/XML/clNgUfWk">XML</a></li>
<li><a href="/facts/BioModels_Database/9QrLDm62">BioModels Database</a></li>
<li><a href="/facts/BioPAX/9yNQC8RL">BioPAX</a></li>
<li><a href="/facts/CellML/rql491Tk">CellML</a></li>
<li><a href="/facts/MIASE/60RC5jPl">MIASE</a></li>
<li><a href="/facts/MIRIAM/UDEywbzJ">MIRIAM</a></li>
<li><a href="/facts/Systems_Biology_Ontology/3xdCoWJx">Systems Biology Ontology</a> (SBO)</li>
<li><a href="/facts/MathML/uKRIc3Fy">MathML</a></li></ul>

<h2 id="external-links">External links</h2>
<ul><li><a href="http://sbml.org/Software/libSBML">libSBML Home Page</a></li></ul>

<h2 id="references">References</h2>

<ol>
<li id="fn:1"><p>Hucka, M.; Finney, A.; Sauro, H. M.; Bolouri, H.; Doyle, J. C.; Kitano, H.; Arkin, A. P.; Bornstein, A. P.; Bray, B. J.; Cornish-Bowden, D.; Cuellar, A.; Dronov, A. A.; Gilles, S.; Ginkel, E. D.; Gor, M.; Goryanin, V.; Hedley, I. I.; Hodgman, W. J.; Hofmeyr, T. C.; Hunter, J. -H.; Juty, P. J.; Kasberger, N. S.; Kremling, J. L.; Kummer, A.; Le Novère, U.; Loew, N.; Lucio, L. M.; Mendes, P.; Minch, P.; Mjolsness, E. (2003). "The systems biology markup language (SBML): A medium for representation and exchange of biochemical network models". Bioinformatics. 19 (4): 524–531. doi:10.1093/bioinformatics/btg015. PMID 12611808. <a href="/wiki/Hiroaki_Kitano" target="_blank">/wiki/Hiroaki_Kitano</a> <a href="#fnref:1" class="footnote-back-ref">↩</a></p></li>
<li id="fn:2"><p>Finney, A.; Hucka, M. (2003). "Systems biology markup language: Level 2 and beyond". Biochemical Society Transactions. 31 (Pt 6): 1472–1473. CiteSeerX 10.1.1.466.8001. doi:10.1042/bst0311472. PMID 14641091. <a href="/wiki/CiteSeerX_(identifier)" target="_blank">/wiki/CiteSeerX_(identifier)</a> <a href="#fnref:2" class="footnote-back-ref">↩</a></p></li>
<li id="fn:3"><p>Hucka, M.; Finney, A.; Bornstein, B. J.; Keating, S. M.; Shapiro, B. E.; Matthews, J.; Kovitz, B. L.; Schilstra, M. J.; Funahashi, A.; Doyle, S. M.; Kitano, M. J. (2004). "Evolving a lingua franca and associated software infrastructure for computational systems biology: The Systems Biology Markup Language (SBML) project" (PDF). Systems Biology. 1 (1): 41–53. doi:10.1049/sb:20045008 (inactive 7 December 2024). PMID 17052114.{{cite journal}}:  CS1 maint: DOI inactive as of December 2024 (link) <a href="https://authors.library.caltech.edu/2099/1/HUCieesb04.pdf" target="_blank">https://authors.library.caltech.edu/2099/1/HUCieesb04.pdf</a> <a href="#fnref:3" class="footnote-back-ref">↩</a></p></li>
<li id="fn:4"><p>Mendes, P. (1993). "GEPASI: A software package for modelling the dynamics, steady states and control of biochemical and other systems". Computer Applications in the Biosciences. 9 (5): 563–571. doi:10.1093/bioinformatics/9.5.563. PMID 8293329. <a href="/wiki/Pedro_Pedrosa_Mendes" target="_blank">/wiki/Pedro_Pedrosa_Mendes</a> <a href="#fnref:4" class="footnote-back-ref">↩</a></p></li>
<li id="fn:5"><p>Jarnac, Sauro H. "A system for interactive metabolic analysis". In: Hofmeyr, J-HS, et al., eds. Animating the Cellular Map: Proceedings of the 9th International Meeting on BioThermoKinetics. Stellenbosch, South Africa: Stellenbosch University Press; 2000. pp. 221–228. <a href="#fnref:5" class="footnote-back-ref">↩</a></p></li>
</ol>

libSBML open-in-new

libSBML