Getting started with SBtab

1. What is parameter balancing? How and where can I employ it?

Parameter balancing is a computational method for obtaining consistent parameter sets for kinetic metabolic models. Experimentally measured values, when inserted into models directly, would be likely to yield incomplete and inconsistent parameter sets. Balanced parameter sets, computed from measured kinetic constants and other experimental data, respect constraints between biochemical quantities and assumptions about typical ranges, represented by prior values and bounds.

You can employ parameter balancing on this website in the Online Balancing section. How it is employed is shown in this tutorial. First, we will show you what sorts of files (1) you will need to provide. Next, you will see how the online balancing (2) is performed. Lastly, we will explain the output files (3).

If you are looking for an explanation on how to embed parameter balancing in your own programming workflows or want to have a look at the underlying Python 3 source code, please go to our parameter balancing Github page.

2. What will I need in order to perform parameter balancing?

Your data for parameter balancing needs to be provided in the Systems Biology standard formats SBML and/or SBtab. Please click on the buttons to read the details.

A: The model You can provide a kinetic metabolic model in either (a) SBML format or the (b) SBtab format:
  • (a) SBML is an established Systems Biology standard format which comes in .xml format. Models in SBML can be generated with a multitude of SBML software tools, the most commonly used ones probably being COPASI and MATLAB. The creation of an SBML model is beyond the scope of this website, but you will find good tutorials on the SBML tutorials page. Furthermore, you can have a look at our SBML example files in our Downloads section.
  • (b) SBtab is a spreadsheet-based Systems Biology standard format for the provision of various types of data. You can e.g. describe a kinetic metabolic model by building SBtabs for the inherent reactions, metabolites, compartments, and quantities. A small model of the phosphofructokinase reaction could be presented in SBtab format as such (the colors are not part of the format but only for the ease of display):

    Parameter Balancing Logo
    Three SBtab tables describing one kinetic model (the colours are for visualisation purposes only, not part of the format)

    The minimalistic example above shows a spreadsheet file consisting of three SBtabs. Each SBtab begins with a declaration row (preceded with "!!SBtab", coloured in dark blue), which defines the required table attributes. Special focus is on the attribute TableType, which defines what kind of data are presented in the SBtab. After the declaration row follow the column headers (coloured in bright blue), each of which are preceded by a single exclamation mark (e.g. "!ID").
    The topmost SBtab has the TableType "Compartment" and defines a single compartment with the ID c, a name cytosol and the size 1. Below that, the second SBtab of the TableType "Compound" provides a list of metabolites in the model including their IDs, names, localisations, charge, and if they are constant. The last SBtab in the example has the TableType "Reaction" and describes the Phosphofructokinase reaction. Note that this is only an excerpt of the many possibilities to define models and their entities in SBtab. You can find more information on the SBtab format and its capabilities in the SBtab specificiation.
    In general, SBtab files are simple spreadsheet files that can be created with every text editor (such as Notepad) or spreadsheet tool (such as MS Office or LibreOffice). The allowed formats are .csv, .tsv, and .xls - we recommend the usage of the tab-separated value format .tsv. You can find example files in our Downloads section.

Besides the obligatory kinetic model in SBML or SBtab format, you can provide an optional SBtab file with experimental data. While this feature is optional, we strongly recommend the provision of such a data file to improve the results of the parameter balancing. The SBtab TableType for these data is called "Quantity" and for the simple phosphofructokinase reaction above it could look as such:

Parameter Balancing Logo
SBtab table "Quantity" with experimental data (the colours are for visualisation purposes only, not part of the format)

The example file shows enzyme concentrations, inhibitory constants, concentrations (metabolites), standard chemical potentials, Michaelis constants, and an equilibrium constant for the phosphofructokinase reaction. These are collected from different sources (see column "Reference"). There may be multiple values for one parameter, which are averaged during the Parameter Balancing. It is important to link the data correctly to the model entities, which is realised via the columns "Reaction:SBML:reaction:id" and "Compound:SBML:species:id", which must hold the corresponding SBML identifiers of the reactions or species. Also note that some parameters (such as concentration) are only linked to an SBML species identifier, others (such as equilibrium constants) are only linked to SBML reaction identifiers, and finally some (such as Michaelis constants) are linked to both SBML species and reaction identifiers. Please make sure that the columns "Mean" and "Unit" are filled; if they are not, you can just as well omit the whole table row.

The allowed quantity types for the first column are "standard chemical potential" (kJ/mol), "catalytic rate constant geometric mean" (1/s), "Michaelis constant" (mM), "activation constant" (mM), "inhibitory constant" (mM), "concentation" (mM), "concentration of enzyme" (mM), "equilibrium constant" (dimensionless), "substrate catalytic rate constant" (1/s), "product catalytic rate constant" (1/s), "chemical potential" (kJ/mol), "reaction affinity" (kJ/mol), "forward maximal velocity" (mM/s), and "reverse maximal velocity" (mM/s). Find more information on these quantities in the Documentation section.

Parameter balancing is a highly complex modelling tool that can be configured to match the user's individual requirements. Thus, users can provide an SBtab file of the TableType "Config" which should look as follows:

Parameter Balancing Logo
The SBtab table "Config" defines configuration options for the parameter balancing (the colours are for visualisation purposes only, not part of the format)

The configuration options are:

  • use_pseudo_values (Bool; True or False): usage of pseudo values as substitute for missing parameter values to improve balancing (see Stanford et al. for details)
  • pH (float; 1-14): pH value that allows parameter balancing for correction of parameter values that do not correspond to the systems target pH value (see Lubitz et al. for details)
  • Temperature (float, in Kelvin): temperature that allows parameter balancing for correction of parameter values that do not correspond to the systems target temperature (see Lubitz et al. for details)
  • overwrite_kinetics (Bool; True or False): should existing kinetic laws in the SBML file be overwritten?
  • cell volume (float; in µm3): volume of the cell
  • parametrisation (string; hal or cat or weg): different parametrisation types for the convenience kinetics. See Liebermeister et al. for details.
  • enzyme_prefactor (Bool; True or False): should a prefactor for the enzyme concentration be set in the rate law?
  • default_inhibition (string; complete, partial, or specific): type of enzyme inhibition
  • default_activation (string; complete, partial, or specific): type of enzyme activation
  • model_name (string): name that is used for the result files
  • boundary_values (string; ignore): ignore boundary values (temporary feature)

As noted in the brackets for each of the items, some of the configuration options require further reading. Changing them is only recommended for experienced users. You will find the default configuration file in our Downloads section and can use it for alterations.

Since parameter balancing is a Bayesian estimation, it relies on a prior distribution of the quantity types. The default prior distribution has been chosen carefully for each quantity type and looks as such:

The table is too large to be sensibly displayed on mobile. Please review on desktop or download the table in the Download section.

Quantity Type Symbol Unit BiologicalElement MathematicalType PhysicalType Dependence PriorMedian PriorStd PriorGeometricStd LowerBound UpperBound DataStd DataGeometricStd SBML element UseAsPriorInformation MatrixInfo
Standard chemical potential μ0 kJ/mol Species Additive Thermodynamic Basic 0 500 -500 500 10 Global parameter 1 [I_species, 0, 0, 0, 0, 0, 0, 0]
Catalytic rate constant geometric mean kV 1/s Reaction Multiplicative Kinetic Basic 10 100 0.00000001 10000 10 1.2 Local parameter 1 [0, I_reaction, 0, 0, 0, 0, 0, 0]
Michaelis constant kM mM Reaction/Species Multiplicative Kinetic Basic 0.1 10 0.0000001 1000 1 1.2 Local parameter 1 [0, 0, I_KM, 0, 0, 0, 0, 0]
Activation constant kA mM Reaction/Species Multiplicative Kinetic Basic 0.1 10 0.0001 100 1 1.2 Local parameter 1 [0, 0, 0, I_KA, 0, 0, 0, 0]
Inhibitory constant kI mM Reaction/Species Multiplicative Kinetic Basic 0.1 10 0.0001 100 1 1.2 Local parameter 1 [0, 0, 0, 0, I_KI, 0, 0, 0]
Concentration c mM Species Multiplicative Dynamic Basic 0.1 10 0.0000001 1000 1 1.2 Species (conc.) 1 [0, 0, 0, 0, 0, I_species, 0, 0]
Concentration of enzyme u mM Reaction Multiplicative Dynamic Basic 0.001 100 0.0000001 0.5 0.05 1.2 Local parameter 1 [[-1/RT * Nt], 0, 0, 0, 0, 0, 0, 0]
pH pH dimensionless None Additive Dynamic Basic 7 1 0 14 1 Global parameter 1 [0, 0, 0, 0, 0, 0, 0, 1]
Standard Gibbs energy of reaction dmuO kJ/mol Reaction Additive Thermodynamic Derived 0 500 -1000 1000 10 Global parameter 0 [Nt, 0, 0, 0, 0, 0, 0, 0]
Equilibrium constant keq dimensionless Reaction Multiplicative Thermodynamic Derived 1 100 0.00000000001 10000000000 10 1.2 Local parameter 1 [[-1/RT * Nt], 0, 0, 0, 0, 0, 0, 0]
Substrate catalytic rate constant kcat+ 1/s Reaction Multiplicative Kinetic Derived 10 100 0.01 1000000000 10 1.2 Local parameter 1 [[-0.5/RT * Nt], I_reaction, [-0.5 * Nkm], 0, 0, 0, 0, 0]
Product catalytic rate constant kcat- 1/s Reaction Multiplicative Kinetic Derived 10 100 0.00000000001 1000000000 10 1.2 Local parameter 1 [[0.5/RT * Nt], I_reaction, [0.5 * Nkm], 0, 0, 0, 0, 0]
Chemical potential μ kJ/mol Species Additive Dynamic Derived 0 500 -500 500 10 0 [I_species, 0, 0, 0, 0, [RT * I_species], 0, 0]
Reaction affinity A kJ/mol Reaction Additive Dynamic Derived 0 500 -100 100 10 0 [[-1 * Nt], 0, 0, 0, 0, [-RT * Nt], 0, 0]
Forward maximal velocity vmax+ mM/s Reaction Multiplicative Dynamic Derived 0.01 100 0.000000001 10000000 0.1 2 Local parameter 0 [[-0.5/RT * Nt], I_reaction, [-0.5 * Nkm], 0, 0, 0, I_reaction, 0]
Reverse maximal velocity vmax- mM/s Reaction Multiplicative Dynamic Derived 0.01 100 0.000000001 10000000 0.1 2 Local parameter 0 [[0.5/RT * Nt], I_reaction, [0.5 * Nkm], 0, 0, 0, I_reaction, 0]
Forward mass action term thetaf 1/s Reaction Multiplicative Dynamic Derived 1 1000 0.000000001 100000000 1 2 0 [[-1/(2*RT) * h * Nt], I_reaction, - 1/2 * h * abs(Nkm), 0, 0, h * Nft, 0, 0]
Reverse mass action term thetar 1/s Reaction Multiplicative Dynamic Derived 1 1000 0.000000001 100000000 1 2 0 [[ 1/(2*RT) * h * Nt], I_reaction, - 1/2 * h * abs(Nkm), 0, 0, h * Nrt, 0, 0]
Forward enzyme mass action term tauf mM/s Reaction Multiplicative Dynamic Derived 1 1000 0.000000001 100000000 1 2 0 [[-1/(2*RT) * h * Nt], I_reaction, - 1/2 * h * abs(Nkm), 0, 0, h * Nft, I_reaction, 0]
Reverse enzyme mass action term taur mM/s Reaction Multiplicative Dynamic Derived 1 1000 0.000000001 100000000 1 2 0 [[ 1/(2*RT) * h * Nt], I_reaction, - 1/2 * h * abs(Nkm), 0, 0, h * Nrt, I_reaction, 0]
Michaelis constant product KMprod mM Reaction Multiplicative Kinetic Derived 1 1000 0.001 1000 1 2 Local parameter 0 [0, 0, Nkm, 0, 0, 0, 0, 0]
Catalytic constant ratio Kcatratio dimensionless Reaction Multiplicative Kinetic Derived 1 10 0.00000000001 10000000000 1 2 Local parameter 0 [-1/RT * Nt], I_reaction, [-1 * Nkm], 0, 0, 0, 0, 0]

Experienced users may choose to change the prior distribution to make it match their individual requirements. Please only do so carefully as it has significant effects on the parameter balancing. Also, read the corresponding section 2.1.2 from the Parameter Balancing manual and the Chapter on Biochemical Quantities in the Documentation Section. Users can provide an alternative table for the prior distributions in SBtab format. We recommend to use the Default Prior SBtab as a starting point for making alterations.

3. How is Online Balancing performed?

If you have the file/s explained in Part 1 of this tutorial in place, the online balancing is performed easily. Start by clicking the "Online Balancing" link in the navigation bar on this page:

Parameter Balancing Logo

You will be directed to the Online Balancing page, where you can upload your prepared input files. There are two alternative options how to do this: (a) Left column: Provide your kinetic metabolic model in SBML format accompanied by optional SBtab files. (b) Right column: Provide your kinetic metabolic model and all other optional files in a single large SBtab file. Here, we explain the two options:

Option 1: Separate Input Files

Parameter Balancing Logo

In this option, you can upload separate input files for the parameter balancing. The SBML file for the kinetic model is obligatory, all other files are optional. All file formats and contents are described in Part 1 of this tutorial. After you have uploaded your SBML file, you can simply click on the "Balance Parameters" button on the bottom of the column. The software will read all your submitted files automatically, perform the parameter balancing and redirect you to the download area.

Option 2: Single Input File

Parameter Balancing Logo

Instead of uploading all files separately, you can also upload all required data as one single SBtab file. In Part 1 of this tutorial we have shown how a kinetic metabolic model can look like in the SBtab format. You can simply add all optional SBtab files (such as the data, configurations, or prior distribution files) to the end of the model SBtab (be aware: do not add them as separate work sheets, but add them below the other SBtabs in the spreadsheet file). You can have a look at our example files in the Download section (focus on the files that say "SBtab format, single input file").
If you are interested in how you can automatically translate your SBML file into the SBtab format (and vice versa), you can have a look at the SBML <-> SBtab converter on the SBtab homepage. We want to remind you that we recommend .tsv files as preferred SBtab format.
After the file is uploaded you can start the parameter balancing by clicking the "Balance Parameters" button on the bottom of the column. Parameter balancing is performed and you will be redirected to the Download area.

4. The Download Area

The download area will appear after you have clicked the "Balance Parameters" button. Please be aware that this might take some time, depending on the size of your input data.

Parameter Balancing Logo

You can download your SBML model with inserted balanced parameters in the "Download area SBML" on the top of the page. The default behaviour will cause the old kinetic rate laws of the model to be overwritten with common modular rate laws sporting the balanced parameter set. This behaviour can be influenced in several ways by using an options file in the parameter balancing. You can choose the parametrisation, enzyme behaviour, and more (see Part 1C of this tutorial). By clicking on the name of the file you can display the SBML source code in a new tab.

In the "Download area SBtab" you can download the full balanced parameter set for your model in SBtab format. By clicking on the file name you can display the SBtab file in a new tab. The values that are employed in the balanced model can be found in the column "Mode", which are point estimates from the computed posterior distribution. In order to understand the full scope of the output file we would like to refer you to Section 2.2.3 of the parameter balancing manual.

Finally, you can download the whole bundle of output information in one single SBtab file: The kinetic model, the quantities, the balanced parameter set and the employed prior distribution. This is provided as modelname_balanced_model.tsv.

5. Closing Remarks

This tutorial is describing the Online Balancing only superficially. You can find more and deeper information as well as FAQ in the Documentation Section and the Parameter Balancing Manual. Here, you can also find details about employing parameter balancing in your programming scripts, workflows, or via Linux commandline. Parameter balancing can also be installed as a pip package. All required file formats and exemplary file contents can be found in the Download Section. And finally, please do not hesitate to contact Wolfram Liebermeister and Timo Lubitz in case of questions, bugs, or feature requests. We are always happy to hear user feedback.