RETREE -- Interactive Tree Rearrangement

RETREE reads in a tree, or allows the usur to construct one, and displays this tree on the screen. The user then can specify how the tree is to be rearraranged, rerooted or written out to a file.

The input trees are in one file ( with file identifier "intree"), the output trees are written into another ("outtree": note the two t's). 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.

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 be used to write out a tree file in the Nexus format used by Paup and MacClade.

This program is compatible with fewer computer systems than the other programs in PHYLIP. It can be adapted to PCDOS systems or to any system whose screen or terminals emulate DEC VT52 or VT100 terminals (such as, for example, Zenith Z19, Z29, and Z49 terminals, Telnet programs for logging in to remote computers over a TCP/IP network, VT100-compatible windows in the X windowing system, and any terminal compatible with ANSI standard terminals). For any other screen types, there is a generic option which does not make use of screen graphics characters to display the nucleotide states. This will be less effective, as the nucleotide states will be less easy to see when displayed. file.

The user interaction starts with the program presenting a menu. The menu looks like this:

Tree Rearrangement, version 3.5c

Settings for this run:
  U      Initial tree (arbitrary, user, specify)?  User tree from tree file
  N      Use the Nexus format to write out trees?  No
  0           Graphics type (IBM PC, VT52, 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, which must be a rooted 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 difficult 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 terminals 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 (Nexus) option allows the user to specify that the tree files that are written by the program will be in the Nexus format defined by David Swofford and Wayne 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). This option is off by default.

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, which looks like this:

NEXT? (Options: R . = U W O M T F B N H J K L C + ? X Q) (? for Help)
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:
R    ("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).   The  command
    also  asks  for  the  number  of  a  node  below  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.

 .    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.

=   (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.

U     ("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  a  rearrangement proves worse than the preceding one -- 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.

W    ("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 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 New Hampshire standard) or in the Nexus  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.

O    ("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 bottom 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.

M    ("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 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 ahas suddenly gotted 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.

T    ("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 F option
    below the individual subtrees defined by those branches  do  not  have  any
    further branches reversed in them.

F    ("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
    F option in the programs MOVE, DNAMOVE, and DOLMOVE, which is actually like
    the T option mentioned below.

B    ("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.

N    ("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.


H, J, K, or L.    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".

C    ("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.

+    ("next tree").  This causes the program to read in the next  tree  in  the
    input file, if there is one.

?    ("Help").  Prints a one-screen summary of what  the  commands  do,  a  few
    words for each command.

X    ("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.

Q    ("Quit").  A synonym for X.  Same as the eXit command.

ADAPTING THE PROGRAM TO YOUR COMPUTER AND TO YOUR TERMINAL

As we have seen, the initial menu of the program allows you to choose among four screen types (PCDOS, Ansi, VT52 and none). If you want to avoid having to make this choice every time, you can change some of the constants at the beginning of the program to have it initialize itself in the proper way. At the beginning of the program are three constants that determine which kind of screen graphics the program will use. They are ibmpc0, vt520, and ansi0. In the distribution version of the programs, ansi0 is set to "true" and the others to "false", in the statements:
#define ibmpc0          false
#define ansi0           true
#define vt520           false
so that the version will work with ANSI compatible terminals.

On the other hand if you have a terminal compatible with DEC's VT52, but not with the ANSI terminal, you should change the constant ansi0 to "false" and vt520 to "true". If you have instead a terminal which is compatible with IBM PC graphics, you should set the constant "ibmpc0" to "true" and the others to "false". If your terminal is compatible with none of these, you will have to set the constants all "false", in which case 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 program was written for me by Andrew Keeffe, using some code from DNAMOVE.

Below is a test tree file, but we cannot show the output it generates because of the interactive nature of the program.


----------------- TEST INPUT TREE FILE ---------------------------
((((((((Human,Chimp),Gorilla),Orang),Gibbon),(Barbary_Ma,(Crab-e._Ma,
(Rhesus_Mac,Jpn_Macaq)))),Squir._Mon),((Tarsier,Lemur),Bovine)),Mouse);