RootAnnotator Files

README ROOT ANNOTATOR 
==========================

authors: Jakob Schulze, Franziska Zickmann
March 2013
Robert Koch-Institute
Berlin, Germany

All rights reserved. In case of questions please contact zickmannf@rki.de.

When using RootAnnotator, please cite the following manuscript: (in submission).

____________________________________________________________________________________________________________________________
````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````

RootAnnotator counts the roots of the trees from a .nexus file and computes the probability to be the root for each branch.
It can annotate these probabilities on different types of summary trees. Further, it can create a file for Tracer* to 
visualize the convergence of the roots.

____________________________________________________________________________________________________________________________
````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````

INSTALLATION

An installed version of java (minimum version 1.6.0; available from http://www.java.com/; already installed on most computers) is required to 
use RootAnnotator with the help of a graphical user interface (GUI). All other required dependecies are in the "dependencies" 
folder that can be downloaded together with the RootAnnotator program from www.XXXX.com.
RootAnnotator is already precompiled, hence to run the program just click on the RootAnnotator.jar file. 
If you are using the command line, you only need the program rootannotator.py. The executable required for your system can be
found in the dependencies folder. Move to this folder or include the program somewhere in your path. Then type:

> ./rootAnnotator --help

If you want to compile RootAnnotator from source, please follow the instructions in the INSTALL file.

____________________________________________________________________________________________________________________________
````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````

INPUT

RootAnnotator at minimum requires a tree sample in .nexus format to compute the root probabilities. 
An overview of the different options of the RootAnnotator GUI is presented in the following.

Note that command line users can obtain the parameter descriptions by typing: 

> ./rootAnnotator --help

==========================

ANALYSIS PANEL

- Analysis Name Tag : assign a name to the current analysis, all output files will start with this name

- Output Directory : specify the directory of the output

- User Tree : provide a tree in nexus or newick format that will be annotated with the root probabilities computed for the 
              tree sample. Note that the taxa of the user tree must also occur in the sample trees.

- Tree Sample 1 : the input sample of trees in nexus format

- Burnin 1 : specify the number of trees that are not regarded in the analysis (DEFAULT: 0)

- Tree Sample 2 (optional) : provide a second sample of trees, useful for convergence analyses

- Burnin 2 (optional) : if Tree Sample 2 is set, specify the number of trees that are not regarded in the second analysis

- Run : perform the root probability computation

==========================

SETTINGS PANEL

- Create MCC tree : check this box if you want to create an MCC tree using TreeAnnotator**. A precompiled version of
		    TreeAnnotator is provided in the dependencies folder (path only required if RootAnnotator is called 
		    via the command line) 

- Create visualization tree : the visualization tree is picked from a selection of the input tree sample. This selection 
                              can consist of all trees whose roots have a certain cumulative probability sum (threshold). 
                              In this case, the exhaustive search guarantees an optimal selection by testing all possible 
                              combinations of roots. However, since this is time consuming it is recommended to use a 
                              faster heuristic search that returns a suboptimal selection which is guaranteed to meet the 
                              threshold. Alternatively, the selection can be performed by including a user-defined list of 
                              roots. 

- Cumulative root probability threshold : parameter to create the visualization tree, threshold for the cumulative 
                                          probability sum

- Use exhaustive search : parameter to create the visualization tree, check this box to perform the time consuming 
                          exhaustive search

- List of roots to be included : parameter to create the visualization tree, provide a comma separated list of roots 
                                 that should be included in the selected trees

- Create file containing selected trees : check this box if you want to obtain a file with the trees selected for the 
                                          visualization tree computation

- Create .csv file : obtain a .csv file that lists all roots and their probabilities in a table

- Analyze convergence : generate a file for Tracer* that shows the convergence of the roots. In case of two input tree 
                        samples, two separate convergence files are generated. The convergence is computed with the help 
                        of a sliding window over the tree sample that is applied step-wise and leads to the computation 
                        of a distribution of found roots.

- Sliding window : parameter for the convergence analysis, size of the sliding window

- Step size : parameter for the convergence analysis, step size

- Save log : save the log file of the current analysis


You also have the possibility to save the current settings and the current console output via the menu (Console, Form Entries).

____________________________________________________________________________________________________________________________
````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````

* available from http://tree.bio.ed.ac.uk/software/tracer/
** see http://beast.bio.ed.ac.uk/TreeAnnotator