© Copyright 1993-2008 by The University of Washington. Written by Joseph Felsenstein. Permission is granted to copy this document provided that no fee is charged for it and that this copyright notice is not removed.
Retree is a tree editor. It reads in a tree, or allows the user to construct one, and displays this tree on the screen. The user then can specify how the tree is to be rearranged, rerooted or written out to a file.
The input trees are in one file (with default file name intree), the output trees are written into another (outtree). The user can reroot, flip branches, change names of species, change or remove branch lengths, and move around to look at various parts of the tree if it is too large to fit on the screen. The trees can be multifurcating at any level, although the user is warned that many PHYLIP programs still cannot handle multifurcations above the root, or even at the root.
A major use for this program will be to change rootedness of trees so that a rooted tree derived from one program can be fed in as an unrooted tree to another (you are asked about this when you give the command to write out the tree onto the tree output file). It will also be useful for specifying the length of a branch in a tree where you want a program like Dnaml, Dnamlk, Fitch, or Contml to hold that branch length constant (see the L suboption of the User Tree option in those programs). It will also be useful for changing the order of species for purely cosmetic reasons for Drawgram and Drawtree, including using the Midpoint method of rooting the tree. It can also be used to write out a tree file in the Nexus format used by Paup and MacClade or in our XML tree file format.
This program uses graphic characters that show the tree to best advantage on some computer systems. Its graphic characters will work best on MSDOS systems or MSDOS windows in Windows, and to any system whose screen or terminals emulate ANSI standard terminals such as old Digitial VT100 terminals, Telnet programs, or VT100-compatible windows in the X windowing system. For any other screen types, (such as Macintosh windows) there is a generic option which does not make use of screen graphics characters. The program will work well in those cases, but the tree it displays will look a bit uglier.
As we will see below, the initial menu of the program allows you to choose among three screen types (PCDOS, Ansi, and none). If you want to avoid having to make this choice every time, you can change some of the constants in the file phylip.h to have the terminal type initialize itself in the proper way, and recompile. We have tried to have the default values be correct for PC, Macintosh, and Unix screens. If the setting is "none" (which is necessary on Macintosh MacOS 9 screens), the special graphics characters will not be used to indicate nucleotide states, but only letters will be used for the four nucleotides. This is less easy to look at.
The constants that need attention are ANSICRT and IBMCRT. Currently these are both set to "false" on Macintosh MacOS 9 systems, to "true" on MacOS X and on Unix/Linux systems, and IBMCRT is set to "true" on Windows systems. If your system has an ANSI compatible terminal, you might want to find the definition of ANSICRT in phylip.h and set it to "true", and IBMCRT to "false".
The user interaction starts with the program presenting a menu. The menu looks like this:
Tree Rearrangement, version 3.69 Settings for this run: U Initial tree (arbitrary, user, specify)? User tree from tree file N Format to write out trees (PHYLIP, Nexus, XML)? PHYLIP 0 Graphics type (IBM PC, ANSI)? ANSI W Width of terminal screen, of plotting area? 80, 80 L Number of lines on screen? 24 Are these settings correct? (type Y or the letter for one to change)
The 0 (Graphics type) option is the usual one and is described in the main documentation file. The U (initial tree) option allows the user to choose whether the initial tree is to be arbitrary, interactively specified by the user, or read from a tree file. Typing U causes the program to change among the three possibilities in turn. Usually we will want to use a User Tree from a file. It requires that you have available a tree file with the tree topology of the initial tree. If you wish to set up some other particular tree you can either use the "specify" choice in the initial tree option (which is somewhat clumsy to use) or rearrange a User Tree of an arbitrary tree into the shape you want by using the rearrangement commands given below.
The L (screen Lines) option allows the user to change the height of the screen (in lines of characters) that is assumed to be available on the display. This may be particularly helpful when displaying large trees on displays that have more than 24 lines per screen, or on workstation or X-terminal screens that can emulate the ANSI terminals with more than 24 lines.
The N (output file format) option allows the user to specify that the tree files that are written by the program will be in one of three formats:
The XML tree file format is fairly simple. The tree file, which may have multiple trees, is enclosed in a pair of <PHYLOGENIES> ... </PHYLOGENIES> tags. Each tree is included in tags <PHYLOGENY> ... </PHYLOGENY>. Each branch of the tree is enclosed in a pair of tags <CLADE> ... </CLADE>, which enclose the branch and all its descendants. If the branch has a length, this is given by the LENGTH attribute of the CLADE tag, so that the pair of tags looks like this:
<CLADE LENGTH="0.09362"> ... </CLADE>
A tip of the tree is at the end of a branch (and hence that branch is enclosed in a pair of <CLADE> ... </CLADE> tags). Its name is enclosed by <NAME> ... </NAME> tags. Here is an XML tree:
<phylogenies> <phylogeny> <clade> <clade length="0.87231"><name>Mouse</name></clade> <clade length="0.49807"><name>Bovine</name></clade> <clade length="0.39538"> <clade length="0.25930"><name>Gibbon</name></clade> <clade length="0.10815"> <clade length="0.24166"><name>Orang</name></clade> <clade length="0.04405"> <clade length="0.12322"><name>Gorilla</name></clade> <clade length="0.06026"> <clade length="0.13846"><name>Chimp</name></clade> <clade length="0.0857"><name>Human</name></clade> </clade> </clade> </clade> </clade> </clade> </phylogeny> </phylogenies>
The indentation is for readability but is not part of the XML tree standard, which ignores that kind of white space.
What programs can read an XML tree? None right now, not even PHYLIP programs! But soon our lab's LAMARC package will have programs that can read an XML tree. XML is rapidly becoming the standard for representing and interchanging complex data -- it is time to have an XML tree standard. Certain extensions are obvious (to represent the bootstrap proportion for a branch, use BOOTP=0.83 in the CLADE tag, for example).
There are other proposals for an XML tree standard. They have many similarities to this one, but are not identical to it. At the moment there is no mechanism in place for deciding between them other than seeing which get widely used. Here are links to other proposals:
|Taxonomic Markup Language||
and preprint at
published in the paper by
Ron Gilmour (2000).
BEAST XML phylogeny format
See page 9 of PDF of BEAST manual at
||An XML format for phylogenies is briefly described there.|
(see also example: )
|Jean-Daniel Fekete's DTD
for a tree XML file
The W (screen and window Width) option specifies the width in characters of the area which the trees will be plotted to fit into. This is by default 80 characters so that they will fit on a normal width terminal. The actual width of the display on the terminal (normally 80 characters) will be regarded as a window displaying part of the tree. Thus you could set the "plotting area" to 132 characters, and inform the program that the screen width is 80 characters. Then the program will display only part of the tree at any one time. Below we will show how to move the "window" and see other parts of the tree.
After the initial menu is displayed and the choices are made, the program then sets up an initial tree and displays it. Below it will be a one-line menu of possible commands. Here is what the tree and the menu look like (this is the tree specified by the example input tree given at the bottom of this page, as it displays when the terminal type is "none"):
,>>1:Human ,>22 ,>21 `>>2:Chimp ! ! ,>20 `>>>>>3:Gorilla ! ! ,>>>>>>>>>>19 `>>>>>>>>4:Orang ! ! ,>18 `>>>>>>>>>>>5:Gibbon ! ! ! ! ,>>>>>>>>6:Barbary Ma ! `>>>>>>>>>>>>>23 ! ! ,>>>>>7:Crab-e. Ma ,>>>>>>>17 `>24 ! ! ! ,>>8:Rhesus Mac ! ! `>25 ! ! `>>9:Jpn Macaq ,>16 ! ! ! `>>>>>>>>>>>>>>>>>>>>>>>>>10:Squir. Mon ! ! ! ! ,>11:Tarsier ** 7 lines below screen ** NEXT? (Options: R . U W O T F D B N H J K L C + ? X Q) (? for Help)
The tree that was read in had no branch lengths on its branches. The absence of a branch length is indicated by drawing the branch with ">" characters (>>>>>>>). When branches have branch lengths, they are drawn with "-" characters (-------) and their lengths on the screen are approximately proportional to the branch length.
If you type "?" you will get a single screen showing a description of each of these commands in a few words. Here are slightly more detailed descriptions of the commands:
The program was written by Andrew Keeffe, using some code from Dnamove, which he also wrote.
Below is a test tree file. We have already showed (above), what the resulting tree display looks like when the terminal type is "none". For ANSI or IBM PC screens it will look better, using the graphics characters of those screens, which we do not attempt to show here.