BAli-Phy should be able to run on any hardware with a modern operating system, including Linux or UNIX, Windows, and Mac OS X.

We recommend at least 512Mb of RAM and a 1.5GHz processor. We typically run BAli-Phy on Pentium 4 processors with 1Gb of RAM and a 3 GHz processor.

In order to compile the program on UNIX, first extract the source code archive, using a graphical archive manager, or the command-line tool tar:

% tar -zxf bali-phy-2.0.2.tar.gz

Then create a separate build directory, enter it, and run the configure command:

% mkdir build
% cd build
% ../bali-phy-2.0.2/configure

If this command succeeds, then you can simply type

% make
% make install

to build and install bali-phy and its associated tools. (This requires GNU make.) To customize the compilation and installation process, read the following sections on supplying arguments to the configure script.

The configure script chooses to install bali-phy in the directory /usr/local/ by default. We can install binaries to another directory dir by passing --prefix=dir. For example, in order to install BAli-Phy under ~/local, you can do:

% ../bali-phy-2.0.2/configure --prefix=$HOME/local

This is recommended if you do not have permission to install to /usr/local/.

You can instruct the compiler to look for include files in directory dir by passing --with-extra-includes=dir to the configure script.

You can instruct the compiler to look for libraries files in directory dir by passing --with-extra-libs=dir to the configure script.

For example, if your system has GSL installed in /usr/local/, then you might need to add "--with-extra-includes=/usr/local/include --with-extra-libs=/usr/local/lib" to the configure script arguments so that the compiler can find the GSL include files and libraries.

The default C++ compiler is g++. On some systems, g++ invokes GCC version 3.3, and the correct compiler is called something else, such as g++-4.0. To use g++-4.0 as the C++ compiler when compiling BAli-Phy, you would set the CXX environment variable as follows:

% ../bali-phy-2.0.2/configure CXX=g++-4.0

Alternatively, on Macintosh systems, you can run the command gcc_select 4.0 to choose the correct compiler.

You can specify optimizing for a specific brand of CPU, by specifying the CHIP variable to configure, as follows:

% ../bali-phy-2.0.2/configure CHIP=cpu

You can set CHIP to any of pentium3, pentium4, nocona, G3, G4, or G5.

Call configure with the flag --enable-static to build static executables. Static executables will be able to run on other computers with the with the same type of CPU but slightly different versions of the operating system.

This step is only necessary if you are using the subversion (SVN) source. It is not necessary if you are compiling from a distributed tar.gz archive of the source, because these archives already include the files that this step will generate, such as the configure script and some Makefiles.

To generate these files, you need automake 1.8 or higher and autoconf 2.59 or higher. Run these commands inside the trunk/ directory that you checked out.

% autoheader
% aclocal
% automake -a
% autoconf

If your system has multiple versions of automake, then you may have to type e.g. automake-1.8 -a and aclocal-1.8 instead in order to specify which version to use.

All these options to configure can be combined, as follows:

% ../bali-phy-2.0.2/configure --prefix=$HOME/local --enable-static CXX=g++-4.1 CHIP=pentium4

This example uses g++-4.1 to build a pentium4-optimized version of bali-phy with static linkage.

After compiling BAli-Phy, you can simply type make install. This will copy the compiled binaries to the directory chosen when you ran configure.

To install pre-compiled binaries, simply extract the compressed archive in the directory of your choice. If you have root access you might extract in /usr/local; if not, you might make a directory ~/local in your home directory and extract there.

You can extract the compressed archive on the command line using the tar command:

% tar -zxf bali-phy-version.tgz

If you installed BAli-Phy to the directory /usr/local/, then you can run bali-phy by typing /usr/local/bin/bali-phy. However, it would be much nicer to simply type bali-phy and let the computer find the executable for you. This can be achieved by putting the directory that contains the bali-phy executables into your "path". (The directory that contains the executables will be /usr/local/bin if you extracted the bali-phy archive to the directory /usr/local, but will be somewhere else if you extracted the bali-phy archive somewhere else.)

The "path" is a colon-separated list of directories that is searched to find program names that you type. It is stored in a variable called PATH. You can examine it the current value of this variable by

% echo $PATH

We will assume that you extracted the bali-phy archive in /usr/local and so you want to add /usr/local/bin to your PATH. The commands for doing depend on what "shell" you are using. Type echo $SHELL to find out.

If your shell is sh or bash then the command looks like this:

% PATH=/usr/local/bin:$PATH

If your shell is csh or tcsh, then the command looks like this:

% setenv PATH /usr/local/bin:$PATH

Unfortunately, the effects of this will affect only the window you are typing in, and will vanish when you reboot. You can put these command into the files .profile (for the Bourne shell sh), .bash_profile (for BASH), or .login (for tcsh). However, the details are beyond the scope of this document.

The simplest way to run BAli-Phy is to invoke the bali-phy executable directly:

% bali-phy sequence-file --data-dir prefix/share/bali-phy/Data/

Here sequence-file is a FastA or PHYLIP file containing the sequences you wish to analyze. It should end in .fasta or .phy to indicate which format it is using. Here prefix stands for the directory where you extracted the bali-phy archive.

BAli-Phy stores important information in a "Data" directory, and needs to know where to find this information. This information includes the genetic code and the WAG rate matrix. If you installed BAli-Phy in a directory called prefix, then the Data/ directory will be at prefix/share/bali-phy/Data/.

If you specify the location of the Data/ directory in a configuration file, then you do not need to specify it on the command line every time. Then, in the future you can just type:

% bali-phy sequence-file

If you don't specify where the data directory is, then BAli-Phy will look for it at ./Data.

data-dir = somewhere/Data

% ln -s somewhere/Data

% cp -r somewhere/Data .

Putting the analysis options in an option file instead of on the command line can be more convenient if you are going to run the same analysis many times, or if you have a large number of options. In addition, the option file may contain comments and blank lines, and can be a good way to record what options you used in an analysis.

#select a data set to analyze
align = examples/EF-Tu/5d.fasta

#select an substitution model
smodel = log-normal+INV

#fix the alignment and do not model indels
traditional = traditional

% bali-phy examples/EF-Tu/5d.fasta --smodel log-normal+INV --traditional

In order to run bali-phy for long periods of time, some modifications to the above commands may be necessary.

The syntax for the program is:

The sequence file is the only required argument. It can be either a FastA (*.fasta) file or a PHYLIP (*.phy) file. The file must end in one of these two suffixes or BAli-Phy won't know how to read it. In addition your FastA files should not contain any blank lines.

The optional arguments are described below. They can also be found by typing bali-phy --help on the command line.

BAli-Phy can read in sequences and alignments in both FastA and PHYLIP formats. Filenames for FastA files should end in .fasta, .mpfa, .fna, .fas, .fsa, or .fa. Filenames for PHYLIP files should end in .phy. If one of these extensions is not used, then BAli-Phy will attempt to guess which format is being used.

Note that blank lines are now allowed in FastA files in version 2.0.1 and later.

Large data sets run more slowly than small data sets. We recommend a conservative starting point with few taxa and short sequence lengths. You can then increase the size of your data set until a balance between speed and size is reached.

The number of samples that you need depends on whether you are primarily interested in obtaining a point estimate or in obtaining detailed measures of confidence and uncertainty. For detailed measures of confidence and uncertainty you should obtain a minimum of 10,000 samples after the Markov chain converges. For an estimate, you don't need very many samples after convergence. (But you may need many samples to be sure that you've converged!)

The basic substitution models in BAli-Phy are continuous-time Markov chains (CTMC). More advanced models such as the Γ 4 +INV model or the M2 codon model are described Section 9, “Substitution Models (Advanced)”. CTMC models can be characterized by transition rates Q ij from letter i to letter j. After a given time t the probability for transition from state i to state j is given by

using a matrix exponential. Becase the The CTMC models used in BAli-Phy are all reversible, the rate matrix for these reversible models can be decomposed into a symmetric matrix S and equilibrium frequencies π as follows:

The matrix S is called the exchangability matrix, and represents how exchangeable letters i and j are independent of their frequencies.

The current models are RS05, RS07-no-T, and RS07. The default is RS07.

To pin columns of the alignment, specify alignment constraints in a file as follows:

A B C
1 2 2

A B C D
2 2 - - 
- - 2 2

Substitution models are specified using a stack, as follows: Model[arg]+Model[arg]+...+Model[arg] where each model uses the previous models as input. Arguments are optional.

Model modifiers are gamma, log-normal, INV, M2, M3, and M7.

The above decomposition can be generalized slightly to yield the following decomposition, where f ranges from 0 to 1 .

Here the parameter f specifies the relative importance of unequal conservation (f=0 ) and unequal replacement (f=1 ) in maintaining the equilibrium frequencies π.

In fact, this can be generalized even further to

where

These models can therefore be expressed as a combination of an "exchange model" (for S) and a "frequency model" (for R).

Example: --smodel EQU --alphabet Triplets

Example: --smodel HKY

Example: --smodel TN+pi=constant

Example: --smodel Empirical[WAG]+log-normal+INV

Example: --smodel M0 --alphabet Codons

Example: --smodel M0+pi=nucleotides --alphabet Codons

Example: --smodel M2 --alphabet Codons

Example: --smodel M0[TN]+M2 --alphabet Codons

BAli-Phy creates a new directory to store its output files each time it is run. By default, the directory name is the name of the sequence file, with a number added on the end to make it unique. BAli-Phy first checks if there is already a directory called file-1/, and then moves on to file-2/, etc. until it finds an unused directory name.

You can specify a different name to use instead of the sequence-file name by using the --name option.

BAli-Phy produces the following output files inside the directory that it creates:

For the last two files, each line in these files corresponds to one iteration.

First, enter the output directory. Then make a local copy of the the analysis makefile:

% cp prefix/share/doc/bali-phy/GNUmakefile .

Here, prefix is the directory where you installed BAli-Phy.

After you have installed the analysis makefile, run the command:

 % make SKIP=burn-in

or

 % make SKIP=burn-in SIZE=iterations

Here, burn-in represents the number of iterations to skip as burn-in, and iterations represents the maximum number of iterations to use in the analysis. Extra samples are discarded. In order for this to work, the directory containing the BAli-Phy tools must be in your PATH.

Running the analysis will produce the three directories: Results/, Mixing/, and Work/. The Results/ directory contains tree and alignment estimates and confidence levels. The Mixing/ directory contains various measures of whether the chain ran long enough given its Mixing. The Work/ directory contains various intermediate files that you probably do not need.

Running the above command will produce the following files in the Results/ directory:

In addition, the following files will be generated to summarize alignment uncertainty, unless the analysis uses a fixed alignment.

In addition, the following files will be produced in the Mixing/ directory:

The SRQ plots can be viewed by typing "plot 'file' with lines" in gnuplot.

Usage: alignment-find [OPTIONS] < alignments-file

Find the last (or first) FastA alignment in a file.

alignment-draw alignment-file [AU-file] [OPTIONS]

Draw an alignment to HTML, optionally coloring residues by AU.

alignment-thin alignment-file tree-file [OPTIONS]

Remove taxa from an alignment to preserve the most sequence diversity, as measured by the total length of the tree for the remaining taxa.

alignment-chop-internal alignment-file [OPTIONS]

Remove ancestral sequences from an alignment. (This probably only works for alignments output by bali-phy.)

alignment-info alignment-file tree-file [OPTIONS]

Display basic information about the alignment, including its length, the number of sequences, columns that are constant or informative, letter frequencies, etc.

If a tree is supplied, then the unweighted parsimony score is given as well.

alignment-indices alignment-file [OPTIONS]

Show the alignment in terms of the index of each character in its sequence. Each line in this file corresponds to one alignment column. This can be useful in producing alignment constraint files.

alignment-cat file1 [file2 ...]

Concatenate several alignments (with the same sequence names) end-to-end.

Usage: trees-consensus file [OPTIONS]

This program analyzes the tree sample contained in file. It reports the MAP topology, the supported taxa partitions (including partial partitions), and the majority consensus topology.

Usage: trees-bootstrap file1 [file2 ... ] --predicates predicate-file [OPTIONS]

This program analyzes the tree samples contained in file1, file2, etc. It gives the support of each tree sample for each predicate in predicate-file, and reports a confidence interval based on the block bootstrap.

Each predicate is the intersection of a set of partitions, and is specified as a list of partitions or (multifurcating) trees, one per line. Predicates are separated by blank lines.

Usage: trees-to-SRQ predicate-file [OPTIONS] trees-file

This program analyzes the tree samples contained in trees-file. It uses them to produce an SRQ plot for each predicate in predicate-file. Plots are produced in gnuplot format, with one point per line and with plots separated by a blank line.

If --mode sum is specified, then a "sum" plot is produced instead of an SRQ plot. In this plot, the slope of the curve corresponds to the posterior probability of the event. If the --invert option is used then the slope of the curve correspond to the probability of the inverse event. This is recommended if the probability of the event is near 1.0, because the sum plot does not distinguish variation in probabilities near 1.0 well.