/usr/share/doc/phylip/html/doc/retree.html is in phylip-doc 1:3.696+dfsg-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE>retree</TITLE>
<META NAME="description" CONTENT="retree">
<META NAME="keywords" CONTENT="retree">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
</HEAD>
<BODY BGCOLOR="#ccffff">
<DIV ALIGN=RIGHT>
version 3.696
</DIV>
<P>
<DIV ALIGN=CENTER>
<H1>Retree -- Interactive Tree Rearrangement</H1>
</DIV>
<P>
© Copyright 1993-2014 by Joseph Felsenstein. All rights reserved.
License terms <a href="main.html#copyright">here</a>.
<P>
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.
<P>
The input trees are in one file (with default file name
<TT>intree</TT>), the
output trees are written into another (<TT>outtree</TT>). 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.
<P>
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.
<P>
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.
<P>
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 <TT>phylip.h</TT> 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.
<P>
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 <TT>phylip.h</TT> and set it to "true", and
IBMCRT to "false".
<P>
The user interaction starts with the program presenting a menu. The
menu looks like this:
<P>
<TABLE><TR><TD BGCOLOR=white>
<PRE>
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)
</PRE>
</TD></TR></TABLE>
<P>
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.
<P>
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.
<P>
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:
<P>
<OL>
<LI>The <B>PHYLIP</B> default file format (the Newick standard) used by the
programs in this package.
<LI> The <B>Nexus</B> format defined by
David Swofford and by Wayne Maddison and David Maddison for their programs
PAUP and MacClade. A tree file written in Nexus format should be directly
readable by those programs (They also have options to read a regular
PHYLIP tree file as well).
<LI> An <B>XML</B> tree file format which we have defined.
</OL>
<P>
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:
<P>
<PRE>
<CLADE LENGTH="0.09362"> ... </CLADE>
</PRE>
<P>
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:
<P>
<TABLE><TR><TD BGCOLOR=white>
<PRE>
<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>
</PRE>
</TD></TR></TABLE>
<P>
The indentation is for readability but is not part of the XML tree
standard, which ignores that kind of white space.
<P>
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).
<P>
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:
<P>
<TABLE border=2>
<TR>
<TD>
Taxonomic Markup Language
</TD>
<TD>
<A HREF="http://www.albany.edu/~gilmr/pubxml/"><CODE>
http://www.albany.edu/~gilmr/pubxml/</CODE></A>.<BR>
and preprint at<BR>
<A HREF="http://xml.coverpages.org/gilmour-TML.pdf"><CODE>xml.coverpages.org/gilmour-TML.pdf</CODE></A>
</TD>
<TD>
published in the paper by<BR>
Ron Gilmour (2000).
</TD>
</TR>
<TR>
<TD>
Andrew Rambaut's<BR> BEAST XML phylogeny format
</TD>
<TD>
See page 9 of PDF of BEAST manual at<BR>
<A HREF="http://evolve.zoo.ox.ac.uk/beast/">
<CODE>http://evolve.zoo.ox.ac.uk/beast/</CODE></A>
</TD>
<TD>
An XML format for phylogenies is
briefly described there.
</TD>
</TR>
<TR>
<TD>
treeml
</TD>
<TD><A HREF="http://www.nomencurator.org/InfoVis2003/download/treeml.dtd">
<CODE>http://www.nomencurator.org/InfoVis2003/download/treeml.dtd</CODE></A><BR>
(see also example: )<BR>
<A HREF="http://www.cs.umd.edu/hcil/iv03contest/datasets/treeml-sample.xml">
<CODE>http://www.cs.umd.edu/hcil/iv03contest/datasets/treeml-sample.xml</CODE></A>
</TD>
<TD>Jean-Daniel Fekete's DTD<BR>
for a tree XML file</TD>
</TR>
</TABLE>
<P>
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.
<P>
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"):
<P>
<TABLE><TR><TD BGCOLOR=white>
<PRE>
,>>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)
</PRE>
</TD></TR></TABLE>
<P>
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 "<TT>></TT>"
characters (<TT>>>>>>>></TT>). When branches have branch lengths, they are
drawn with "-" characters (<TT>-------</TT>) and their
lengths on the screen are approximately proportional to the branch length.
<P>
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:
<P>
<DL COMPACT>
<DT>R <DD>("Rearrange"). This command asks for the number of a node which is to be
removed from the tree. It and everything to the right of it on the tree is to
be removed (by breaking the branch immediately below it). (This is also
everything "above" it on the tree when the tree grows upwards, but as the
tree grows from left to right on the screen we use "right" rather than
"above"). The command also
asks whether that branch is to be inserted At a node or Before a node.
The first will insert it as an additional branch coming out of an
existing node (creating a more multifurcating tree), and the second will insert
it so that a new internal node is created in the tree, located in the
branch that precedes the node (to the left of it), with the branch that is
inserted coming off from that new node. In both cases the program asks you
for the number of a node at (or before) which that group is to be inserted.
If an
impossible number is given, the program refuses to carry out the rearrangement
and asks for a new command. The rearranged tree is displayed: it will often
have a different number of steps than the original. If you wish to undo a
rearrangement, use the Undo command, for which see below.
<P>
<DT>. <DD> (dot) This command simply causes the current tree to be redisplayed. It is of
use when the tree has partly disappeared off of the top of the screen owing to
too many responses to commands being printed out at the bottom of the screen.
<P>
<DT>= <DD>(toggle display of branch lengths). This option is available whenever
the tree has a full set of branch lengths. It toggles on and off whether
the tree displayed on the screen is shown with the relative branch lengths
roughly correct. (It cannot be better than roughly correct because the
display is in units of length of whole character widths on the screen). It
does not actually remove any branch lengths from the tree: if the tree
showing on the screen seems to have no branch lengths after use of the "="
option, if it were written out at that point, it would still have a full
set of branch lengths.
<P>
<DT>U <DD>("Undo"). This command reverses the effect of the most recent
rearrangement, outgroup re-rooting, or flipping of branches. It returns to the
previous tree topology. It will be of great use when rearranging the tree, and
when one makes a mistake, it permits you to
abandon the new one and return to the previous one without remembering its
topology in detail. Some operations, such as the simultaneous removal of
lengths from all branches, cannot be reversed.
<P>
<DT>W <DD>("Write"). This command writes out the current tree onto a tree output
file. If the file already has been written to by this run of Retree, it will
ask you whether you want to replace the contents of the file, add the tree to
the end of the file, or not write out the tree to the file. It will also
ask you whether you want the tree to be written out as Rooted or Unrooted. If
you choose Unrooted, it will write the outermost split of the tree as a
three-way split with the three branches being those that issue from one of
the nodes. This node will be the left (upper) interior node which is next
to the root, or the other one if there is no interior node to the left (above)
the root. The tree
is written in the standard format used by PHYLIP (a subset of the
Newick standard), in the Nexus format, or in an XML tree file format.
A normal PHYLIP tree
is in the proper format to serve as the
User-Defined Tree for setting up the initial tree in a subsequent run of the
program. However, some programs also require a line in the tree input
file that gives the number of trees in the file. You may have to add this
line using an editor such as <TT>vi</TT>, <TT>Emacs</TT>, Windows
<TT>Notepad</TT>, or MacOS's <TT>Simpletext</TT>.
<P>
<DT>O <DD>("Outgroup"). This asks for the number of a node which is to be the
outgroup. The tree will be redisplayed with that node
as the left descendant of the root fork. Note that it is possible to
use this to make a multi-species group the outgroup (i.e., you can give the
number of an interior node of the tree as the outgroup, and the program will
re-root the tree properly with that on the left of the bottom fork).
<P>
<DT>M <DD>("Midpoint root"). This reroots a tree that has a complete set of
branches using the Midpoint rooting method. That rooting method finds the
centroid of the tree -- the point that is equidistant from the two
farthest points of the tree, and roots the tree there. This is the point
in the middle of the longest path from one tip to another in the tree.
This has the effect
of making the two farthest tips stick out an equal distance to the
right. Note that as the tree is rerooted, the scale may change on the screen
so that it looks like it has suddenly gotten a bit longer. It will not
have actually changed in total length. This option is not in the menu
if the tree does not have a full set of branch lengths.
<P>
<DT>T <DD>("Transpose"). This asks for a node number and then flips the two
branches at that node, so that the left-right order of branches at that node is
changed. This also does not actually change the tree topology
but it does change the appearance of the tree. However, unlike the <TT>F</TT>
option discussed below, the individual subtrees defined by those branches do
not have the order of any branches reversed in them.
<P>
<DT>F <DD>("Flip"). This asks for a node number and then flips the entire
subtree at that node, so that the left-right order of branches in the whole
subtree is changed. This does not actually change the tree topology
but it does change the appearance of the tree. Note that it works differently
than the <TT>F</TT> option in the programs Move, Dnamove, and Dolmove, which
is actually like the <TT>T</TT> option mentioned above.
<P>
<DT>B <DD>("Branch length"). This asks you for the number of a node
which is at the end of a branch length, then asks you whether you want to
enter a branch length for that branch, change the branch length for that
branch (if there is one already) or remove the branch length from the
branch.
<P>
<DT>N <DD>("Name"). This asks you which species you want to change the
name for (referring to it by the number for that branch), then gives you the
option of either removing the name, typing a new name, or leaving the
name as is. Be sure not to try to enter a parentheses ("(" or ")"), a
colon (":"), a comma (",") or a semicolon (";") in a name, as those may
be mistaken for structural information about the tree when the tree file
is read by another program.
<P>
<DT>H, J, K, or L. <DD>These are the movement commands for scrolling the
"window" across a tree. H moves the "window" leftwards (though not beyond
column 1), J moves it down, K up, and L right. The "window" will
move 20 columns or rows at a time, and the tree will be redrawn in
the new "window". Note that this amount of movement is not a full screen.
<P>
<DT>C <DD>("Clade"). The C command instructs the program to print out
only that part of the
tree (the "clade") from a certain node on up. The program will prompt you for
the number of this node. Remember that thereafter you are not looking at the
whole tree. To go back to looking at the whole tree give the C command again
and enter "0" for the node number when asked. Most users will not want to use
this option unless forced to, as much can be accomplished with the window
movement commands H, J, K, and L.
<P>
<DT>+ <DD>("next tree"). This causes the program to read in the next tree in
the input file, if there is one.
<P>
<DT>? <DD>("Help"). Prints a one-screen summary of what the commands do, a few
words for each command.
<P>
<DT>X <DD>("Exit"). Exit from program. If the current tree has not yet been saved
into a file, the program will first ask you whether it should be saved.
<P>
<DT>Q <DD>("Quit"). A synonym for X. Same as the eXit command.
</DL>
<P>
The program was written by Andrew Keeffe, using some code from Dnamove, which
he also wrote.
<P>
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.
<P>
<HR>
<P>
<H3>TEST INPUT TREE FILE</H3>
<P>
<TABLE><TR><TD BGCOLOR=white>
<PRE>
((((((((Human,Chimp),Gorilla),Orang),Gibbon),(Barbary_Ma,(Crab-e._Ma,
(Rhesus_Mac,Jpn_Macaq)))),Squir._Mon),((Tarsier,Lemur),Bovine)),Mouse);
</PRE>
</TD></TR></TABLE>
</BODY>
</HTML>
|