The DOT Test

D.D. Ackerly and C.O. Webb
August 2005
dackerly@berkeley.edu
cwebb@oeb.harvard.edu

The scripts below will run the DOT test, as described in the publication above. Please read the paper before conducting the test! These scripts were developed on Mac OS X, in the unix environment, and require that the user have R and awk installed (R can be run as a GUI or unix installation). The R libraries 'ape' and 'msm' are required. The scripts also require a command line version of ancml, written by Schluter et al. (1997). The OS X executable and source code for ancml should be downloaded at: http://www.phylodiversity.net/cwebb/software/ancml-OSX.zip. Original source code can be obtained at: http://www.zoology.ubc.ca/~schluter/ancml.html.

Instructions:
1) Install the following files into a folder. Experienced users may want to install these in a default path, but editing of several lines in dot.R and trancml is required, as files are expected to be in the current directory.

	ancml (see above)
	trancml
	picfixed.R
	dot.R

2) Insure that trancml is executable (and that the first line points to your awk executable):

	% chmod u+x trancml
	
3) Prepare input files (see documentation for phylocom for more information on these file formats: www.phylodiversity.net/phylocom). Files must be named 'phylo' and 'traits'. The example files provided correspond to the case shown in the Figure for Appendix A.

A) 'phylo': phylogeny as a nexus string on one line, with a unix line-ending; no header material should be included. Positive branch lengths can be present, and if no branch lengths are available all branch lengths should be set to 1. If your phylogeny has any zero length branches, ancml will run but it will  generate extremely high standard errors for ancestral states due to fitting a high beta parameter to accommodate phenotypic change on zero length branches. The alternative randomization methods using Felsenstein's (1985) contrast method will not run, as this algorithm chokes on zero length branches.

B) 'traits': trait data in following form ('\t' indicate a tab, Ô\nÕ a unix newline). Be sure that there is a line ending on the final line of data. Taxon names must be <30 characters and have no spaces.

	Line 1: "type\t3\t3\n"
	Line 2: (optional): "name\tTraitXName\tTraitYName\n"
	Line 3 and following: "taxon1Name\tvalue1\value2\n"
	
	For example:
	type	3	3
	name	logSLA	JanMin
	Ceanothus_arboreus	0.949	6.07
	Ceanothus_cordulatus	1.351	-4.06
	....
	

4) Open dot.R in an editor (emacs, vi, pico, BBedit...) and set two run-time variables at top of file:

BATCH: = 0 for basic screen output of results; = 1 for more extensive file 		output, which is useful for importing results of multiple runs into spreadsheet.

Nreps: Number of reps for randomization and bootstrapping. We recommend at least 200 to allow direct calculation of one- or two-tailed significance tests. 

5a) To run from within R: Open R (GUI or unix version), and run:

	> source('dot.R', echo=T, print.eval=T)

5b) To run from command line: 

	% R CMD BATCH dot.R R.out

6) In the background, the trancml script will generate 'dot.in', which compiles results of ancml analysis for both traits. This file can be opened in a spreadsheet to see ancestral states and standard errors for both traits, along with node ages and other information.
	
7) Output: The BATCH=1 option will generate 22 output variables (last 9 are omitted if zero length branches are present). In screen output mode (BATCH=0), the twelve variables marked with asterisks are shown.

Nreps: Number of bootstrap and randomization replicates

Wx.as: Mean node age for trait X, calculated directly from ancestral states

Wy.as: Same for trait Y

D.as: Age difference (Wx.as-Wy.as)

*Wx.bs: Mean node age for trait X, averaged across all bootstrap reps

*Wx.sd: Standard deviation of node age for X, across the bootstrap reps

*Wy.bs: Same for trait Y

*Wy.sd: Standard deviation of node age for X, across the bootstrap reps

*D.bs: Mean age difference between traits, averaged across all bootstrap reps (Wx.bs-Wy.bs)

*D.sd: Standard deviation of the difference in node age, averaged across all bootstrap reps

*P.bs: Significance of one-tailed test that D.bs > 0. For D < 0, p = 1-P.bs. For two-tailed test, take lesser of P.bs and (1-P.bs) and divide by 2.

betaX, betaY: Brownian motion rate parameters calculated by ancml for each trait

*Wx.pic: Mean node age for trait X, calculated from Felsenstein's independent contrast algorithm

*Wy.pic: Same for trait Y

*D.pic: Difference in node age, based on Felsenstein contrasts

*P.tips: Significance of one-tailed test that D.pic > 0, based on randomization of tip values (see above for D.pic < 0 and two-tailed tests)

*P.contrasts: Significance of one-tailed test that D.pic > 0, based on randomization of contrasts across nodes (see above for D.pic < 0 and two-tailed tests)

BMtestX, BMtestY: Correlation of the absolute value of standardized independent contrasts for trait X with the standard deviation of the contrast (square root of subtending branch lengths). This should not be significantly differen from zero (see Garland et al. 1992)

NormTestX, NormTestY: Correlation coefficient for truncated normal probability plot of standardized contrasts of traits X and Y. If trait fits Brownian motion model, the absolute value of the contrasts should exhibit a truncated normal distribution. The normal probability plot would then be a straight line, and this correlation should be close to 1. If it is much lower than 1, the plot should be examined graphically to determine the departures from normality. After running dot.R, this can be done in R with the command: plot(qtnorm(qq,lower=0),sort(abs(Fx[,1]))) (substitute Fy for trait Y).

References
Felsenstein, J. 1985. Phylogenies and the comparative method. Amer. Nat. 125:1-15.
Garland, T., Jr., P. H. Harvey, and A. R. Ives. 1992. Procedures for the analysis of comparative data using phylogenetically independent contrasts. Syst. Biol. 41:18-32.
Schluter, D., T. Price, A. Mooers, and D. Ludwig. 1997. Likelihood of ancestor states in adaptive radiation. Evolution 51:1699-1711.