Systems Biology Format Converter (SBFC)

= User Guide =

Introduction
The Systems Biology Format Converter (SBFC) aims to provide a generic framework to convert a Systems Biology model format into another. Interoperability between formats is a recurring issue in Systems Biology. Although there are several tools available to convert models from one format to another, most of them have been independently developed and/or cannot be easily combined. The framework is written in Java and can be used as a standalone executable or as web service. The SBFC framework currently supports conversion from SBML to BioPAX Level 2 and Level3, Matlab, Octave, XPP, Dot, or APM. It is also planned to add conversions from SBML to SBGN-ML, and from SBGN-ML to an SBGN enriched graphical representation designed for use in a web browser.

SBFC is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or any later version. This is a collaborative project and we hope that developers will provide support for more formats by creating new modules.

The following sections present an introduction about the SBFC package for users. A separate Developer Guide can be found here.

Roadmap
The definition of a roadmap for the future development of SBFC is currently in progress. A preliminary document is here.

Requirements
To use SBFC as a standalone software, the following software must be installed:


 * Java 6+.

The SBFC web service, was tested with the following browsers and is currently compatible as follows:


 * Google Chrome up to version 44. Both GNU/Linux and Windows are supported;
 * Mozilla Firefox up to version 40. Both GNU/Linux and Windows are supported;
 * Internet Explorer. Limited support.

Download and Installation
You can download the latest version of SBFC including all the converters here: .

You can also download some of the converters as a separate package from the SBFC SourceForge Web Site.

The SBFC user and developer manuals can be downloaded as pdf documents from the following web links: user manual and developer manual.

Using SBFC as standalone package
Download or the specific converter of interest from the SBFC webpage in SourceForge. After downloading and uncompressing the package, you can put the extracted folder where you prefer. We suggest to create a folder containing the model you need to convert inside the SBFC folder.

Using SBFC within a program
Download or the specific converter of interest from the SBFC web page in the SourceForge website. After downloading and uncompressing the package, you should put the file sbfc-.jar in the library folder of your program and include this file in the program library path required for compilation. If you have downloaded the standalone version of SBFC, you do not need to do anything else. Otherwise, you should also install the dependencies libraries required by SBFC.

How to use SBFC
This section explains how to use the software SBFC, providing the user with some use case.

Conversion using a console
After unpacking the file, you will find several script files (.sh for Linux/OSX, .bat for windows). These scripts are used to launch conversion jobs. To test the correct installation of SBFC, a set of model examples is available in the folder examples:


 * example/SBML.xml : is a very simple model in SBML
 * example/BioPAX.owl : is a very simple model in BioPAX

To retrieve the list of currently supported converters (Java Class names), run the command: ./sbfModelList.sh (or sbfModelList.bat on windows)

APMModel BioPAXModel DotModel OctaveModel SBGNMLStringModel SBGNModel SBMLModel XPPModel
 * 1) Example of output

To retrieve the list of the currently supported input models (Java Class names), run the command: ./sbfConverterList.sh (or sbfConverterList.bat on windows)

Miriam registry file = Miriam.xml BioPAX2BioPAXL3 SBML2APM SBML2BioPAX_l2 SBML2BioPAX_l3 SBML2Dot SBML2Matlab SBML2Octave SBML2SBGNML SBML2SBML SBML2XPP URL2URN URN2URL For a detailed description of the available converters, please see following Section.
 * 1) Example of output

To convert a model file (or the models in a folder), run the command: ./sbfConverter.sh [InputModelClassName] [ConverterClassName] [modelFile | modelsFolder]

For instance, to convert an SBML model (e.g. SBML.xml) to an Octave model the command will be: ./sbfConverter.sh SBMLModel SBML2Octave examples/example/SBML.xml

A script file is also present for certain converters to simplify the command. To do the previous conversion, a user can also type the following command: ./sbml2octave.sh examples/example/SBML.xml (or sbml2octave.bat examples\example\SBML.xml on windows)

Conversion using Java
To convert using Java directly, you can:

java Converter [InputModelClassName] [ConverterClassName] [ModelFile] For instance: java Converter SBMLModel SBML2Octave examples/example/SBML.xml /* Input model given as a string */ public static String ConvertFromString([InputModelClassName] [ConverterClassName] [ModelString]) /* Input model given as a file */ public static void ConvertFromFile([InputModelClassName] [ConverterClassName] [FilePath])
 * run the Converter class located in /org/sbfc/converter/ . In this case the general syntax is:
 * Alternatively, invoke one of the two following methods in the Converter class from your code directly:

Conversion using a GUI
If you don’t need to convert a large number of files then instead of using directly the command line or some scripts, you can launch some conversions using a simple GUI:

Run the ConverterGUI class located in the package org.sbfc.converter. In this case the general syntax is: java −jar sbfc−x.y.z−standalone.jar org.sbfc.converter.ConverterGUI

If your system is configured to execute jar files, you can also double click on the sbfc-x.y.z- standalone.jar from a file explorer directly to start the gui. Once the gui open, you have to specify your input file and the converter you want to use. Optionaly you can specify an output file. If you don’t specify one, an automatic output file path will be generated automatically, it will be located on the same folder as the input file. Then you just need to click on the ’Convert’ button to start the conversion. If you let the ’open output file’ checkbox selected, at the end of the conversion a new window will open showing the content of the output file. If you unchecked the checkbox, you will get a small dialog window to tell you once the conversion is done.

Alternatively, you can invoke the following method in the ConverterGUI class from your code directly to get a JFrame that you can show to the users: ConverterGUI.getConverterGuiInstance.setVisible(true);

Core SBFC converters
This section introduces the converters currently supported. For a more detailed description, click on the converter name.


 * SBML to SBML
 * A list of scripts for converting between SBML levels and versions. Scripts for converting SBML model annotation from Miriam (urn) to identifiers.org (url) and viceversa are also provided.


 * SBML to BioPAX
 * The main objective of the BioPAX initiative is to develop a data exchange format for biological pathways that is flexible, extensible, optionally encapsulated and compatible with other standards and can be widely adopted in a timely manner.


 * SBML to SBGN-ML
 * The mission of the SBGN-ML project is to develop high quality, standard graphical languages for representing biological processes and interactions. [IN PROGRESS]


 * SBML to Matlab
 * Matlab is a high-level language, primarily intended for numerical computations. It provides a convenient GUI and command line interface for solving linear and nonlinear problems numerically, and for performing other numerical experiments.


 * SBML to Octave
 * GNU Octave is a high-level language, primarily intended for numerical computations. It provides a convenient command line interface for solving linear and nonlinear problems numerically, and for performing other numerical experiments using a language that is mostly compatible with Matlab.


 * SBML to XPP
 * XPP-Aut is a numerical analysis software. It permits to solve differential equations, difference equations, delay equations, functional equations, boundary value problems, and stochastic equations.


 * SBML to Dot
 * GraphViz is an open source graph visualization software. The language used to encode the graphics processed by GraphViz is called DOT. Note that a "dot" file can be used with other graphical software and you have the possibility to convert them to PNG, SVG, ..)


 * SBML to APM
 * APM (APMonitor Modeling Language) is an optimization software for mixed-integer and differential algebraic equations. It is coupled with large-scale solvers for linear, quadratic, nonlinear, and mixed integer programming (LP, QP, NLP, MILP, MINLP). Modes of operation include data reconciliation, real-time optimization, dynamic simulation, and nonlinear predictive control. It is freely available through MATLAB, Python, or from a web browser interface.


 * BioPAX L1/L2 to L3
 * The main objective of the BioPAX initiative is to develop a data exchange format for biological pathways that is flexible, extensible, optionally encapsulated and compatible with other standards and can be widely adopted in a timely manner.

Additional third-party SBFC converters
Currently, the Systems Biology community has been working on additional converters. Each of these converters developed by third-parties can use specific libraries and library versions which could be different and not fully compatible with the libraries currently required by SBFC. For this reason, at the moment, these converters are separate from the main SBFC converters. For a more detailed description, click on the converter name.


 * MDL to SBML
 * A converter translating from MDL, a language for the software Monte Carlo Cell (MCell), to SBML.


 * BioPAX from/to GPML
 * Two converters translating between GPML, a Graphical Pathway Markup Language describing biological pathways, and BioPAX.


 * Antimony from/to SBML
 * A converter translating between Antimony and SBML (using http://antimony.sourceforge.net/).


 * CellML from/to SBML
 * A converter translating between CellML and SBML (using http://antimony.sourceforge.net/).

SBFC as web service
Conversion jobs can be very demanding in term of CPU and memory, if you have large models or a large number of models to convert. Systems biology models can also be converted online using SBFC web service. This uses the SBFC in the background so only the converters already integrated in SBFC are available. We implemented two modes to convert models within SBFC web service:
 * via a web browser. In this case the conversion uses the cluster of computer machines at the EBI (European Bioinformatics Institute). Please, visit the web page: http://www.ebi.ac.uk/biomodels/tools/converters/. The user must specify the input and output model formats. Models can be converted via three input methods: multiple file upload, URL pointing, copy/paste. Once the conversion jobs are started, the results can be downloaded for 72 hours after the conversion finished. It is worth noting that neither the original nor the converted models are kept on the servers for a period longer than 72 hours for privacy purposes. As the web service uses SBFC in the background, only the converters already integrated in SBFC are available.
 * via the Java class ConverterLink. This class allows the user to run conversion job and get the converted model directly as the return value of a method. This is convenient if SBFC is integrated in an existing application. A UML class diagram for the class ConverterLink and how to use it is shown in the attached Figure. Depending on user requirements, two types of methods for submitting conversion jobs can be selected within the class ConverterLink:
 * blocking calls: the methods submitAndGetResultFromURL and submitAndGetResultFromString start a conversion job and wait until the model is converted and returned from the web server. For big models the conversion process can take several minutes.
 * non blocking calls: the methods submitJobFromURL and submitJobFromString start a conversion job and immediately return a ConversionId object. The status of the conversion can be check later on with the getJobStatus method.

Advanced options
For using SBFC with libsbml, the user must configure the environment variable LD_LIBRARY_PATH to include the path to your installed copy of libsbml. For Unix/Linux users, this environment variable is declared in the following files: For Windows users, please consider the same files but with extension .bat instead of .sh.
 * sbfConverter.sh
 * sbfConverterList.sh
 * sbfConverterOnline.sh
 * sbfModelList.sh

Error messages
SBFC can notify the user with three potential error messages to highlight problems during the conversion process or when reading / writing a model format. These error messages are thrown via the following SBFC exceptions:


 * ConversionException: The conversion between two model formats was not successful;
 * ReadModelException: The input model was not imported correctly;
 * WriteModelException: The output model was not exported correctly.

Legacy converters
Here is a list of converters that are not yet integrated with SBFC because they are no longer maintained. Detailed descriptions for each of these converters can be found on the following pages:


 * SBML to XPP: outdated XSL version
 * SBML to Dot: outdated XSL version
 * SBML to BioPax: outdated XSL version
 * SBML to Scilab: outdated XSL version
 * SBML to CellML: outdated XSL version
 * CellML to SBML: outdated XSL version

= Developer Guide =

A Developer Guide about how to develop with SBFC can be found here.