Introduction

Welcome to the SBtab documentation. On this page, you can find all information on the SBtab format and how to use it. This includes the SBtab specification, which defines the format characteristics in detail. Also, you will find the SBtab definition file that contains all predefined SBtab table types and the corresponding columns and contents.
Next to the SBtab specification details, we offer several software tools for the handling of SBtab. These tools can be used online, as Python3, R, or Matlab programming code or as commandline tools. See the SBtab employment options for more details. Also, visit the SBtab Github page if you are interested in the source code or want to contribute to the project.
If you encounter any problems with SBtab or its tools, please consult our Section Frequently Asked Questions. Any problems that are not answered in this section, as well as all sorts of positive or negative feedback, are welcome for the SBtab team.
Finally, numerous SBtab example files can be found in the Download section and our Getting Started Section provides a tutorial for beginners.

SBtab format specification

• SBtab version 1.0
• SBtab version 0.9
• SBtab version 0.8

A specification for the current version of SBtab can also be found on arxiv.org.

Definition of SBtab table types

The definition of all predefined SBtab table types, their corresponding columns and contents, can be found in the definitions.tsv. Besides the table type information, this file can also be employed if you want to define an individual table type for types of data that SBtab does not cover so far. Simply download the definitions, add your table type and the columns to the end of the file, and upload it on the SBtab customiser. Then, you can validate SBtab files whether they adhere to your individual table type definition on the SBtab validator.

1. The SBtab Online Interface

The online interface of SBtab allows the validation of SBtab files, the conversion of SBtab to SBML and vice versa, and the customisation of the SBtab format for individual purposes. These interfaces are easy to use and basically only include file upload/download and the clicks of an overseeable amount of buttons. Our Getting Started Section will give you a head start.

2. Python Code

We have implemented SBtab objects (for single tables and documents) and all tools in Python3. The source code is openly available on the SBtab Github page and we encourage users to contribute to the project. You can embed SBtab objects and tools into your own programming workflows over the interfaces explained on Github.

3. Python Pip Package

Python users can install SBtab functionality under Linux systems in form of a pip3 package. First, install pip on your system, if it is not already installed. Next, simply type sudo pip3 install sbtab in your commandline and the package will be installed. Finally, you can import the package in your Python3 scripts via import sbtab. More information can be found on the SBtab Github page.

4. Matlab Code

Many basic functionalities of SBtab can also be used via Matlab. The code can be downloaded from the Matlab SBtab Github page. However, please note that this does not encompass the whole functionality of SBtab. Moreover, the Matlab toolbox expects SBtab files to be in tab-separated text format exclusively.

5. R code

We provide a simple interface that allows R users to import the SBtab Python code into their R projects, manipulate SBtab objects, and call Python functions from within the R environment. For this, we use the rPython library, which needs to be preinstalled to employ the provided code. Alongside these rPython-based approaches, we also translated the creation of an SBtab file document (including one or more SBtabs) from Python directly into the R language. These example files as well as the source code are available on the SBtab Github page. We hope that these elucidations will help R programmers to integrate SBtab files and functionalities into their projects.

Python-SQlite interface

Single or collections of SBtab files can be automatically converted into an SQLite database, using the package sqlite_interface within the SBtab GitHub page. This feature can be useful for developers that would like to allow users to upload their data in the form of SBtab into a web service, and using SQL to query the data using standard web development tools.

SBtab: Tables or Documents?

SBtabs can contain various sorts of data. Often, it is completely sufficient to have a single table that contains e.g. a list of experimental data values or a list of reactions that you wish to exchange with a colleague or that you want to use as input of a software tool. In these common cases, you would use a simple SBtab table of a corresponding table type Quantity or Reaction. A very small example SBtab table is depicted below.

Sometimes however, it is more convenient to bundle a set of information or of different data to one larger document. For this purpose you can employ SBtab Documents, which consist of more than one SBtab table. This may come in handy when you have multiple lists of experimental data with different setups but on the same topic. It is even more convenient, when you want to describe on biochemical model consisting of compartments, compounds, reactions, and so on. If you collect the single SBtab tables in one document (e.g. subsequently in a spreadsheet file), they make up one SBtab document. It is good practise to start such a document with a document declaration row, which is preceded with a triple exclamation mark (in contrast to an SBtab table that has a double exclamation mark). Make sure that all TableID attributes of the SBtab tables are unique within one SBtab document as well as all entries of !ID columns. Moreover, keep track of the shortnames in your document, which can e.g. link an entry from a compound SBtab to the reaction formula of a reaction SBtab. See the small example SBtab document depicted below.

Information for programmers: The underlying Python code thus distinguishes between SBtabTable objects and SBtabDocument objects, where the latter contain one or more of the former.

The SBtab software tools usually allow the input of either SBtab tables or SBtab documents. The standard output of the SBML to SBtab converter is a SBtab document consisting of the different model entitie types.

SBML and SBtab

SBtab to SBML The content of some SBtab table types can be converted to the Systems Biology standard format SBML with the SBML converter. These comprise the table types which describe data on model entities, such as Compartment, Compound, Reaction, and Quantity. Please note that SBML model files have rigid rules on their content. E.g., you cannot translate a sole Quantity SBtab to SBML, because SBML requires model entities. In contrast, you are able to convert a sole Compound or a sole Reaction SBtab to SBML, because SBML regards these sorts of data as sufficienct for a valid model. However, during the conversion process to SBML we often have to complement the user data in order to adhere to all SBML restrictions. Examples include the creation of a default compartment (if no compartment information is provided by the user) or the setting of entity attributes to default values (if not provided by the user; e.g. the attribute irreversible for reactions). If we were to omit these complementations, the generated SBML files would be considered invalid. To make these default settings as transparent as possible, we provide detailled information in the SBtab specification.

SBML to SBtab It is also possible to convert SBML files to SBtab files with the SBML converter. The content of the SBML compartments, species, reactions, and parameters is translated to SBtab files of the corresponding table types. Presenting the data from the SBML files in the SBtab format makes the content human readable in form of simple spreadsheets. Moreover, users can make alterations in the SBtab files and convert them back to SBML, making the SBtab converter an SBML editor by proxy. However, we recommend validating the SBtab syntax after any alterations before you translate them back to SBML. You can use the SBtab validator to do so.

SBML Level 3 Packages Upon the introduction of version number 3, SBML has introduced a number of Level 3 Packages to describe specific sorts of data their format definition. Our SBML <-> SBtab converter supports conversion of the SBML3 FBC package and a basic version of the SBML3 layout package. For more information please consult the SBtab specification.

In any case of encountered errors or arising questions with this website, its tools, and plugins, please don't hesitate to contact Timo Lubitz. However, many problems may be sorted out by having a close look to this troubleshooting page. It enlists several troubles that users had and offers solutions.

How do I make a table file SBtab-compliant?

SBtab tables are normal data tables (spreadsheets or delimited text files), but to enable an easy exchange of data, these tables need to respect certain rules. You can make your own table files SBtab-compliant by a number of small changes:

1. Choose an SBtab table type appropriate for your specific kind of data (for a list of predefined table types, see the SBtab specification).
2. Insert a declaration line (starting with "!!SBtab") as the first line of your table and declare the table type by an attribute "TableType='x'" in the same line, where 'x' corresponds to a valid table type.
3. You will also need to set a table identifier by adding the attribute "TableID='y'" to the first line as well, where 'y' is an arbitrary identifier (which must be unique for each table in a SBtab document consisting of more than one table).
4. The second row after the declaration row is the row with the column titles. Unique identifiers must be given in a column "!ID". The elements in this column serve as shortnames, to be referenced in other tables, and must therefore be unique (e.g., unique gene names). It is good practise to make the "!ID" column the first column.
5. Each table type has a predefined set of supported columns, which can be see in the SBtab specification and the definitions file. Choose from the list for your table type, which columns you want to use. Each column must be preceded with an exclamation mark "!" and its content must adhere to the data format given in the definitions file. You can also add individual columns that are not part of the SBtab predefined table type. If you do so, simply omit the "!" at the beginning of the column header. Then, the column is part of your SBtab but its content will be ignored by SBtab software tools.
6. In columns containing biological annotations (e.g., database identifiers for chemical compounds), use column names as described in the SBtab specification.
7. If you want to create a whole SBtab document instead of a single SBtab table, please make sure to be consistent in the usage of shortnames and be careful that all IDs are unique within the whole document. You will further need to begin your document with a document declaration row preceded with "!!!SBtab" and followed by the document attributes.

If you are still unsure about aforementioned points, we suggest you have a look at our numerous example files in the Download Section. In the end, to check your SBtab files for correct syntax, you can use the online validator.

I cannot upload and/or convert my SBML file to SBtab.

The SBML to SBtab converter requires SBML code Level 2, Version 4, or higher. Please make sure that your SBML file has the correct file extension (.xml or .sbml) and if this does not help, consult the online SBML validator to ensure that your file is valid SBML.

My SBtab file cannot be uploaded.

SBtab files can be uploaded as long as they have the right file extension. Possible extensions are .csv, .tsv, .xlsx. We recommend the usage of .tsv. However, if you still cannot upload your SBtab file, please consult the SBtab example files that are provided in the Files Section.

When I open my SBtab file with Excel or LibreOffice, the columns are not separated correctly.

This can happen when the spreadsheet tool does not identify the delimiter of the file correctly. Some version of LibreOffice cannot deal with tsv files; in this case it suffices to rename your file extension from tsv to csv and then it works. In any case, all tools offer the possibility to choose the delimiter for the columns. This happens usually on startup of the software (LibreOffice) or can be chosen via the Text Import Wizard (MS Excel).

My SBtab file cannot be converted to SBML.

Note that not *all* SBtab files can be converted to SBML, they need to contain model structure information. Thus, the conversion requires at least a Reaction or Compound SBtab file. Of course, combinations are feasible, as long as one of these mandatory files is provided. If the conversion still does not work, try and validate the files you are using on the SBtab validator page. If there is no validation warning, but the conversion still does not work, please look at the SBtab example files and consult the specification. Oftentimes, it can be helpful to view the SBtab file with a text editor instead of Excel/Open Office; this enables the user to see the file completely unformatted and identify possible problems.

The Excel add-in cannot be installed properly.

This can have several reasons. First, verify that all required pre-requisites are fulfilled for the add-in to work (see xlSBtab add-in page). Then, in Excel you can edit the "SBtab settings" in the SBtab add-in menu. Click the button and make sure that the paths are set correctly: the Python interpreter should be set to the installation directory "xlSBtab/python/python.exe" and the SBtab path should be set to "xlSBtab/SBtab/scripts". The installation directory xlSBtab can usually be found in "/Program Files/" or "/Program Files (x86)/", depending on your system.

I converted SBtab to SBML, but the SBML is invalid.

During the conversion from SBtab to SBML, kinetic laws from the SBtab file can be converted to SBML code. This is a complex process and the kinetic laws provided by the user are not checked for causality: If the user provides erroneous laws, the resulting SBML file will be invalid. The same scenario holds for rules (algebraic, rate, or assignment). In future, SBtab will also comprise validity checks of kinetic laws and rules in SBtabs, but currently this is not the case. By using the SBML online validator, you can always find out which other invalidities an SBML file might hold.

There seems to be a chaos in the submitted SBtab and SBML files in my browser session.

This can happen from time to time while extensive uploading and downloading of files from the server side. Simply click on this clear session link to clear all files from your current session and start new. Note that currently uploaded files will be lost from the session.

Citing SBtab

If you are using SBtab, please cite our corresponding publication:
Lubitz T., Hahn J., Bergmann F.T., Noor E., Klipp E., Liebermeister W. (2016), SBtab: A flexible table format for data exchange in systems biology, Bioinformatics (2016)