StableTraits

Software for fitting stable models of character evolution to continuous traits evolving on phylogenetic trees.

The model

The model is described in the paper. If you want, you can also download the simulated data referenced in the paper, and the data used in the mammal body mass reconstruction.

The software

There are two programs. The first is stabletraits, which fits a stable model to a phylogeny and some data using markov chain monte carlo methods. The second is stabletraitssum, which summarizes output of the first program. Both are command line programs.

Platform File
Source code stabletraits_1.5_src.zip
Linux binaries stabletraits_1.5_linux.zip
Windows binaries stabletraits_1.5_win.zip
Mac binaries stabletraits_1.5_osx.zip

StableTraits

To run the program you will need a phylogenetic tree and some input data, typically values of a continuous character such as body mass for species at the tips of the phylogeny. The tree should be stored in newick format in a file containing nothing other than the newick string. The character data should be stored in a tab separated file in which each row provides the data for a single taxon. The first column of this file contains the taxon name, which should match the name in the phylogeny perfectly. The second column contains the trait value.

StableTraits takes a number of command line options, the details of which are obtained by typing:

./stabletraits --help

A minimal model fit needs the location of the tree and data file, along with the base path for output files:

./stabletraits --tree mytree.tre --data mydata.txt --output myoutput

Other useful command options include --iterations which determines the number of steps in the Markov chain (by default, 1000000), and --skip which determines the thinning rate. A thinning rate of 200 (the default) means that every 200th step will be recorded to file. You can use the option --chains to specify the number of independent Markov chains (by default, two). On the multithreaded version of the software, each chain will run on a separate processing core in a parallel fashion. You can set the prior on evolutionary rate using --igamma_shape and --igamma_scale but these have reasonable default values which prevent rates approaching zero. You can force StableTraits to fit a Brownian motion model (for model selection purposes) using the flag --brownian, which constrains the index of stability to equal 2. If you also wish to constrain the rate of evolution to the maximum likelihood value you can use --brownianstrict.

The software will output a number of files. Assuming the option --output myoutput was used, the following files will be generated:

File Description
myoutput.chainx.log x is an integer ranging from one to the total number of chains. These files contain parameter estimates from the Markov chains.
myoutput.fixed_taxa Contains a list of taxon names and trait values that are invariable (i.e. fixed from your input).
myoutput.tree Contains the input phylogeny in which all nodes have been given a label if not labelled in the input tree.
myoutput.prior Specifies the prior parameters used.
myoutput.progress Reports DIC and PRSF diagnostics calculated during the run. These diagnostics are also printed to screen during operation of the program and are discussed below.

During operation, the program will perform Markov chain steps in a set of (by default 40) stages. If the run has 1,000,000 iterations, there will by default be 40 stages of 25,000 iterations each. At the end of each stage, PBIC, DIC and PRSF diagnostics will be calculated on the basis of the last half of all completed iterations so far (i.e. assuming a burnin of 50%). Should PRSF (the proportional scale reduction factor as defined by Brooks and Gelman 1998) approach 1 (i.e. PRSF < approximately 1.1) it is an indication that the chains have converged on a solution. You may wish to note the number of generations at which PRSF first gets close to one in order to set an appropriate burnin period during later analyses. DIC is the deviance information criterion and can be used as a model selection criterion in a manner analogous to AIC in maximum likelihood studies (lower DIC implies better model fit). PBIC is similar to DIC but with an extra penalty on the number of parameters, and our simulation studies show that it works better than DIC, so you should use PBIC for model selection.

StableTraitsSum

This program summarises the output from StableTraits. You must provide a --path command line option identical to that used in the --output option for stabletraits. The program will search this path for the output files:

./stabletraitssum --path myoutput

You may also specify --from and --to options which are the numbers in generations of the samples for which you would like summaries. To obtain an estimate discarding the first 200,000 generations you would use --from 200000. To obtain an estimate using the samples from generation 200,000 to 400,000 you would use --from 200000 --to 400000. The program calculates median estimates of model parameters including ancestral states, along with a 95% credible interval. If you specify the --brownian flag, the program uses a hill climbing algorithm to find branch lengths which would give rise to the median stable ancestral state reconstruction under a Brownian motion model. This scaled tree may be used for further analyses which assume a Brownian motion model of evolution, such as PGLS or independent contrasts, while incorporating information from the stable model fit. Please take account of the absolute error of the Brownian reconstruction relative to the stable distribution during the program run - some stable reconstructions are simply incompatible with a Brownian model. Termination of the hill climbing algorithm occurs when the reduction in difference between Brownian motion reconstruction and stable reconstruction across the tree as a whole is less than some limit (--hillclimblimit) for a fixed number of iterations (--iterlimit). The program will output a number of summaries:

File Description
myoutput.ancstates The median estimates of ancestral states and stable parameters along with the 95% credible interval.
myoutput.rates_tree A copy of the original tree with branch lengths set to the evolutionary rate imputed by the stable reconstruction. Specifically, each branch length is equal to the absolute difference in the stable reconstruction occurring on that branch divided by the square root of the input branch length.
myoutput.scaled_tree Only if you specified --brownian. A copy of the original tree with branch lengths set such that the Brownian motion reconstruction of the character on this tree is approximately the same as the stable ancestral reconstruction. This can be understood is incorporating departures from neutrality into the branch lengths such that the scaled tree can be used for further analyses which depend on Brownian assumptions (such as independent contrasts). In the scaled tree, relatively large branch lengths imply relatively high rates of evolutionary change.
myoutput.brlens The original branch lengths, evolutionary rates, node height and (optionally) scaled branch lengths in tabulated format so you can import into a spreadsheet and identify branches of interest if you are so inclined.

Compilation instructions

Windows and Visual Studio

  • Install Visual Studio
  • Install boost
  • Install CMake (select the option to add binaries to your PATH)
  • Unpack the source
  • Edit the following line in CMakeLists.txt so that the path matches the root location of your boost installation: set(BOOST_ROOT "C:/boost_1_62_0")
  • In a visual studio command prompt, enter the unpacked directory and run:
    • cmake . -G "NMake Makefiles"
    • nmake
  • Tested successfully on Windows 10 Professional with Visual Studio Community 2015

Linux and GCC

  • Install build essentials from your package repository
  • Install boost development files from your package repository
  • Install CMake from your package repository
  • Unpack the source
  • In a terminal window, enter the unpacked directory and run:
    • cmake .
    • make
  • Tested successfully on Ubuntu 16.10 “Yakkety”

Mac OSX and XCode

  • Install XCode (or upgrade to the latest version)
  • Install Homebrew
  • In a terminal window, run:
    • brew install gcc --without-multilib
    • brew install boost
    • brew install cmake
  • Unpack the source
  • In a terminal window, enter the unpacked directory and run:
    • cmake -DCMAKE_CXX_COMPILER=g++-6 CMakeLists.txt (the compiler number should match your homebrew-installed version)
    • make
  • Tested successfully on El Capitan
comments powered by Disqus