source: branches/stable/GDE/PHYLIP/doc/retree.html

Last change on this file was 2176, checked in by westram, 21 years ago

* empty log message *
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 18.6 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2<HTML>
3<HEAD>
4<TITLE>retree</TITLE>
5<META NAME="description" CONTENT="retree">
6<META NAME="keywords" CONTENT="retree">
7<META NAME="resource-type" CONTENT="document">
8<META NAME="distribution" CONTENT="global">
9<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
10</HEAD>
11<BODY BGCOLOR="#ccffff">
12<DIV ALIGN=RIGHT>
13version 3.6
14</DIV>
15<P>
16<DIV ALIGN=CENTER>
17<H1>RETREE -- Interactive Tree Rearrangement</H1>
18</DIV>
19<P>
20&#169; Copyright 1993-2002 by The University of
21Washington.  Written by Joseph Felsenstein.  Permission is granted to copy
22this document provided that no fee is charged for it and that this copyright
23notice is not removed.
24<P>
25RETREE is a tree editor.  It reads in a tree,
26or allows the user to construct one, and
27displays this tree on the screen.  The
28user then can specify how the tree is to
29be rearraranged, rerooted or written out to a file.
30<P>
31The input trees are in one file (with default file name
32<TT>intree</TT>), the
33output trees are written into another (<TT>outtree</TT>).  The user
34can reroot, flip branches, change names of species, change or remove
35branch lengths, and move around to look at various parts of the tree if it is
36too large to fit on the screen.  The trees can be multifurcating at any
37level, although the user is warned that many PHYLIP programs still cannot
38handle multifurcations above the root, or even at the root.
39<P>
40A major use for this program will be to change rootedness of trees so that
41a rooted tree derived from one program can be fed in as an unrooted tree to
42another (you are asked about this when you give the command to write out
43the tree onto the tree output file).  It will also be useful for specifying
44the length of a branch in
45a tree where you want a program like DNAML, DNAMLK, FITCH, or CONTML to
46hold that branch length constant (see the L suboption of the User Tree
47option in those programs.  It will also be useful for changing the order
48of species for purely cosmetic reasons for DRAWGRAM and DRAWTREE, including
49using the Midpoint method of rooting the tree.  It can also be used to write out
50a tree file in the Nexus format used by Paup and MacClade or in our XML tree
51file format.
52<P>
53This program uses graphic characters that show the tree to best
54advantage on some computer systems.
55Its graphic characters will work best on MSDOS systems or MSDOS windows in
56Windows, and to
57any system whose screen or terminals emulate ANSI standard terminals
58such as old Digitial VT100 terminals,
59Telnet programs,
60or VT100-compatible windows in the X windowing system.
61For any other screen types, (such as Macintosh windows) there is a generic
62option which does
63not make use of screen graphics characters.  The program will work well
64in those cases, but the tree it displays will look a bit uglier.
65<P>
66The user interaction starts with the program presenting a menu.  The
67menu looks like this:
68<P>
69<TABLE><TR><TD BGCOLOR=white>
70<PRE>
71
72Tree Rearrangement, version 3.6a3
73
74Settings for this run:
75  U          Initial tree (arbitrary, user, specify)?  User tree from tree file
76  N   Format to write out trees (PHYLIP, Nexus, XML)?  PHYLIP
77  0                     Graphics type (IBM PC, ANSI)?  (none)
78  W       Width of terminal screen, of plotting area?  80, 80
79  L                        Number of lines on screen?  24
80
81Are these settings correct? (type Y or the letter for one to change)
82
83</PRE>
84</TD></TR></TABLE>
85<P>
86The 0 (Graphics type) option is the usual
87one and is described in the main documentation file.  The U (initial tree)
88option allows the user to choose whether
89the initial tree is to be arbitrary, interactively specified by the user, or
90read from a tree file.  Typing U causes the program to change among the
91three possibilities in turn.  Usually we will want to use a User Tree from
92a file.  It requires that you have available a tree file
93with the tree topology of the initial tree.  If you wish to set up some other
94particular tree you can either use the "specify" choice in the initial tree
95option (which is somewhat clumsy to use) or rearrange a User Tree of an
96arbitrary tree into the shape you want by using
97the rearrangement commands given below. 
98<P>
99The L (screen Lines) option allows the user to change the height of the
100screen (in lines of characters) that is assumed to be available on the
101display.  This may be particularly helpful when displaying large trees
102on displays that have more than 24 lines per screen, or on workstation
103or X-terminal screens that can emulate the ANSI terminals with more than
10424 lines.
105<P>
106The N (output file format) option allows the user to specify that the tree files that
107are written by the program will be in one of three formats:
108<P>
109<OL>
110<LI>The <B>PHYLIP</B> default file format (the Newick standard) used by the
111programs in this package.
112<LI> The <B>Nexus</B> format  defined by
113David Swofford and by Wayne Maddison and David Maddison for their programs
114PAUP and MacClade.  A tree file written in Nexus format should be directly
115readable by those programs (They also have options to read a regular
116PHYLIP tree file as well).
117<LI> An <B>XML</B> tree file format which we have defined.
118</OL>
119<P>
120The XML tree file format is fairly simple.  Each tree is included in tags
121&lt;PHYLOGENY&gt; ... &lt;/PHYLOGENY&gt;.  Each branch of the tree is enclosed in a pair of tags
122&lt;BRANCH&gt; ... &lt;/BRANCH&gt;, which enclose the branch and all its descendants.
123If the branch has a length, this is given by the LENGTH attribute of the
124BRANCH tag, so that the pair of tags looks like this:
125<P>
126<PRE>
127&lt;BRANCH LENGTH=0.09362&gt; ... &lt;/BRANCH&gt;
128</PRE>
129<P>
130A tip of the tree is at the end of a branch (and hence enclosed in a pair of
131&lt;BRANCH&gt; ... &lt;/BRANCH&gt; tags.  Its name is enclosed by &lt;NAME&gt; ... &lt;/NAME&gt;
132tags.  Here is an XML tree:
133<P>
134<TABLE><TR><TD BGCOLOR=white>
135<PRE>
136&lt;phylogeny&gt;
137  &lt;branch&gt;
138    &lt;branch length=0.87231&gt;&lt;name&gt;Mouse&lt;/name&gt;&lt;/branch&gt;
139    &lt;branch length=0.49807&gt;&lt;name&gt;Bovine&lt;/name&gt;&lt;/branch&gt;
140    &lt;branch length=0.39538&gt;
141      &lt;branch length=0.25930&gt;&lt;name&gt;Gibbon&lt;/name&gt;&lt;/branch&gt;
142      &lt;branch length=0.10815&gt;
143        &lt;branch length=0.24166&gt;&lt;name&gt;Orang&lt;/name&gt;&lt;/branch&gt;
144        &lt;branch length=0.04405&gt;
145          &lt;branch length=0.12322&gt;&lt;name&gt;Gorilla&lt;/name&gt;&lt;/branch&gt;
146          &lt;branch length=0.06026&gt;
147            &lt;branch length=0.13846&gt;&lt;name&gt;Chimp&lt;/name&gt;&lt;/branch&gt;
148            &lt;branch length=0.0857&gt;&lt;name&gt;Human&lt;/name&gt;&lt;/branch&gt;
149          &lt;/branch&gt;
150        &lt;/branch&gt;
151      &lt;/branch&gt;
152    &lt;/branch&gt;
153  &lt;/branch&gt;
154&lt;/phylogeny&gt;
155</PRE>
156</TD></TR></TABLE>
157<P>
158The indentation  is for readability but is not part of the XML tree
159standard, which ignores that kind of white space.
160<P>
161What programs can read an XML tree?  None right now, not even PHYLIP programs.
162But soon our lab's LAMARC package will have programs that can read an XML tree.
163XML is rapidly becoming the standard for representing and interchanging
164complex data -- it is time to have an XML tree standard.  Certain extensions
165are obvious (to represent the bootstrap proportion for a branch, use
166BOOTP=0.83 in the BRANCH tag, for example). 
167<P>
168The W (screen and window Width) option specifies the width in characters
169of the area which the trees will be plotted to fit into.  This is by
170default 80 characters so that they will fit on a normal width terminal.  The
171actual width of the display on the terminal (normally 80 characters) will
172be regarded as a window displaying part of the tree.  Thus you could
173set the "plotting area" to 132 characters, and inform the program that
174the screen width is 80 characters.  Then the program will display only part
175of the tree at any one time.  Below we will show how to move the "window"
176and see other parts of the tree.
177<P>
178After the initial menu is displayed and the choices are made,
179the program then sets up an initial tree and displays it.  Below it will be a
180one-line menu of possible commands.  Here is what the tree and the menu
181look like (this is the tree specified by the example input tree given at
182the bottom of this page, as it displays when the terminal type is "none"):
183<P>
184<TABLE><TR><TD BGCOLOR=white>
185<PRE>
186                                      ,>>1:Human
187                                   ,>22 
188                                ,>21  `>>2:Chimp
189                                !  ! 
190                             ,>20  `>>>>>3:Gorilla
191                             !  ! 
192                 ,>>>>>>>>>>19  `>>>>>>>>4:Orang
193                 !           ! 
194              ,>18           `>>>>>>>>>>>5:Gibbon
195              !  ! 
196              !  !              ,>>>>>>>>6:Barbary Ma
197              !  `>>>>>>>>>>>>>23 
198              !                 !  ,>>>>>7:Crab-e. Ma
199     ,>>>>>>>17                 `>24 
200     !        !                    !  ,>>8:Rhesus Mac
201     !        !                    `>25 
202     !        !                       `>>9:Jpn Macaq
203  ,>16        ! 
204  !  !        `>>>>>>>>>>>>>>>>>>>>>>>>>10:Squir. Mon
205  !  ! 
206  !  !                                ,>11:Tarsier
207** 7 lines below screen **
208
209NEXT? (Options: R . U W O T F D B N H J K L C + ? X Q) (? for Help)
210</PRE>
211</TD></TR></TABLE>
212<P>
213The tree that was read in had no branch lengths on its branches.  The
214absence of a branch length is indicated by drawing the branch with "<TT>></TT>"
215characters (<TT>>>>>>>></TT>).  When branches have branch lengths, they are
216drawn with "-" characters (<TT>-------</TT>) and their
217lengths on the screen are approximately proportional to the branch length.
218<P>
219If you type "?" you will get a single screen showing a description of each
220of these commands in a few words.  Here are slightly more detailed
221descriptions of the commands:
222<P>
223<DL COMPACT>
224<DT>R</DT> <DD>("Rearrange").  This command asks for the number of a node which is to be
225removed from the tree.  It and everything to the right of it on the tree is to
226be removed (by breaking the branch immediately below it). (This is also
227everything "above" it on the tree when the tree grows upwards, but as the
228tree grows from left to right on the screen we use "right" rather than
229"above").  The command also
230asks whether that branch is to be inserted At a node or Before a node.
231The first will insert it as an additional branch coming out of an
232existing node (creating a more multifurcating tree), and the second will insert
233it so that a new internal node is created in the tree, located in the
234branch that precedes the node (to the left of it), with the branch that is
235inserted coming off from that new node.  In both cases the program asks you
236for the number of a node at (or before) which that group is to be inserted.
237If an
238impossible number is given, the program refuses to carry out the rearrangement
239and asks for a new command.  The rearranged tree is displayed: it will often
240have a different number of steps than the original.  If you wish to undo a
241rearrangement, use the Undo command, for which see below.</DD>
242<P>
243<DT>.</DT> <DD> (dot) This command simply causes the current tree to be redisplayed.  It is of
244use when the tree has partly disappeared off of the top of the screen owing to
245too many responses to commands being printed out at the bottom of the screen.</DD>
246<P>
247<DT>=</DT> <DD>(toggle display of branch lengths).  This option is available whenever
248the tree has a full set of branch lengths.  It toggles on and off whether
249the tree displayed on the screen is shown with the relative branch lengths
250roughly correct.  (It cannot be better than roughly correct because the
251display is in units of length of whole character widths on the screen).  It
252does not actually remove any branch lengths from the tree: if the tree
253showing on the screen seems to have no branch lengths after use of the "="
254option, if it were written out at that point, it would still have a full]
255set of branch lengths.</DD>
256<P>
257<DT>U</DT> <DD>("Undo").  This command reverses the effect of the most recent
258rearrangement, outgroup re-rooting, or flipping of branches.  It returns to the
259previous tree topology.  It will be of great use when rearranging the tree and
260when one -- it permits you to
261abandon the new one and return to the previous one without remembering its
262topology in detail.  Some operations, such as the simultaneous removal of
263lengths from all branches, cannot be reversed.</DD>
264<P>
265<DT>W</DT> <DD>("Write").  This command writes out the current tree onto a tree output
266file.  If the file already has been written to by this run of RETREE, it will
267ask you whether you want to replace the contents of the file, add the tree to
268the end of the file, or not write out the tree to the file.  It will also
269ask you whether you want the tree to written out as Rooted or Unrooted.  If
270you choose Unrooted, it will write the outermost split of the tree as a
271three-way split with the three branches being those that issue from one of
272the nodes.  This node will be the left (upper) interior node which is next
273to the root, or the other one if there is no interior node to the left (above)
274the root.  The tree
275is written in the standard format used by PHYLIP (a subset of the
276Newick standard), in the Nexus format, or in an XML tree file format.
277A normal PHYLIP tree
278is in the proper format to serve as the
279User-Defined Tree for setting up the initial tree in a subsequent run of the
280program.  However, some programs also require a line in the tree input
281file that gives the number of trees in the file.  You may have to add this
282line using an editor such as <TT>vi</TT>, <TT>Emacs</TT>, Windows
283<TT>Notepad</TT>, or MacOS's <TT>Simpletext</TT>.</DD>
284<P>
285<DT>O</DT> <DD>("Outgroup").  This asks for the number of a node which is to be the
286outgroup.  The tree will be redisplayed with that node
287as the left descendant of the bottom fork.  Note that it is possible to
288use this to make a multi-species group the outgroup (i.e., you can give the
289number of an interior node of the tree as the outgroup, and the program will
290re-root the tree properly with that on the left of the bottom fork.</DD>
291<P>
292<DT>M</DT> <DD>("Midpoint root").  This reroots a tree that has a complete set of
293branches using the Midpoint rooting method.  That rooting method finds the
294centroid of the tree -- the point that is equidistant from the two
295farthest points of the tree, and roots the tree there.  This is the point
296in the middle of the longest path from one tip to another in the tree.
297This has the effect
298of making the two farthest tips stick out an equal distance to the
299right.  Note that as the tree is rerooted, the scale may change on the screen
300so that it looks like it ahas suddenly gotted a bit longer.  It will not
301have actually changed in total length.  This option is not in the menu
302if the tree does not have a full set of branch lengths.</DD>
303<P>
304<DT>T</DT> <DD>("Transpose").  This asks for a node number and then flips the two
305branches at that node, so that the left-right order of branches at that node is
306changed.  This also does not actually change the tree topology
307but it does change the appearance of the tree.  However, unlike the <TT>F</TT>
308option discussed below, the individual subtrees defined by those branches do
309not have the order of any branches reversed in them.</DD>
310<P>
311<DT>F</DT> <DD>("Flip").  This asks for a node number and then flips the entire
312subtree at that node, so that the left-right order of branches in the whole
313subtree is changed.  This does not actually change the tree topology
314but it does change the appearance of the tree.  Note that it works differently
315than the <TT>F</TT> option in the programs MOVE, DNAMOVE, and DOLMOVE, which
316is actually like the <TT>T</TT> option mentioned above.</DD>
317<P>
318<DT>B</DT> <DD>("Branch length").  This asks you for the number of a node
319which is at the end of a branch length, then asks you whether you want to
320enter a branch length for that branch, change the branch length for that
321branch (if there is one already) or remove the branch length from the
322branch.</DD>
323<P>
324<DT>N</DT> <DD>("Name").  This asks you which species you want to change the
325name for (referring to it by the number for that branch), then gives you the
326option of either removing the name, typing a new name, or leaving the
327name as is.  Be sure not to try to enter a parentheses ("(" or ")"), a
328colon (":"), a comma (",") or a semicolon (";") in a name, as those may
329be mistaken for structural information about the tree when the tree file
330is read by another program.</DD>
331<P>
332<DT>H, J, K, or L.</DT> <DD>These are the movement commands for scrolling the
333"window" across a tree.  H moves the "window" leftwards (though not beyond
334column 1, J moves it down, K up, and L right.  The "window" will
335move 20 columns or rows at a time, and the tree will be redrawn in
336the new "window". Note that this amount of movement is not a full screen.</DD>
337<P>
338<DT>C</DT> <DD>("Clade").  The C command instructs the program to print out
339only that part of the
340tree (the "clade") from a certain node on up.  The program will prompt you for
341the number of this node.  Remember that thereafter you are not looking at the
342whole tree.  To go back to looking at the whole tree give the C command again
343and enter "0" for the node number when asked.  Most users will not want to use
344this option unless forced to, as much can be accomplished with the window
345movement commands H, J, K, and L.</DD>
346<P>
347<DT>+</DT> <DD>("next tree").  This causes the program to read in the next tree in
348the input file, if there is one.  Currently the program does not detect
349gracefully that it has come to the end of the input tree file, and may
350crash with a "segmentation fault" if it does.  However usually it will not
351lose any tree file that it has written.  On Unix or Linux systems the
352crash may produce a useless "core dump" (a big file named "core") which
353you will want to delete.</DD>
354<P>
355<DT>?</DT> <DD>("Help").  Prints a one-screen summary of what the commands do, a few
356words for each command.</DD>
357<P>
358<DT>X</DT> <DD>("Exit").  Exit from program.  If the current tree has not yet been saved
359into a file, the program will first ask you whether it should be saved.</DD>
360<P>
361<DT>Q</DT> <DD>("Quit").  A synonym for X.  Same as the eXit command.</DD>
362</DL>
363<P>
364The program was written by Andrew Keeffe, using some code from DNAMOVE, which
365he also wrote.
366<P>
367Below is a test tree file.  We have already showed (above), what the
368resulting tree display looks like when the terminal type is "none".
369For ANSI or IBM PC screens it will look better, using the graphics characters
370of those screens, which we do not attempt to show here.
371<P>
372<HR>
373<P>
374<H3>TEST INPUT TREE FILE</H3>
375<P>
376<TABLE><TR><TD BGCOLOR=white>
377<PRE>
378((((((((Human,Chimp),Gorilla),Orang),Gibbon),(Barbary_Ma,(Crab-e._Ma,
379(Rhesus_Mac,Jpn_Macaq)))),Squir._Mon),((Tarsier,Lemur),Bovine)),Mouse);
380</PRE>
381</TD></TR></TABLE>
382</BODY>
383</HTML>
Note: See TracBrowser for help on using the repository browser.