Release Notes of SBMLsqueezer version 1.3

Download of SBMLsquezeezer

You can always download the latest version of SBMLsqueezer at http://www.ra.cs.uni-tuebingen.de/software/SBMLsqueezer/downloads.

New Features

A New and Purely Java-Based SBML Data Structure

SBMLsqueezer's data structure was completely changed: Earlier versions were based on String concatenation to create kinetic formulas with all participating species and parameters. Now SBMLsqueezer is based on an abstract syntax tree representation of the formula and also creates Parameter objects rather than simply their identifier.

This new data structure is actually an almost complete Java implementation of SBML and has therefore become a separate project, JSBML, available at http://sourceforge.net/projects/jsbml. On the SBML homepage, you can find a separate mailing list about this project: http://sbml.org/Forums

With JSBML at hand, SBMLsqueezer does no longer manipulate CellDesigner's plug-in Objects directly. If you start SBMLsqueezer from CellDesigner's plug-in menu or its reaction context menu, SBMLsqueezer will copy all required parts of the model into JSBML objects. Only this copy of the model is manipulated. By clicking on OK or Apply, all changes will be synchronized with CellDesigner's original data structures.

Stand-Alone Mode

SBMLsqueezer now also runs in a stand-alone mode. With the help of libSBML, valid SBML files can be read and copied into the JSBML data objects. JSBML now mirrors the complete definition of SBML up to Level 2 Version 4. As in the CellDesigner plug-in mode, SBMLsqueezer only manipulates JSBML objects. By clicking on save, changes are written into the SBML file.

Command-line mode: All features of SBMLsqueezer are now also available from the command line. This allows users to write shell or batch scripts that access SBMLsqueezer's functions.

The Application Programming Interface (API) of SBMLsqueezer has been simplified. There is now just one function, squeeze in the main class SBMLsqueezer that can be called to read in a model from a valid SBML file and to write the result, i.e., an SBML model including new KineticLaws, new Parameters, new or adapted UnitDefinitions, into the given out file. Before creating kinetic formulas for the model, the user probably wants to adjust SBMLsqueezer's configuration. To this end, the methods set(CfgKey, <boolean|double|int|String>) in class SBMLsqueezer allow the programmer to set any configuration key and value pair, similar to the command-line mode. Here we give a minimal example of how to use this new API:

public static void main(String[] args) {
  // Initialize SBMLsqueezer with appropriate SBML readers/writers
  SBMLsqueezer squeezer = new SBMLsqueezer(new LibSBMLReader(), new LibSBMLWriter());
  // Configure SBMLsqueezer
  squeezer.set(CfgKeys.OPT_ALL_REACTIONS_ARE_ENZYME_CATALYZED, true);
  squeezer.set(CfgKeys.OPT_DEFAULT_COMPARTMENT_INITIAL_SIZE, 1.0);
  squeezer.set(CfgKeys.POSSIBLE_ENZYME_RNA, true);
  squeezer.set(CfgKeys.KINETICS_UNI_UNI_TYPE, MichaelisMenten.class.getName());
  squeezer.set(CfgKeys.KINETICS_OTHER_ENZYME_REACTIONS, ConvenienceKinetics.class.getName());
  try {
    // Create kinetic equations, parameters, units etc. and save the result
    // args contains infile and outfile path
    squeezer.squeeze(args[0], args[1]);
  } catch (Throwable e) {
    e.printStackTrace();
  }
}

Since SBMLsqueezer still requires an installation of libSBML on the user's system, which can sometimes become problematic, a more convenient way of using SBMLsqueezer has now been made available: the SBMLsqueezer web application does not require any local installation and is freely available at http://webservices.cs.uni-tuebingen.de. In this framework, workflows can be created in which SBMLsqueezer can directly be linked to the full version of SBML2LaTeX. The full version of SBML2LaTeX contains many additional features that are not included in SBMLsqueezer's version of SBML2LaTeX. Hence, it is highly recommended to make use of the online version of SBML2LaTeX.

Configuration

SBMLsqueezer now memorizes every setting and changed parameters from the Graphical User Interface (GUI) whether in CellDesigner plug-in or stand-alone mode. In the stand-alone case, SBMLsqueezer even memorizes given command-line arguments. These settings are read from a configuration file at the next start. This is especially convenient for open and save directories. At any time, the user can change all settings to the defaults by clicking the designated button in the preferences dialog.

Improved Systems Biology Ontology Support

SBMLsqueezer is now fully based on the Systems Biology Ontology (SBO). The JSBML copy of CellDesigner's plug-in data structures maps all CellDesigner-specific annotations to corresponding SBO terms. Afterwards these are mapped back. SBO term “enzymatic catalyst” (SBO:0000460) was created because it is required by SBMLsqueezer to distinguish enzymes and other catalysts, such as certain anorganic ions. SBMLsqueezer's stand-alone version interpretes SBO terms that can be found in the model and changes the annotation of ModifierSpeciesReferences from “catalyst” (SBO:0000013) to “enzymatic catalyst” if the SBO term of the corresponding Species is one of those belonging to the family of materials considered as enzymes (SBMLsqueezer still offers check boxes to indicate certain kinds of species as enzymes).

Earlier versions of SBMLsqueezer indicated the SBO term identifiers of newly created kinetic equations if these were already defined in SBO. However, this was more or less just for information to the user and could neither be saved nor be considered during any other processes. This version of SBMLsqueezer is able to not only take SBO terms into account while creating rate laws, but can even save SBO terms in the resulting SBML file. However, in CellDesigner plug-in mode, SBMLsqueezer is not yet able to save SBO term ids in CellDesigner data objects due to the missing functionality in its API.

SBMLsqueezer now contains an own parser to identify the correct SBO term ids and attributes that are required to annotate all newly created objects.

Whenever possible, SBMLsqueezer annotates newly created objects, such as Parameters or UnitDefinitions, with SBO identifiers.

MIRIAM Support

In contrast to earlier versions, SBMLsqueezer now also interprets and uses MIRIAM tags. The new command-line and configuration key option OPT_IGNORE_THESE_SPECIES_WHEN_CREATING_LAWS takes a list of comma-separated MIRIAM identifiers as value. Species annotated with BQB_IS and the given MIRIAM resource are then ignored when creating rate equations. This is, for instance, useful if small molecules such as water take part in a reaction. The concentration of water can hardly be measured and it is assumed to occur abundantly within the cell. By default, the list of species whose influence is to be neglected when creating new kinetic equations contains the KEGG compound identifiers for the following substances:

  • C00001: water
  • C00038: Zn2+
  • C00070: Cu2+
  • C00076: Ca2+
  • C00080: proton
  • C00175: Co2+
  • C00238: K+
  • C00282: H2
  • C00291: Ni2+
  • C01327: Cl-
  • C01528: H2Se
  • C14818: Fe(II)
  • C14819: Fe(III)

New Kinetic Equations and Extensibility

In earlier versions the inclusion of new kinetic equations into SBMLsqueezer was not an easy task. After writing a class that actually generates the new rate law, a rule had to be implemented of when to make this rate law available. Furthermore, the GUI had to be changed to include this new formula. Summarized, several changes in the program code were necessary to include additional rate laws.

Now SBMLsqueezer is based on Java reflection, i.e., initially SBMLsqueezer does not know any one of its available kinetic equations. These are all loaded when initializing SBMLsqueezer. Currently, twelve interfaces define the properties of all kinetic equations. The rules of when select which kind of rate equation only make use of the implemented interfaces. Hence, new kinetic equations can be incorporated into SBMLsqueezer simply by implementing designated interfaces. Since SBMLsqueezer is an open-source project, users can customize it easily and extend it with desired rate laws.

Much effort was put into the extension of SBMLsqueezer with additional rate laws for gene-regulatory processes. Earlier versions of SBMLsqueezer only provided the Hill equation variant suggested by Hinze et al. 2007. This equation has now been renamed to Hill-Hinze equation to highlight that it is actually a modification of the original rate law. Only in special cases this equation equals the traditional Hill equation (SBMLsqueezer will highlight these cases). Now nine additional rate equations were included:

  • Additive Model Linear: A generalized super class of all other additive rate laws for gene-regulatory processes.
  • Additive Model Non-Linear: defined in the paper “The NetGenerator Algorithm: Reconstruction of Gene Regulatory Networks” of Töpfer, S.; Guthke, R.; Driesch, D.; Wötzel, D., and Pfaff 2007
  • H-Systems: Spieth, C.; Hassis, N.; Streichert, F.; Supper, J.; Beyreuther, K., and Zell, A. “Comparing Mathematical Models on the Problem of Network Inference”, 2006.
  • NetGenerator Linear Model: “The NetGenerator Algorithm: Reconstruction of Gene Regulatory Networks” of Töpfer, S.; Guthke, R.; Driesch, D.; Wötzel, D., and Pfaff 2007
  • NetGenerator Non-Linear Model: “The NetGenerator Algorithm: Reconstruction of Gene Regulatory Networks” of Töpfer, S.; Guthke, R.; Driesch, D.; Wötzel, D., and Pfaff 2007
  • S-Systems: Tournier, L.: “Approximation of dynamical systems using S-systems theory: application to biological systems”
  • Hill-Radde equation: “Modeling Non-Linear Dynamic Phenomena in Biochemical Networks“ of Nicole Radde and Lars Kaderali
  • Vohradsky: “Neural network model of gene expression.” of Vohradský, J. 2001
  • Weaver: “Modeling regulatory networks with weight matrices” of Weaver, D.; Workman, C., and Stormo, G. 1999

The following new generalized kinetic equations for metabolic reactions were also implemented in SBMLsqueezer, which are all defined by Liebermeister et al., submitted manuscript 2010:

  • Common modular rate law (CM)
  • Direct binding modular rate law (DM)
  • Force-dependent modular rate law (FM)
  • Power-law modular rate law (PM)
  • Simultaneous binding modular rate law (SM).
Each one of these equations is only available in a reversible mode and the user must choose one of the three possible versions that determine the degree of thermodynamic correctnes. The weg version is the most complicated form but always thermodynamically correct. The hal version ensures thermodynamic correctness in most cases, whereas for the cat version thermodynamic properties cannot be guaranteed to be correct. The versions can be selected in the preferences dialog or provides as a command-line option.

Finally, the generalized form of Hill's equation as proposed by Cornish-Bowden (2004, p. 314 in “Fundamentals of Enzyme Kinetics”) has been implemented and is now also available for metabolic reactions.

If the corresponding flag is set, boundary conditions are also set for species that represent empty sets, i.e., degraded species, sources, or sinks in a reaction.

Support and Assignment of Units and Unit Definitions

For multy-compartment models concentration versus molecule counts matters. SBMLsqueezer now provides two different ways of ensuring unit correctness. First, each species can be brought to units of concentration. To this end, SBMLsqueezer interpretes the hasOnlySubstanceUnits attribute of each species. Depending on whether this is set to true, the species is divided by the size of the surrounding compartment. Otherwise the species already represents a concentration and nothing is done. Second, all species can be brought to molecule count units. This is again achieved with the help of the hasOnlySubstanceUnits attribute, but now SBMLsqueezer multiplies with the compartment size if this attribute is false.

In contrast to earlier versions, SBMLsqueezer now equipps all newly created Parameter objects with units. To this end, SBMLsqueezer derives the correct units from the context. For instance, in the mass action kinetics the units of the catalytic constants depend on the order of the reaction and have therefore to be computed whenever such a rate law is created. Furthermore, SBMLsqueezer also to considers the hasOnlySubstanceUnits property of each species and the way in which the surrounding compartment comes into play to derive the units of parameters.

To make models more realistic, SBMLsqueezer redefines the pre-defined SBML unit definition substance from mol to mmol and volume from l to ml.

If possible, SBMLsqueezer avoids creating new UnitDefinition objects. It first tries to find equivalent and already existing definitions in the model.

Bug Fixes

In the original paper of Hinze et al. 2007, inhibition was expressed with 1 - product of all inhibition functions. Earlier versions of SBMLsqueezer created a product that run over all inhibitors with (1 - inhibition function) for each such function.

In all gene-regulation kinetics, it is now assumed that degradation processes are distinct reactions that can be, e.g., modeled using a mass action rate law. Hence, no degradation terms can be found in gene-regulation kinetics anymore.

The rate law corresponging to SBO:0000266 was not correct. Earlier versions of SBMLsqueezer produced the fraction Kmjs/Kibj * I, but correct is S * I/Kibj (see Equation 10 in the supplementary material “Kinetic Laws”; the correct version of this equation can be found at http://www.ebi.ac.uk/sbo/main/SBO:0000266).

In case of an explicit enzyme catalysis, erlier versions of SBMLsqueezer did not multiply the numerator of equation SBO:0000273 with the enzyme. Therfore, it always produced the Vmax version of the equation, but the parameter was called kcat.

References

Parts of the content in these release notes have been taken from the Ph.D. thesis of Andreas Dräger (2010), University of Tübingen, Germany.