TREEKIN
NAME
treekin − Calculate a macrostate dynamics of biopolymers
SYNTAX
treekin [options] < foo.bar
DESCRIPTION
treekin
computes a reduced dynamics of biopolymer folding by means
of numeric integration of a Markov process that generally
operates at the level of macrostates, i.e. basins of
attraction of the underlying energy landscape.
treekin expects a .bar file via stdin, and optionally a
rates file in the current working directory. Both the .bar
file and the rates file (default name is rates.out)
can be obtained from barriers. In case of -m I option
(default) the program needs just the rate file provided as
standard input.
OPTIONS
−h, −−help
Print help and exit
−V, −−version
Print version and exit
−a, −−absorb=state
Make a state absorbing
−m, −−method=STRING
Select method to build transition matrix: A ==> Arrhenius−like kinetics F ==> Full process kinetics (whole subopt) I ==> use input as a rate matrix (possible values="A", "F", "I" default=‘I’)
−−num−err=STRING
Method how to deal wih numerical errors in probability: I ==> Ignore H ==> Halt the program R ==> Rescale the probability (possible values="I", "H", "R" default=‘H’)
−−t0=time
Start time (default=‘0.1’)
−−t8=time
Stop time (default=‘1E12’)
−T, −−Temp=DOUBLE
Temperature in Celsius (default=‘37.0’)
−n, −−nstates=INT
Read only first <int> states (assume quasi−stationary distribution (derivation of others is = 0))
−−p0=STRING
Set initial population of state <int> to <double> Can be given multiple times (NOTE: sum of <double> must equal 1) (example: "−−p0 2=1.0" − state 2 has initial population 100 percent)
−−tinc=DOUBLE
Time scaling factor (for log time−scale) (default=‘1.02’)
−d, −−degeneracy
Consider degeneracy in transition rates (default=off)
−e, −−exponent
Use matrix−expontent routines, NO diagonalization (default=off)
−u, −−umatrix
Dump transition matrix U to a file mx.txt (and to binary mx.bin − not fixed yet) (default=off)
−x, −−mathematicamatrix
Dump transition matrix U to Mathematica−readable file mxMat.txt (default=off)
−b, −−bin
Assume binary rates input (default=off)
−t, −−fpt=STRING
Calculate first passage times "all" − calculate all fpt’s(slow) <num> − calculate fpt’s to state <num> from all states
−r, −−recover
Recover from pre−calculated Eigenvalues and Eigenvectors (default=off)
−w, −−wrecover
Write recovery file containing Eigenvalues and Eigenvectors (default=off)
−−info |
Show settings (default=off) |
−f, −−ratesfile=STRING
Name of the textfile containing the (barriers) rate matrix (NOTE: the rate matrix must have been print out with ’%10.4g’ per entry otherwise treekin will calculate crap) In case of −m I option (default), this is read from the standard input.
−v, −−verbose
Verbose output (default=off)
−q, −−quiet
Be silent (do not print out the output) (default=off)
−−fptfile=STRING
File where to write first passage times (meaningfull only with −t option)
−−visualize=STRING
Filename where to print a visualization of rate graph (without file subscript, two files will be generated: .dot and .eps with text and visual representation of graph)
−−just−shorten
Do not diagonalize and iterate, just shorten input (meaningfull only with −n X option or −fpt option or −−visualize option) (default=off)
−−max−decrease=INT
Maximal decrease in dimension in one step (default=‘1000000’)
−−feps=DOUBLE
Machine precision used by LAPACK routines (and matrix aritmetic) −− if set to negative number, the lapack suggested value is used (2*DLAMCH("S") ) (default=‘1E−15’)
−−useplusI
Use old treekin computation where we add identity matrix to transition matrix. Sometimes less precise (maybe sometimes also more precise), in normal case it should not affect results at all. (default=off)
−−minimal−rate=DOUBLE
Rescale all rates to be higher than the minimal rate using formula "rate −> rate^(ln(desired_minimal_rate)/ln(minimal_rate))", where desired_minimal_rate is from input, minimal_rate is the lowest from all rates in rate matrix.
−−hard−rescale=DOUBLE
Rescale all rates by a hard exponent (usually 0.0<HR<1.0). Formula: "rate −> rate^(hard−rescale)". Overrides −−minimal−rate argument.
−−equil−file=STRING
Write equilibrium distribution into a file.
−−times=DOUBLE
Multiply rates with a constant number.
−−warnings
Turn all the warnings about underflow on. (default=off)
EXAMPLES
Typically, computation of a reduced dynamics based on the analysis of folding landscapes requires two steps: Elucidation of the landscape (topology) and − based on that − calculation of the reduced dynamics.
The first step involves computing the relevant properties of an energy landscape by barriers (see barriers(1) for details). The resulting .bar−file contains information on local minima, basins, saddle points as well as thermodynamic properties of the energy landscape. Additionally, the −−rates option in the below example triggers barriers to generate another output file (rates.out) containing the transition rates between all pairs of macrostates (ie. basins of attraction), calculated by summing over the corresponding microscopic rates.
barriers −−saddle −−bsize −−rates < foo.sub > foo.bar
In a second step, treekin is called with options to calculate the macrostate dynamics on the previously generated landscape by means of applying microscopic transition rates (option −m I):
treekin −−p0 2=1 < rates.out
In this example, the simulation starts with 100% of the initial population in macrostate 2, i.e. the second lowest minimum in the barrier tree (option −−p0 2=1). The transition matrix is computed from a set of microscopic rates, read from a rates file (as computed by barriers).
Generally, calculation of the macrostate dynamics by means of microscopic rates (option −m I) is consiberably more accurate than the simplified Arrhenius−like dynamics (option −m A).
Looking at the default output produced by treekin, there are two sections: Overall status information on the computation (marked by hash signs at the beginning of the line) are printed at the top. Below, the actual data is printed for each time step in (n+1) space−separated columns, where n is the number of investigated (macro)states. The first column lists the current time, whereas all remaining columns correspond to the population probabilities of individual (macro)states.
REFERENCES
If you use this program in your work you might want to cite the following original papers:
M.T. Wolfinger,
W.A. Svrcek−Seiler, Ch. Flamm, I.L. Hofacker, P.F.
Stadler
Efficient computation of RNA folding dynamics
J.Phys.A: Math.Gen. 37: 4731−4741 (2004)
I.L. Hofacker,
Ch. Flamm, Ch. Heine, M.T. Wolfinger, G. Scheuermann, P.F.
Stadler
BarMap: RNA folding on dynamic energy landscapes
RNA: 2010 16: 1308−1316 (2010)
AUTHORS
Michael T.
Wolfinger, Marcel Kucharik, Ivo Hofacker, Christoph Flamm,
Andreas Svrcek−Sailer, Peter Stadler.
Send comments to <ivo@tbi.univie.ac.at>
SEE ALSO
barriers(1)