McQFold is a program for MCMC-sampling secondary structures with pseudoknots
for a given RNA sequence. It is freely available under the terms of the
GNU General Public License, read the file LICENSE for details. This program 
is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; 
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 
PARTICULAR PURPOSE.

If you use McQFold for scientific work please read and cite

D. Metzler, M. Nebel (2006) "Predicting RNA Secondary Structures with Pseudoknots
by MCMC Sampling". preprint

The complete reference will be given on the authors' web-pages and on the
homepage of McQFold when the article will be accepted for publication.


INSTALLATION

The following instructions explain how to compile the McQFold under GNU/Linux. The
program is written in C++. It might also be installable under other operating systems.

After unzipping the file "McQFold.tgz" with the command "tar xvzf McQFold.tgz"
you will find a directory "McQFold". Enter it with "cd McQFold" and run the command
"make". This will generate an executable file "McQFold", which you can copy into a
directory in which your operating system looks for executables. (Depending on your
PATH variable this might be "~/bin" or "~/usr/bin".) You may increase the execution 
speed of the program by adapting the compiler options in the file "Makefile" to 
your hardware before running "make".


RUNNING THE PROGRAM

Make sure that the current working directory contains a file "input_sequence" with 
the sequence to analysed. The sequence must consist of the letters a,c,g,t,u,A,C,G,T,U 
in one line. It must NOT contain any blanks, gap-symbols, wild-cards, line-breaks or thelike.

The working directory must also contain a file "model_probs" with the transition and
emission probabilities of our grammar (cf. D. Metzler, M. Nebel, 2006). You obtain an
example for "model_probs" with the source code of the program. You may change the nubers
in this example file, but neither the grammar rules nor the order in which they appear in
the file. For example "StoaxFyb 0.009" means that the probability that S is changed into
"axFyb" is 0.009, "au  0.35" means that 0.35 is the probability that a pair "a-u" or "u-a" 
is emitted from the (a,b) or (x,y) pair in  "axFyb", the 0.2 in "c  0.2" is the probability
that the x in "Ltox  0.9" emits a "c", and "q  0.75" controls the lengths of q-stems in the 
same way as "FtoxFy   0.75" controls the lengths of regular stems.

Start the with "McQFold" or "<name of the directory where it is installed>/McQFold".
McQFold will use the system time as seed for the random generator. If you want McQFold
to use any other number as seed, you can assign it to McQFold as a command-line argument.


OUTPUT FILES

McQFold will generate four output files named "output_samples", "output_folding", 
"output_pairprobs", and "logfile".

"output_samples" contains 20 possible structures, sampled according to their
posterior probability for the given sequence.

"output_folding" contains the structure that was found by the simulated annealing 
procedure, which searches for the most probable structure for the given sequence.

"output_pairprobs" contains n*n numbers, where n is the sequence length. The 
[k+m*(n-1)]-th entry (where k<n) is the estimated probability that positions k
and m are paired. (Yes, for simplicity there is some redundancy in this file!)
For each of 20 q-stem-configurations (which are used to sample the 20 structures
in "output_samples") the pairing probability for each pair of positions is computed by
the inside-outside algorithm. The values in "output_pairprobs" are the averages of
these probabilities.

"logfile" contains several values which helpful to examine the convergence of
the mcmc and simulated annealing procedures. The first two numbers in each line
are the log-probability of the current state and the current number of q-stems
during the run of the program. The meaning of the other numbers become obvious
when carefully reading the source code of McQFold.


BUG REPORTS

Please report all bugs in McQFold to the developer of the program: 

Dirk Metzler
metzler@cs.uni-frankfurt.de 
www.cs.uni-frankfurt.de/~metzler

Last modified: May 30, 2006