tCal distribution page

Welcome! Here we provide useful information on tCal to facilitate its application in your work.
[ What is tCal ]
tCal is a Python programming module which implements advanced thermodynamic model of gene transcriptional regulation in bacteria. Its functionalities are:
  • build realistic transcription regulation models of bacterial genes
  • calculate transcription probability
  • export formula to facilitate construction of SBML models
In this page you can find the paper describing tCal module. In its reference there are some excellent papers describing the thermodynamic model in full detail. The supplementary document contains detailed description on how the transcription probability formula implemented in tCal is derived. Also a brief tutorial and demo programs are available on this page. You can try it instantly by using ``tCal online''.

Download tCal package Try tCal online!

[ Publication ]
Xin Zhou and Zhen Su, tCal: transcriptional probability calculator using thermodynamic model, Bioinformatics 2008 24(22): 2639-2640. Link to publisher, and PubMed.
Download paper (PRE-PRINT) Download supplement document

(Oct 4, 2008) In APPLICATION section, near line 22, original words "C4 and C5 show mixed effect of repressor and activator with equal DNA-binding strength ( = ...)". The energy misses a delta sign, it is best written as " = = -8kBT".
[ Tutorial ]
tCal is written in Python programming language, so basic Python programming is needed to use it. It can run on any platform with Python interpreter installed (version 2.5 or higher required).

In this tutorial I will show you how to model some simple examples as figure 1 of the paper. The tutorial will procceed in interactive mode of Python. It is straight forward to utilize these codes to implement complicated models. First place tCal module in your working directory and start Python interpreter:

$ python

You are now in interactive mode of Python. Import all classes from tCal package:

>>> from tCalculator import *

and build an instance of ``TranscriptionUnit'' class:

>>> unit = TranscriptionUnit(rnapNum=1000,rnapEn=-5.0,genomeBg=5e6)

The creation of transcription unit needs to specify three essential parameters, and are explained below:
  • rnapNum: number of effective RNAP molecules
  • genomeBg: number of non-specific binding sites in the genome background
  • rnapEn: difference of RNAP binding energy at specific site and non-specific sites ().
At this first step, only RNA polymerase (RNAP) binding strength is characterized for the transcription unit. The basal gene transcription probability (in absence of regulators) can thus be calculated using baseBindingProb() method:

>>> unit.baseBindingProb()

The next step we will specify the configuration of regulation region of the transcription unit. As a simple example of combinatory regulation, suppose that the target gene is regulated by two activators independently, and there's one binding site for each activator. Binding site ``1'' is binded by regulator ``A'', and binding site ``2'' is binded by regulator ``B''.

To specify such configuration in tCal, first we have to add regulators to the transcription unit, using addRegulator() method:

>>> unit.addRegulator(name='A',rp_energy=-4)
>>> unit.addRegulator(name='B',rp_energy=-3.5)

Keyword arguments for addRegulator() method:
  • name: name of the regulator, should always be string
  • rp_energy: interaction energy of the regulator with RNAP ()
Negative indicates that the regulator is transcription activator, and possitive for repressor. And specify arbitrary number of regulator molecules using setRegMolNumber() method:

>>> unit.setRegMolNumber(name='A',number=100)
>>> unit.setRegMolNumber(name='B',number=200)

Keyword arguments for setRegMolNumber() method:
  • name: regulator name
  • number: number of molecules
Then add binding sites using addBindingSite() method:

>>> unit.addBindingSite(id=1,reg='A',dEnergy=-7)
>>> unit.addBindingSite(id=2,reg='B',dEnergy=-7)

Keyword arguments for addBindingSite() method:
  • id: integer id for binding site
  • reg: name of the binding regulator
  • dEnergy: difference of regulatory binding energy at this binding site and non-specific sites ()
Above settings are sufficient for calculation of transcription probability under regulation. Just call the bindingProb() method:

>>> unit.bindingProb()

We then get to another situation, in which the two binding sites has overlap, and this causes trouble for the co-binding event of the two regulators, as indicated by the figure below:

We now have two ways to describe this situation: either use positive interaction energy as proposed in my paper, or simply reject the binding event from happening.
To do it the first way, we shall use addInteractGroup() method to encode this ``hard'' interaction relationship (energies are chosen arbitrarily to reflect this situation):

>>> unit.addInteractGroup(names=(1,2),g_energy=10,gp_energy=10)

Keyword argument for addInteractGroup():
  • names: a tuple of binding site IDs, indicates the binding regulators at these sites will interact
  • g_energy: interaction energy of the regulators ()
  • gp_energy: interaction of the regulator group with RNAP ()
Now the transcription probability decreased a bit:

>>> unit.bindingProb()

Then we do it the second way. We can use addForbiddenEvent() method to denote this binding event is ``forbidden'', so to exclude it from computation.

>>> unit.addForbiddenEvent((1,2))

The argument is a tuple of binding site IDs. This way the co-binding event will be excluded from computation, and the transcription probability decreased a bit. Note that this result is very close to that obtained in the first way:

>>> unit.bindingProb()

Now let's get to the condition in which two activators work cooperatively to control target gene expression. This means that each one of the regulator could not fully activate gene expression individually, and only when two binds together could do so. This can be regarded as ``AND'' logical relationship.

Following shows the code to model this condition:

>>> unit = TranscriptionUnit(rnapNum=1000,rnapEn=-5.0,genomeBg=5000000)
>>> unit.addRegulator(name='A',rp_energy=-.5)
>>> unit.addRegulator(name='B',rp_energy=-.5)
>>> unit.addBindingSite(id=1,reg='A',dEnergy=-7)
>>> unit.addBindingSite(id=2,reg='B',dEnergy=-7)
>>> unit.addInteractGroup(names=(1,2),g_energy=-5,gp_energy=-5)

We first calculate the transcription probability in case of only activator A, you can see that this probability is low:

>>> unit.setRegMolNumber(name='A',number=300)
>>> unit.setRegMolNumber(name='B',number=0)
>>> unit.bindingProb()

Then we calculate the transcription probability when both activators are present. The probability rised to great extent:

>>> unit.setRegMolNumber(name='A',number=300)
>>> unit.setRegMolNumber(name='B',number=300)
>>> unit.bindingProb()

Export the probability formula:

>>> formula = unit.bindingProbFormula()
>>> formula

The formula can be used to compose RateRule instance governing rate-of-change of the transcription unit, using Python API of libsbml (shown in the demo program below).

[ Demonstration program ]
We provide an example Python program utilizing tCal to construct SBML models of gene regulatory network. To execute the program, please install the SBML progamming library libsbml with Python interface. You can refer to libSBML 3.1.1 Python API document page for full information.
You can put the program in your working directory and type following shell commands:

$ python

It will generates a file named ``testmodel.xml'' which contains the SBML model.


Page maintained by Xin Zhou (Email:
Created: June 23, 2008
Last modfied: Oct 4, 2008