                     Tracer v1.6 2003-2013
        		  MCMC Trace Analysis Package
                              by
        Andrew Rambaut, Alexei J. Drummond & Marc Suchard

              Institute of Evolutionary Biology
                    University of Edinburgh
                      a.rambaut@ed.ac.uk
                      
                Department of Computer Science
                     University of Auckland
                    alexei@cs.auckland.ac.nz

               David Geffen School of Medicine
            University of California, Los Angeles
                      msuchard@ucla.edu


UNIX / Mac OS X / Linux / Windows README 
a.rambaut@ed.ac.uk - 19 October 2013

Contents:
1) INTRODUCTION
2) INSTALLING AND RUNNING TRACER
3) LOADING TRACE FILES
4) ANALYSIS
5) VERSION HISTORY
6) SUPPORT & LINKS
7) ACKNOWLEDGMENTS

___________________________________________________________________________
1) INTRODUCTION

Tracer is a program for analysing the trace files generated by Bayesian MCMC runs (that is, the continuous parameter values sampled from the chain). It can be used to analyse runs of BEAST, MrBayes, LAMARC and possibly other MCMC programs.

BEAST - <http://beast.bio.ed.ac.uk/>

MrBayes - <http://morphbank.ebc.uu.se/mrbayes/>

LAMARC - <http://evolution.genetics.washington.edu/lamarc.html>

___________________________________________________________________________
2) INSTALLING AND RUNNING TRACER

Mac OS X: To install Tracer, simply drag the program file to where you normally put applications. Then double click to run.

Windows: To install Tracer, simply drag the folder to where you normally put applications. Then double click to run.

Linux / UNIX: Copy or move the folder to where you normally put applications and then double click the "lib/tracer.jar" file to run. You can either add the Tracer.v1.4 directory to your path or perhaps create symbolic links to the shell file 'tracer' within it in your '/usr/local/bin' or '~/bin' directories

___________________________________________________________________________
3) LOADING TRACE FILES

Once Tracer is running, select "Import" from the "File" menu to load trace files. You can load multiple trace files to compare or combine their results.

The input format is simply a tab-delimited text file where the first line
contains the column titles, the first column is the state number (or generation in the terminology of MrBayes) and each subsequent column is a continuous parameter sampled from the MCMC chain. 

___________________________________________________________________________
4) ANALYSIS

At present there is no detailed manual for this application, you will simply have to play around and see what happens. Basically you can select the trace file in the top left of the window, the individual parameter in the bottom left and the analysis appears on the right. 

There are 4 analysis tabs to choose from:

Estimates - this shows the mean, stdev, confidence intervals and other statistics about the selected parameter. A frequency distribution will also be plotted.

Density - this shows the Bayesian posterior density plot for the selected parameter.

Joint-Marginal - this only appears if exactly 2 parameters are choosen (hold down shift to select multiple parameters). It then plots one against the other to look at their joint-marginal distribution.

Trace - this shows the trace of the parameter against state or generation number. Use this to check mixing, choose a suitable burn-in and look for trends that might suggest problems with convergence.

Multiple parameters can be selected by holding down the shift key. This will overlay the plots for the different parameters allowing comparisons to be made. You can also select multiple trace files as well to compare different runs. If multiple trace files have the same trace names then a "Combined" trace will automatically appear. This can be selected as well as the individual trace files.

You can also select the "Demographic Analysis" from the Analysis menu - This plots the distribution of demographic population sizes over time for a number of models (constant size, exponential growth & logistic growth) that are available in BEAST. This involves you selecting the traces for each parameter of the model. You should only select the model that was actually run under BEAST (e.g., if you ran an exponential growth model, you shouldn't plot the constant population size model).

The "Analysis" menu also contains options for performing Bayesian Skyline reconstructions and for calculating Bayes Factors between runs.

The "Print" function in the "File" menu will print the current graph or table and the "Export Data" function can be used to export the data from the plots for use in another graphic package.

To export the currently displayed graphic use the "Export PDF" function in the "File" menu.

___________________________________________________________________________
5) VERSION HISTORY

---Version 1.6 20 Oct 2013---

* Multilocus 'Skygrid' analysis option - use this option when analysing BEAST output generated under this model.

* Density plots are now drawn as kernal density estimates instead of histograms.

* Traces can be designated as integer or categorical with appropriate plots and statistics given.

---Version 1.5 30 Nov 2009---

* Can now import log files by dragging them into the left hand side of the window.

* GMRF 'Skyride' analysis option - use this option when analysing BEAST output generated under this model (Minin, Bloomquist & Suchard, 2008, Mol Biol Evol 25:1459-71).

* Burnins are shown on trace plots (in a paler colour).

* The ESSs of 'Combined Traces' are now calculated explicitly rather than just summing the individual ESSs. This shows cases where individual traces are sampling different distributions. 

* Fixed bug when selecting 'Combined Trace' on its own. A checkbox is available for hiding these.

* By default the trace panel shows the complete trace rather than a sub-sample.

* Fixed issues when columns had the same name - a suffix is now appended.

---Version 1.4.1 29 Nov 2008---

* Multiple trace files can now be selected in the Import dialog box.

* When selecting multiple trace files, the common set of traces are displayed (even if they are in a different order - as long as they are named the same) to make model comparisons easier.

* Numerous bug fixes

---Version 1.4 11 Oct 2007---

* This is almost a complete rewrite of the code so it is difficult to list the changes.

---Version 1.3 29 Sept 2005---

* Fixes crashes when the wrong model is selected in Bayesian Skyline reconstruction.

* Fixes crashes when solid intervals is chosen with zero values.

* More reliably reveals statistics table when a log file is loaded.

* Keeps log likelihood values in non-scientific format.

* Can copy and paste from all tabs and windows.

* Can export raw numerical data as text file.

---Version 1.2.1 24 Feb 2005---

* Added +/- buttons below the trace table so that traces can be removed from the table.

* Fixes a problem with analysing linear Bayesian skyline plots.

---Version 1.2 29 Oct 2004---

* Now analyses the new Bayesian Skyline Plot.

* More demographic model analyses.

* Keeps a menu available on the mac even when all the windows have been closed.

* Fixes a problem with the reporting of erroneous mean parameter values when multiple traces were combined after changing from default burn-in sizes.

---Version 1.1.1 17 Sep 2004---

* Can now use the "New" command in the "File" menu to create a new Tracer
window.

---Version 1.1 24 May 2004---

* Added a new Analysis menu that has a single item: Demographic Analysis.

* Added a plot in the Estimates tab when multiple statistic traces are selected. It now shows a series of range bars for the HPD allowing comparison of related statistics.

* Can optionally draw every point in the Trace plot or only a sample if the file is large.

* Can now select multiple traces when multiple trace files are combined.

* Improved legend display for plotting densities of multiple combined trace files.

---Version 1.0.1 22 Sep 2003---

* Fixed problem with analysis thread using up way too much CPU time. 	This was more noticable on Windows machines.
 
* Fixed problem with the program hanging when a parameter trace contained only one value over its entire length (mainly discrete parameters).

* Added a progress window that pops up when loading large files.

* Switched to native look-and-feel on Windows.

---Version 1.0 28 Aug 2003---

* First released verson

___________________________________________________________________________
6) SUPPORT & LINKS

<a.rambaut@ed.ac.uk>
<alexei@cs.auckland.ac.nz>
<msuchard@ucla.edu>

We would encourage you to join the BEAST users' mailing-list to get
notifications of updates and bugs. At a later date this may be expanded to
be a discussion-list so that users can exchange ideas and help. You can
join the mailing list here:

<http://groups.google.com/group/beast-users>

The website for BEAST (and Tracer) is here:

<http://beast.bio.ed.ac.uk/>

Source code distributed under the GNU Lesser General Public License:

<http://code.google.com/p/beast-mcmc/>

___________________________________________________________________________
8) ACKNOWLEDGMENTS

Thanks to the following for supplying code or assisting with the creation
of Tracer:

	Joseph Heled
	Oliver Pybus
	Benjamin Redelings
