-----------------
RATO, version 1.3
-----------------

# Copyright (C) 2005 by Torsten Eriksson and Frank Rutschmann.
# This program is distributed by Frank Rutschmann (http://www.plant.ch).
# If you have any questions, don't hesitate to contact me: frank@plant.ch.


RATO is a Perl utility to extract a ratogram from the main multidivtime
output file. Additionally, it calculates the average rate of all branches
and writes it together with the ratogram into a NEXUS treefile. Such a file
can be read by programs like PAUP* or TreeView, from where the ratogram can
be printed.

Since version 1.2, RATO is able to extract the rates from multiple
genes. In such a case, multiple ratograms (one per gene) will be written to
the output file. Additionally, RATO calculates the average rate for each
branch across all genes, and adds an "averaged ratogram" to the output file.
This final ratogram contains therefore rates averaged over all genes.

RATO requires an installed Perl distribution on your computer.
You can download Perl for free as a source code or as a pre-compiled binary
distribution at http://www.perl.com/download.csp.


Usage:

a) Install the Perl distribution, including the definition of a PATH variable
   (which tells the operating system where the Perl executable is located).
   
b) Copy the file rato.pl into any directory.

c) Open a terminal window, change to that directory, and enter the following
   command:

   Windows:
   perl rato.pl name_of_the_multidivtime_output_file

   Linux / Mac OS X:
   ./rato.pl name_of_the_multidivtime_output_file

   The name_of_the_multidivtime_output_file is usually out.*, where the *
   represents a name you gave when you started the multidivtime analysis.

d) If everything works fine, the program reports for every gene the ratogram,
   the number of branches and the average rate of all branches of the tree.
   Additionally, it writes the ratogram into the output file ratogram.*.tre.
   Finally, RATO reports the above data also for the "averaged ratogram"
   (with rates averaged over all genes) and adds the ratogram to the output file.

e) Open the file ratogram.*.tre with TreeView or PAUP* and print the ratogram.


NOTE:
If you used 10 million year units for defining the rttm prior in
multicntrl.dat (see FAQ 4 in the Bayesian dating step-by-step manual),
don't forget to divide the rates in the chronogram by 10 to get the
usual rate units of substitutions/site/mys.
