Introduction 3.2

From MbWiki

Jump to: navigation, search

Contents

Introduction

MrBayes 3 is a program for the Bayesian inference of phylogeny. The program has a command-line interface and should run on a variety of computer platforms, including clusters of Macintosh and UNIX computers. Note that the computer should be reasonably fast and should have a lot of RAM memory (depending on the size of the data matrix, the program may require hundreds of megabytes of memory). The program is optimized for speed and not for minimizing memory requirements.

This manual explains how to use the program. After this section, which introduces the program, we will first walk you through a simple analysis, which will get you started, and a more complex analysis that uses more of the program’s capabilities (section 3). We then briefly describe the models implemented in the program (section 4), answer some frequently asked questions (section 5), and discuss the differences between versions 2 and 3 of the program (section 6). Finally, we give more detailed instructions on how to compile the program and how to run the parallel versions of it (section 7). [[Section 7 also contains brief information for developers interested in tweaking MrBayes code or contributing to the MrBayes project. The manual ends with a series of diagrams giving a graphical overview of all the models and proposal mechanisms implemented in the program (Appendix). For more detailed information about commands and options in MrBayes, see the command reference that can either be downloaded from the program web site or generated from the program itself (see section 1.4 Getting Help below). All the information in the command reference is also available on-line when using the program.

The manual assumes that you are familiar with the basic concepts of Bayesian phylogenetics. If you are new to the subject, we recommend the recent reviews by Holder and Lewis (2003), Lewis (2001) and Huelsenbeck et al. (2001, 2002). It is also worthwhile to study the early papers introducing Bayesian phylogenetic methods (Li 1996; Mau, 1996; Rannala and Yang, 1996; Mau and Newton, 1997; Larget and Simon, 1999; Mau, Newton and Larget, 1999; Newton, Mau and Larget, 1999). The basic MCMC techniques are described in Metropolis et al. (1953) and Hastings (1970). The Metropolis-coupled MCMC used by MrBayes was introduced by Geyer (1991).

Conventions Used in this Manual

What you see on the screen and what is in the input file is in plain typewriter font. What you type is in bold typewriter font.

Acquiring and Installing MrBayes

MrBayes 3 is distributed without charge by download from the MrBayes web site. If someone has given you a copy of MrBayes 3, we strongly suggest that you download the most recent version from this site. The site also gives information about the MrBayes users email list and describes how you can report bugs or contribute to the project.

MrBayes 3 is a plain-vanilla program that uses a command line interface and therefore behaves virtually the same on all platforms ‑ Macintosh, Windows and Unix. There is a separate download package for each platform. The Macintosh package contains two versions of the program: the standard serial version, named MrBayes3.2, and a version for running the program in parallel on clusters of Macintoshes, named MrBayes3.2p. For more information on the parallel Macintosh version of MrBayes, which requires the installation of lam-mpi, see section 8 of this user manual or contact your local system administrator. The Windows package only contains the serial version of the program and is ready to run after unzipping, just like the Macintosh serial version.

If you decide to run the program under Unix/Linux, then you need to compile the program from the source code. In the latter case, simply unpack the file mrbayes-3.2.tar.gz by typing tar zxf mrbayes-3.2.tar.gz. The tar command uncompresses and extracts all of the files from the archive. You then need to compile the program. We have included a “configure” script that examines the settings on your machine and which generates a Makefile; a file that contains compiler instructions producing the serial version of the program. You first run the configure script and second you simply type make to compile the program according to these instructions. A typical compile session would look like this:

~ $ tar zxf mrbayes-3.2.tar.gz
~ $ cd mrbayes-3.2
~/mrbayes-3.2 $ ./configure
checking for gcc... gcc
checking for C compiler default output file name... a.out
checking whether the C compiler works... yes
checking whether we are cross compiling... no
checking for suffix of executables...
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc accepts -g... yes
checking for gcc option to accept ISO C89... none needed
checking how to run the C preprocessor... gcc -E
checking for grep that handles long lines and -e... /usr/bin/grep
checking for egrep... /usr/bin/grep -E
checking for ANSI C header files... yes
checking for exp in -lm... yes
checking for a BSD-compatible install... /usr/bin/install -c
checking for readline in -lreadline... yes
checking for rl_completion_matches function... no
checking for 32 or 64 bits cpu... 32
configure: creating ./config.status
config.status: creating Makefile
config.status: creating config.h
~/mrbayes-3.2 $ make
gcc -O3 -ffast-math -Wall -DUSECONFIG_H -c -o bayes.o bayes.c
gcc -O3 -ffast-math -Wall -DUSECONFIG_H -c -o command.o command.c
gcc -O3 -ffast-math -Wall -DUSECONFIG_H -c -o mbmath.o mbmath.c
gcc -O3 -ffast-math -Wall -DUSECONFIG_H -c -o mcmc.o mcmc.c
gcc -O3 -ffast-math -Wall -DUSECONFIG_H -c -o model.o model.c
gcc -O3 -ffast-math -Wall -DUSECONFIG_H -c -o plot.o plot.c
gcc -O3 -ffast-math -Wall -DUSECONFIG_H -c -o sump.o sump.c
gcc -O3 -ffast-math -Wall -DUSECONFIG_H -c -o sumt.o sumt.c
gcc -O3 -ffast-math -Wall -DUSECONFIG_H -c -o tree.o tree.c
gcc -O3 -ffast-math -Wall -DUSECONFIG_H -c -o utils.o utils.c
gcc -O3 -ffast-math -Wall -DUSECONFIG_H -lreadline -lm mb.c bayes.o command.o mbmath.o mcmc.o model.o plot.o sump.o sumt.o tree.o utils.o -o mb

The compilation usually stops for several minutes at the mcmc.c and model.c files; this is perfectly normal. This is the largest source file and optimization of the code takes quite a while.

Depending on which platform/distribution the compilation is being performed on, it may be useful to install relevant development libraries to enable compilation. Users of Ubuntu 5.10 (Breezy Badger), for instance, may need to install the either the libreadline4-dev or libreadline5-dev package to provide linking during compilation to GNU readline functionality. You have to do this before you run the configure script.

We assume as the default C compiler gcc, which is installed on most systems. If you do not have gcc installed on your machine or when you want to use another compiler, you can set the environment variable CC before you run the configure script. Use setenv CC MyCompiler if you use the (t)csh shell, use export CC=MyCompiler if you use the bash shell or if you don't know what shell you are running.

~/mrbayes-3.2 $ export CC=MyCompiler
~/mrbayes-3.2 % ./configure
checking for gcc... MyCompiler
checking for C compiler default output file name... a.out
checking whether the C compiler works... yes
...

If you want to produce the MPI version, you have to run the configure script with an extra option, like ./configure --enable-mpi. This assumes that you have the mpicc compiler in your path. See section 8 of this manual for more information.

The executable serial version of the program is called “mb”. To execute the program, simply type ./mb in the directory where you compiled the program. The ./ prefix is needed to tell Unix that you want to run the local copy of mb in your working directory. If you run MrBayes often, you will probably want to add the program to your “path”; refer to your Unix manual or your local Unix expert for more information on this.

All three packages of MrBayes come with example data files. These are intended to show various types of analyses you can perform with the program, and you can use them as templates for your own analyses. Two of the files, primates.nex and cynmix.nex, will be used in the tutorial sections of this manual (sections 2 and 3).

Getting Started

Start MrBayes by double-clicking the application icon (or typing ./mb) and you will see the information below:

MrBayes v3.2


(Bayesian Analysis of Phylogeny)

by
Fredrik Ronquist, John P. Huelsenbeck, and Paul van der Mark

School of Computational Science
Florida State University
ronquist@csit.fsu.edu

Section of Ecology, Behavior and Evolution
Division of Biological Sciences
University of California, San Diego
johnh@biomail.ucsd.edu

Distributed under the GNU General Public License

Type "help" or "help <command>" for information
on the commands that are available.


MrBayes >

The order of the authors is randomized each time you start the program, so don’t be surprised if the order differs from the one above. Note the <tt>MrBayes > prompt at the bottom, which tells you that MrBayes is ready for your commands.

Changing the Size of the MrBayes Window

Some MrBayes commands will output a lot of information and write fairly long lines, so you may want to change the size of the MrBayes window to make it easier to read the output. On Macintosh and Unix machines, you should be able to increase the window size simply by dragging the margins. On a Windows machine, you cannot increase the size of the window beyond the preset value by simply dragging the margins but (on Windows XP, 2000 and NT) you can change both the size of the screen buffer and the console window by right-clicking on the blue title bar of the MrBayes window and then selecting “Properties” in the menu that appears. Make sure the “Layout” tab is selected in the window that appears, and then set the Screen Buffer Size and Window Size to the desired values.

Getting Help

At the MrBayes > prompt, type help to see a list of the commands available in MrBayes. Most commands allow you to set values (options) for different parameters. If you type help <command>, where <command> is any of the listed commands, you will see the help information for that command as well as a description of the available options. For most commands, you will also see a list of the current settings at the end. Try, for instance, help lset or help mcmc. The lset settings table looks like this:

Default model settings:

Parameter Options Current Setting

Nucmodel 4by4/Doublet/Codon 4by4
Nst 1/2/6 1
Code Universal/Vertmt/Mycoplasma/
Yeast/Ciliates/Metmt Universal
Ploidy Haploid/Diploid Diploid
Rates Equal/Gamma/Propinv/Invgamma/Adgamma Equal
Ngammacat <number> 4
Usegibbs Yes/No No
Gibbsfreq <number> 100
Nbetacat <number> 5
Omegavar Equal/Ny98/M3 Equal
Covarion No/Yes No
Coding All/Variable/Noabsencesites/
Nopresencesites All
Parsmodel No/Yes No

Note that MrBayes 3 supports abbreviation of commands and options, so in many cases it is sufficient to type the first few letters of a command or option instead of the full name.

A complete list of commands and options is given in the command reference, which can be downloaded from the program web site (http://www.mrbayes.net). You can also produce an ASCII text version of the command reference at any time by giving the command manual to MrBayes. Further help is available in a set of hyperlinked html pages produced by Jeff Bates and available on the MrBayes web site. Finally, you can get in touch with other MrBayes users and developers through the mrbayes-users email list (subscription information at http://www.mrbayes.net).

Reporting and Fixing Bugs

If you find a bug in MrBayes, we are very grateful if you tell us about it using the bug reporting functions of SourceForge, as explained on the MrBayes web site (http://www.mrbayes.net). When you submit a bug, make sure that you upload a data file with the data set and sequence of commands that produced the error. If the bug occurs during a MCMC analysis (after issuing the “mcmc” command), you can help us greatly by making sure the bug can be reproduced reliably using a small data set and ideally, a fixed seed and swapseed for the mcmc command. The Tracker software at SourceForge will make sure that you get email notification when the bug has been fixed in the source code on the MrBayes CVS repository at SourceForge. Note, however, that there may be some time before new executables containing the bug fix will be released.

Advanced users may be interested in fixing bugs themselves in the source code. Refer to section 8 of this manual for information on how to contribute bug fixes, improved algorithms or expanded functionality to other users of MrBayes.

License and Warranty

MrBayes is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. The program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details (http://www.gnu.org/copyleft/gpl.html).

Personal tools