Fixed & Starting Trees in BEAST 2

Setting a starting tree in the program BEAST can be a complicated issue, and I've been asked about troubleshooting for it. Here is a full XML file with annotations, as an example of how to designate a starting tree and how to force BEAST to keep it as a fixed topology.

BEAST is a widely-used phylogenetic dating program and has an excellent GUI interface in BEAUti, where users can control most all parameters and inputs they'd need. BEAUti is the front-end program that produces the XML file that is then used by BEAST for tree estimation. XML stands for 'eXtensible Markup Language', which is both human and machine readable, and is similar to HTML.

One piece that must be manually edited in a text editor is the user-specified starting tree, if desired. Why use a starting tree? For large and difficult datasets, one can start in the best area of parameter space, so that the Markov chain isn't wasting time jumping around to sample the presumably 'incorrect' topologies. I'm not sure as to how much a starting tree increases efficiency, since alternate topologies can still be sampled (it's certainly not needed for small, straightforward datasets), but I may update my opinions in the future based on the success of trying to manipulate phylogenomic data.

There are two different XML editing tasks I'll cover.

ONE: writing the code to provide BEAST with a starting tree (topology and branch lengths). This is data-dependent, so you'll first have to estimate a starting tree that agrees with run parameters.

TWO: fixing the tree topology so that all branch lengths are calculated on only the input topology. This is really easy! You just comment out four lines of code so the topology isn't ever updated.

---

Setting a user-specified starting topology
The default starting tree is a random tree, which is coded in an element (content & attributes surrounded by an opening and closing tag ('init', our tree initializer). The whole element needs to be replaced by a user-specified starting tree in newick format. Take a look at the example document!

Fixing the starting tree topology
There are four lines to comment out: the operators for subtree-slide, wide & narrow exchange, and Wilson-Balding. Removing these four operators prevents the topology from updating, but still allows for estimation of the node ages (i.e., branch lengths will be modified even though the topology will not). In an XML file,  comments are surrounded by ' <!-- ' and ' --> ', which means they will not be processed.

---

An example XML file is here for download. Open it in a text editor to view the annotations! It was written in BEAST 2.4, and it will open in BEAUti and run with no further modifications.

beast_fix_starting_tree_murray.xml
File Size:	28 kb
File Type:	xml

Download File

---

---

There are a couple of nice sites with information on user input starting trees, yet translating that to your own data can still be a bit of a struggle. I hope here I could add a bit of guidance on the issue by providing an annotated XML file to help clarify the changes needed.  

There is now an updated and more-detailed tutorial at: http://www.beast2.org/fix-starting-tree/.
Also, thanks to great info from: http://www.northernbotanist.com/?page_id=732.