Tutorial

This tutorial will teach you the basics of using libsbmljs in an empty project. Make sure you have Node.js 10.15.0 or later before starting. We’re going to use Node.js for this tutorial because setting up libsbmljs in the browser usually involves Webpack, which makes things a little more complicated. We have a separate example showing how to use libsbmljs with Webpack.

• First, create and change to a new directory and run the following. The answers you provide to npm's questions don't matter for this tutorial. You can leave all of the fields blank

  npm init
  

• You will need to install one of libsbmljs's npm packages. We will use the `libsbmljs_stable` package for this tutorial.

  npm install --save libsbmljs_stable@beta
  

• Next you will need to install Babel:

  npm install --save-dev @babel/core @babel/cli @babel/node @babel/preset-env
  

• Create the file “index.js” in the current directory. This file will hold all the JavaScript code for this tutorial. Open the “index.js” file.

• Unlike most JavaScript libraries, libsbmljs is loaded asynchronously. This means that it cannot be used immediately after importing it because the browser or Node.js may still be downloading and compiling it. The libsbmljs module can be called using a "then()" method similar to a Promise. Any libsbmljs functions you want to use should go inside the "then()" callback. Add the following code to your `index.js` file:

  import libsbml from 'libsbmljs_stable'
  // the module isn't usable yet - wait for it to load
  libsbml().then((libsbml) => {
    // now it is safe to use the module
    const doc = new libsbml.SBMLDocument(3,2)
  })
  

• To populate the SBML content to the document you just created in the previous step, let's add one SBML Comaprtment, one Species and one Reaction. You can paste this code into your `then()` callback or copy the full source code at the end of this tutorial into "index.js".

...
  // create a model and compartment
  const model = doc.createModel()
  const compartment = model.createCompartment()
  compartment.setId('C1')
  compartment.setSize(1)
  compartment.setConstant(true)

  // create a species
  const species = model.createSpecies()
  species.setId('S1')
  species.setConstant(false)
  species.setHasOnlySubstanceUnits(false)
  species.setBoundaryCondition(false)

  // create a reaction
  const reaction = model.createReaction()
  reaction.setId('J1')
  reaction.setReversible(false)

  const reactant = reaction.createReactant() // returns a SpeciesReference
  reactant.setSpecies('S1')
  reactant.setConstant(false)

  // create a parser for infix formulae
  // this is a libsbmljs helper class
  // it doesn't exist in the libsbml C++ library
  const parser = new libsbml.SBMLFormulaParser()
  reaction.createKineticLaw().setMath(parser.parseL3Formula('10*S1'))
...

• Finally, we will write out the SBML document we create to XML:

  ...
    // print out the serialized XML for the SBML model we created
    const writer = new libsbml.SBMLWriter()
    console.log(writer.writeSBMLToString(doc))
  ...
  

• You can run this example from the directory containing "index.js" as follows:

  npx babel-node --presets @babel/env index.js
  

You should see the following output printed to the terminal:

<?xml version="1.0" encoding="UTF-8"?>
<sbml xmlns="http://www.sbml.org/sbml/level3/version2/core" level="3" version="2">
  <model>
    <listOfCompartments>
      <compartment id="C1" size="1" constant="true"/>
    </listOfCompartments>
    <listOfSpecies>
      <species id="S1" hasOnlySubstanceUnits="false" boundaryCondition="false" constant="false"/>
    </listOfSpecies>
    <listOfReactions>
      <reaction id="J1" reversible="false">
        <listOfReactants>
          <speciesReference species="S1"/>
        </listOfReactants>
        <kineticLaw>
          <math xmlns="http://www.w3.org/1998/Math/MathML">
            <apply>
              <times/>
              <cn type="integer"> 10 </cn>
              <ci> S1 </ci>
            </apply>
          </math>
        </kineticLaw>
      </reaction>
    </listOfReactions>
  </model>
</sbml>

• Here is the full source code of the “index.js” file we created in this tutorial:

import libsbml from 'libsbmljs_stable'
// the module isn't usable yet - wait for it to load
libsbml().then((libsbml) => {
  // now it is safe to use the module
  const doc = new libsbml.SBMLDocument(3,2)

  // create a model and compartment
  const model = doc.createModel()
  const compartment = model.createCompartment()
  compartment.setId('C1')
  compartment.setSize(1)
  compartment.setConstant(true)

  // create a species
  const species = model.createSpecies()
  species.setId('S1')
  species.setConstant(false)
  species.setHasOnlySubstanceUnits(false)
  species.setBoundaryCondition(false)

  // create a reaction
  const reaction = model.createReaction()
  reaction.setId('J1')
  reaction.setReversible(false)

  const reactant = reaction.createReactant() // returns a SpeciesReference
  reactant.setSpecies('S1')
  reactant.setConstant(false)

  // create a parser for infix formulae
  // this is a helper class of libsbmljs
  // it doesn't exist in the libsbml C++ library
  const parser = new libsbml.SBMLFormulaParser()
  reaction.createKineticLaw().setMath(parser.parseL3Formula('10*S1'))

  // print out the serialized XML for the SBML model we created
  const writer = new libsbml.SBMLWriter()
  console.log(writer.writeSBMLToString(doc))
})