Getting Started

What is SBtab and how does it look like?

SBtab is a set of conventions and rules for data tables and spreadsheet files, facilitating the exchange of data in Systems Biology. These cumbersome words may easily be explained by looking at a simple example. SBtab tables can hold all sorts of data; our example contains kinetic quantities:

!!SBtab TableID='kp_1' TableType='Quantity' TableName='Kinetic constants' SBtabVersion='1.0'
!ID !QuantityType !Reaction:SBML:reaction:id !Compound:SBML:species:id !Mean !Unit
scp1 standard chemical potential F6P -1380 kJ/mol
scp2 standard chemical potential FBP -2206 kJ/mol
kcrf1 substrate catalytic rate constant R04779 0.02 1/s
kcrr1 product catalytic rate constant R04779 0.01 1/s
kmc1 Michaelis constant FBP R04779 0.5 mM
kmc2 Michaelis constant ATP R04779 0.5 mM
kmc3 Michaelis constant ADP R04779 0.1 mM
kic1 inhibitory constant ATP R04779 1 mM

Let us have a detailled look at the table. The first row is SBtabs declaration row. It is always preceded by !!SBtab, which is followed by a set of attributes. Some attributes are mandatory, others are optional. Mandatory attributes are TableID (defining a unique identifier of the table, which is important in documents consisting of more than one SBtab Table) and TableType (defining the type of data, which is contained in the SBtab Table). Optional attributes include an arbitrary TableName and the SBtabVersion, which defines the syntax version of SBtab that the table adheres to. For more information on these matters and more optional attributes please see the SBtab specification.

The second row holds the column names. These names are preceded by an exclamation mark, which makes them controlled SBtab columns. The SBtab validator tool can evaluate the syntax of controlled columns, which can be very useful (e.g. if the column !ID is not unique or if column !Mean holds non-numeric characters, both of which can lead to errors when employing SBtab Tables in software tools).

All rows from three onwards are value rows and they hold the actual content of the SBtab Table. In our example, we see here entries for kinetic constants (remember the attribute TableType from the declaration row, which says Quantity). The content of these rows is rather self-explaining, so we just browse through them: The !ID column holds an arbitrary identifier that must be unique within the SBtab Table and must not holds special characters (such as '#'). !QuantityType defines the type of quantity that is described, while !Reaction:SBML:reaction:id and !Compound:SBML:species:id directly link the entries to elements of a possible SBML model that belongs to the SBtab Table. Finally, !Mean and !Unit provide the numeric value and unit for the quantity.

Equipped with this knowledge, you will be able to read and write all SBtab files. They will only differ in their attributes, column names, and value rows, all according to the sort of data that is contained in the SBtab.

Why should I use SBtab in the first place?

SBtab Application Options

Data tables in the form of spreadsheet or delimited text files are the most popular data format in Systems Biology. However, they are often not sufficiently structured and they lack clear naming conventions that are required for modelling.
SBtab is an attempt to establish easy-to-use formats that are both flexible and clearly structured. It comprises defined table types for different kinds of data; syntax rules for usage of names, shortnames, and database identifiers used for annotation; and standardised formulae for reaction stoichiometries. Furthermore, SBtab enables users to easily define their own table types to customise SBtab for different types of data.
Using SBtab does not only ease a controlled exchange of data, but it also enables the integration of data into software tools and modelling workflows. Since SBtab can be converted to established modelling format SBML and vice versa, it serves as input and output format of a multitude of software tools and applications. But also SBtab itself is employed as exchange format of tools and repositories (such as KiMoSys and eQuilibrator).

How can I practically generate an SBtab file?

SBtab Creation Options

This is the easiest part: You can write SBtab tables with every text editor (such as Notepad or Word) or spreadsheet tool (such as MS Excel or LibreOffice).
If you use a plain text editor, you can employ commas, semicolons, or tabs as content delimiters. Then you save the file as either .csv format (if you have used commas or semicolons as delimiters) or .tsv format (if you used tabs). We recommend using tabs and saving in .tsv format.
If you want to use a spreadsheet tool instead, the columns are separated automatically and you can choose the delimiter and file format upon saving the file. Delimiters and formats are analogous to what is explained in the previous paragraph.
If this explanation was too abstract for your taste, you will find many example files in our Download section.

SBtab files describing biochemical network models

If you want to convert an SBtab table or even an SBtab document (consisting of possibly many SBtab tables) to SBML, the SBtabs need to contain data that can be translated to a biochemical network model. The most crucial SBtab table types employed for the conversion are Reaction, Compound, Compartment, and Quantity (there are more; but this is beyond the scope of this Getting Started section. You can read about it in the Documentation Section.).
Again, the concept is best understood by looking at an example. We will have a look at a small system consisting of two reactions R1 and R2.

!!SBtab TableID="" TableType="Reaction" SBtabVersion="0.9.1"
!ID !ReactionFormula !Identifiers:kegg.reaction !GeneName
R1 ATP + F6P <=> ADP + F16P R00658 pfk
R2 F16P + H2O <=> F6P + Pi R01015 fbp
!!SBtab TableType="Compound" SBtabVersion="0.9.1"
!ID !Name !InitialConcentration !Location
F6P Fructose-6-phosphate 0.1 cytosol
ATP ATP 0.2 cytosol
ADP ADP 1.1 cytosol
F16P Fructose-1,6-bisphosphate 1.2 cytosol
H2O Water 10.0 cytosol
Pi Inorganic phosphate 2.1 cytosol
PEP Phosphoenolpyruvate 3.3 cytosol
AMP AMP 2.1 cytosol
!!SBtab TableType="Compartment" SBtabVersion="0.9.1"
!ID !Size
extracellular 2.0
cytosol 1.0

What does the example show?

With the SBtab syntax knowledge acquired above, we can identify three SBtab tables, each starting with a declaration row (!!SBtab), and holding different columns and value rows. Each SBtab is responsible for providing a certain kind of information. The first one (TableType='Reaction') enlists reaction data, the second table (TableType='Compound') holds all species of the model, and the third SBtab finally contains the model compartments. Note here that only few columns in each table are mandatory (such as !ID), while many others are optional (such as !GeneName in the reaction table). An overview of supported table types and their corresponding columns (mandatory and optional) can be found in the SBtab specification.

How can I validate the syntax of my SBtab files?

One of the main purposes of SBtab is to make data automatically processable by software tools and applications. Therefore, it is of utmost importance to adhere to the correct syntax. This is not always trivial and can become tedious with growing complexity of the provided data. The SBtab Online Validator can be employed to assess the validity of your SBtab files. Simply click on the "Online Tools" link in the navigation bar and choose "Validator":

SBtab Tutorial SBML Validator
Choose "Validator" from the "Online Tools" (click on image to enlarge).

You can either provide them as separate SBtab tables or as one SBtab document consisting of >=1 tables. Next, each SBtab is listed separately in the interface and its syntax can be validated by clicking the corresponding Validate button. If any invalidities occur, warning and error messages will be issued on the bottom of the page. These messages are separated in file validation (is the file valid, e.g. the format and encryption) and file content validation (e.g. are all mandatory attributes set and do the column names correspond to the given table type).

SBtab Tutorial SBML Validator
Choose an SBtab file to validate and see warning/error messages on the bottom of the page (click on image to enlarge).

How do I convert SBtabs to SBML?

The SBtab files can be uploaded to the SBML Online Converter. Simply click on "Online Tools" link in the navigation bar and choose "SBML Converter":

SBtab Tutorial SBML Converter
Choose "SBML Converter" from the "Online Tools" (click on image to enlarge).

You can either provide them as separate SBtab tables or as one SBtab document with >=1 tables. Only SBtabs with model information can be translated to SBML (i.e. SBtabs with the table types Compartment, Reaction, Compound, Quantity, Layout, and FbcObjective). If you have submitted more than one SBtabs (as in the screenshot below), you can either convert these into seperate SBML files by using the Convert to SBML buttons next to the file name or you can convert all SBtabs into one SBML file via the Convert to SBML button on the top of the list (grey area).

SBtab Tutorial SBML Converter
Convert SBtab files to one SBML model file (click on image to enlarge).

If warnings occurred during the conversion process, these are issued on the bottom of the page in red lettering. We recommend to validate your SBtab files prior to conversion. The conversion from SBML to SBtab works analogously to the other direction.

How can I customise SBtab to my individual needs?

SBtab files can contain various sorts of data. The attribute TableType in the SBtab declaration row declares the type of data that is contained in the table (and thus, which columns are allowed and the content they may hold). The list of predefined table types is long and can be found in the SBtab specification. We provide the supported table types to our software tools in form of the definitions.tsv. If you want to use SBtab to exchange a kind of data that is not contained in our list of table types, you can create your own TableType and add it to the default definitions file. Then, you can upload your definitions.tsv in the SBtab customiser.

SBtab Tutorial Customiser
Choose "Customise SBtab" from the "Online Tools" (click on image to enlarge).

When you have uploaded your customised definitions file, you can upload your SBtab files in the SBtab validator and check if they adhere to your individualised table definitions.