(c) Copyright  1990-1993  by  Joseph  Felsenstein  and  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.

     DRAWTREE interactively plots an unrooted tree diagram, with  many  options
including  orientation  of  tree  and  branches, label sizes and angles, margin
sizes.  Particularly if you can use your computer or terminal screen to preview
the  plot,  you  can very effectively adjust the details of the plotting to get
just the kind of plot you want.

     As with DRAWGRAM, to run DRAWTREE you need a compiled copy of the program,
a  font  file,  and  a tree file.  On running the program, you will be asked to
choose the plotter type for the final output.  Then you will be asked to choose
the  graphics  screen  type  for  the  previewing  (or  N  if there is to be no
previewing).  The various options have been  discussed  in  the  document  file
common to both these programs.

     Once these choices have been made you will see the  central  menu  of  the
program, which looks like this:



     These are the settings that control the appearance of the tree, which  has
already  been  read  in.   You can either accept these as is, in which case you
would answer Y to the question and press the Return or Enter key,  or  you  can
answer  N  if you want to change one, or simply type the digit corresponding to
the one you want to change (if you answer N it will just  immediately  ask  you
for that number anyway).

     For a first run, particularly if previewing is available, you might accept
these default values and see what the result looks like.  The program will then
tell you it is about to preview the tree and ask you to press Return  or  Enter
when  you  are  ready  to  see this (you will probably have to press it twice).
When you are through looking at the previewed tree on your  screen,  you  press
Return  or Enter again.  The program will then ask you if the tree is now ready
to be plotted.  If you answer Y (for Yes) the program will usually write a plot
file  (with  some  plot  options it will draw the tree on the screen).  Then it
will terminate.

     But if you answer N (for No) it will go back to the above menu, allow  you
to  change  more  options, and go through the whole process again.  The easiest
way to learn the meaning of  the  options  is  to  try  them,  particularly  if
previewing is available.  Below I will describe them one by one; you may prefer
to skip reading this unless you are puzzled about one of them.


                                  THE OPTIONS

     The first option (1) is whether  the  tree  will  use  the  branch  length
information.   If  a full set of branch lengths is not present in the tree file
this will be indicated, and you then cannot  change  this  option.   If  branch
lengths are not used, all branches will be given equal lengths of 1.0.

     The second (2) option shows the angle of the labels.   Initially  a  Fixed
label  angle  of  0.0  degrees will be used.  If you want to change the way the



labels are drawn, the program will offer you a choice  between  Fixed,  Radial,
and  Along  as  the ways the angles of the labels are to be determined.  If you
choose Fixed (the default), you will be asked if you want labels to be at  some
fixed  angle,  between  90.0  and -90.0 degrees, you can specify that.  You may
have to try different angles to find one that keeps the labels from  colliding:
I  have  not  guarded against this.  However there are additional options.  The
other two systems for determining angles of labels are  Radial  (R)  and  Along
(A).   Radial  indicates  that the labels are all aligned to as to point toward
the root node of the tree.  Along aligns them to have the  same  angle  as  the
branch  connected  to that tip.  This is particularly likely to keep the labels
from colliding, but it may give a misleading impression that the  final  branch
is  long.   Note that with the Radial option, if you do not like the point from
which the labels appear to radiate, you might try re-rooting the  tree  (option
7).

     The third (3) option controls the rotation of the tree.  This is initially
90.0  degrees.   The  angle is read out counterclockwise from the right side of
the tree, so that increasing this angle will rotate the tree  counterclockwise,
and  decreasing  it  will  rotate  it  clockwise.  The meaning of this angle is
explained further under option (4).  As you rotate  the  tree,  the  appearance
(and  size)  may  change, but the labels will not rotate if they are drawn at a
Fixed angle.

     The fourth (4) option is the angle through  which  the  tree  is  plotted.
This is by default 360.0 degrees.  The tree is in the shape of an old-fashioned
hand fan.  The tree fans out from its root node, each  of  the  subtrees  being
allocated  part of this angle, a part proportional to how many tips the subtree
contains.  If the rotation of the tree is (say) 90.0 degrees (the default under
option  (3)),  the  fan starts at +270 degrees and runs clockwise around to -90
degrees (i.e., it starts at the bottom of the plot and  runs  clockwise  around
until  it returns to the bottom.  Thus the center of the fan runs from the root
upwards (which is why we say it is  rotated  to  90.0  degrees).   By  changing
option  (3)  we can change the direction of the fan, and by changing option (4)
we can change the width of the fan without changing its center  line.   If  you
want  the  tree  to  fan out in a semicircle, a value of a bit greater than 180
degrees would be appropriate, as the tree will not completely fill the fan.

     The fifth option (5) is  whether  the  tree  angles  will  be  iteratively
improved.   This  is  a  rather arbitrary process intended to adjust them to be
less overcrowded in some regions of the plot.  It depends on a rather arbitrary
"enthusiasm  constant"  that you can adjust, reducing it if the tree angles are
changed so much by the iteration process that they tangle, or increasing it  if
you see little result from the iterative improvement.  If iterative improvement
is on (it is by default) then option (9) specifies the value of the  enthusiasm
constant.

     The sixth option (6) specifies how the branch lengths will  be  translated
into  distances  on  the output device.  Note that when branch lengths have not
been provided, there are implicit branch  lengths  of  1.0  per  branch.   This
option  will  toggle  back  and  forth  between  automatic adjustment of branch
lengths so that the diagram will just fit into the margins, and you  specifying
how many centimeters there will be per unit branch length.  This is included so
that you can plot different trees to a common scale, showing  which  ones  have
longer  or  shorter  branches than others.  Note that if you choose too large a
value for centimeters per unit branch length, the tree will be so big  it  will
overrun  the  plotting  area  and  may  cause failure of the diagram to display
properly.  Too small a value will cause the tree to be a nearly invisible dot.

     The seventh option (7) specifies the horizontal and  vertical  margins  in
centimeters.   You  can  enter  new margins (you must enter new values for both
horizontal and vertical margins, though these need not be  different  from  the



old  values.   For  the  moment  I  do  not allow you to specify left and right
margins separately, or top and bottom margins separately.  In the next  release
I  hope  to  do so, so that you can plot several trees on one plot, or plot one
tree across several pieces of paper.

     The eighth option (8) is the character height, measured as a fraction of a
quantity  which  is the horizontal space available for the tree, divided by one
less than the number of tips.  You need not worry about exactly what  this  is:
you  can always change the value (which is initially 0.3333) to make the labels
larger or smaller.  On output devices where line thicknesses can be varied, the
thickness  of  the tree lines will automatically be adjusted to be proportional
to the character height, which is an additional reason you may want  to  change
character height.

     The ninth option (9), if iterative improvement is turned on as  it  is  by
default,  specifies  the  value  of  the  "enthusiasm  constant"  for iterative
improvement, which we discussed above (see item 5).  If  iterative  improvement
is not turned on, the ninth option is whether the angles will be "regularized".
Regularization is on by default.  It takes the angles of  the  branches  coming
out  from  each  node,  and  changes them so that they are "rounded off".  This
process (which I will not fully describe) will make the lines vertical if  they
are  close  to vertical, horizontal if they are close to horizontal, 45 degrees
if they are close to that, and so on.  It will lead to a tree in  which  angles
look  very regular.  You may or may not want that.  If you are unhappy with the
appearance of the tree you could try rotating it slightly (option  3)  as  that
may  cause some branches to change their angle by a large amount, by having the
angles be "rounded off" to a different value.

     If the printer is a Laserwriter or other  Postscript  printer,  the  tenth
menu  item (10) appears, and asks you for the name of the font to be used.  The
default is the Hershey stroke font provided in the font  file.   You  can  also
specify  any  other  font  available to you on the Laserwriter.  However I have
only been able to get Courier, Times-Roman, and Helvetica to work on mine.   We
hope  in the future to provide font choices for other printers as well, such as
Hewlett-Packard Laserjets, but at the moment we can only do it  for  Postscript
printers as the others cannot print text at an arbitrary angle.

     I recommend that you try all of these options  (particularly  if  you  can
preview  the  trees).   It  is  of particular use to try trees with and without
regularization (option number 5), plotted at different angles (option number 3)
and  with  fan  sizes  360 degrees or less (option 4).  You will find that wide
variety of effects can be achieved.

     I would appreciate suggestions for improvements in DRAWTREE, but please be
aware  that  the  source  code  is  already very large and I may not be able to
implement all suggestions.