Drawgram

Written by Joseph Felsenstein and James McGill.
© Copyright 1986-2014 by Joseph Felsenstein. All rights reserved. License terms here.

Drawgram interactively plots a cladogram- or phenogram-like rooted tree diagram, with many options including orientation of tree and branches, style of tree, label sizes and angles, tree depth, margin sizes, stem lengths, and placement of nodes in the tree. Particularly if you can use your computer to preview the plot, you can very effectively adjust the details of the plotting to get just the kind of plot you want.

To understand the working of Drawgram you should first read the Tree Drawing Programs web page in this documentation.

Java Interface

All Phylip programs will get Java interfaces in the 4.0 release. But under some operating systems there are currently serious problems with Drawgram, so it has received its Java interface early as part of the 3.695 bug fix release. We do not anticipate changing this Java interface substantially in the 3.7 release, but don't be surprised if we do.

This new Java interface supersedes the old character-mode menu interface. PHYLIP also contains versions of Drawgram and Drawtree that have the character-mode menu interface. We have kept these available because PHYLIP is used in many places as part of pipelines driven by scripts. Since these scripts do not usually invoke the preview mode of Drawgram, we have disabled the previewing of tree plotting in Drawgram in this release. Previewing is available in the version of Drawgram that has the interactive Java interface.

The Java interface is different from the previous character-mode menu interface; it calls the C code of Drawgram, which is in a dynamic library. Thus, after the previewing is done, the code producing final plot file should make plots that are indistinguishable from those produced by previous versions of Drawgram.

Java Menu Interface

The Java Drawgram Interface is a modern GUI. It will run only on a machine that has a recent version of Oracle Java installed. This is not a serious limitation because Java is freeware that is universally available.

When you start the Drawgram Java interface it looks similar to the following, which has been edited to generate the plot which follows:

It has all the usual GUI funtionality: input and output file selectors, drop down menu options, data entry boxes and toggles. "Preview" brings up a nearly WYSIWYG preview window that displays the Postscript plot created by the current settings (the fonts used in the previewing window are not the same, but use Serif, SansSerif, and Monospaced fonts that approximate the PostScript fonts that are used in the output plot):

Each time you select "Preview" another preview window is generated, so that multiple previews can be visible. This allows you to compare various display options. When the plot has been fine tuned, clicking "Create Plot File" writes the Postscript file that generated the last Preview to the plot file specified. Note that if there are multiple preview windows open, the most recent one is the one that shows how the tree in the final plot file will look, since it will be plotted using the most recent settings.

All the functionality in the Java GUI is the same as in the equivalent menu item in the character-mode menu interface. To ease the transition, we have kept the text in the Java GUI as close as possible to the description in the character-mode menu interface. So, for example, "S" in the old interface, which has the description "Tree style", has the counterpart "Tree style" in the new interface. The detailed explanations of each label are found below.

Command Line Interface

To understand the working of Drawgram and Drawtree, you should first read the Tree Drawing Programs web page in this documentation.

The Command Line Interface gives the user access to a huge collection of both display systems and output formats (some of them are historical curiosities at this point, but they still work so there is no reason to remove them). It can also be driven by scripting because it is a command line interface. But, as most users have little experience with command line systems, it is a bit daunting.

As with Drawtree, to run Drawgram you need a compiled copy of the program, a font file, and a tree file. The tree file has a default name of intree. The font file has a default name of "fontfile". If there is no file of that name, the program will ask you for the name of a font file (we provide ones that have the names font1 through font6). Once you decide on a favorite one of these, you could make a copy of it and call it fontfile, and it will then be used by default. Note that the program will get confused if the input tree file has the number of trees on the first line of the file, so that number may have to be removed.

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

Rooted tree plotting program version 3.695 Here are the settings: 0 Screen type (IBM PC, ANSI): ANSI P Final plotting device: Postscript printer V Previewing device: X Windows display H Tree grows: Horizontally S Tree style: Phenogram B Use branch lengths: (no branch lengths available) L Angle of labels: 90.0 R Scale of branch length: Automatically rescaled D Depth/Breadth of tree: 0.53 T Stem-length/tree-depth: 0.05 C Character ht / tip space: 0.3333 A Ancestral nodes: Centered F Font: Times-Roman M Horizontal margins: 1.65 cm M Vertical margins: 2.16 cm Y to accept these or type the letter for one to change

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 character 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 in the Java interface version, you might accept these default values and see what the result looks like.

You can resize the preview window, though you may have to ask the system to redraw the preview to see it at the new window size.

Once you are finished looking at the preview, you will want to specify whether the program should make the final plot or change some of the settings. The possible settings are listed below.

When you are ready to produce the final plot file, you should use the button "Create Plot File" (if you are using the Java interface) or you should type Y (if you are using the character-mode menu). In the Java-interface version, the name of the plot file has been set in the dialog box near the top of the Java window. It defaults to plotfile.ps. In the character-mode menu, the file name defaults to plotfile.

If there is already a file of that name, the program will ask you whether you want to Overwrite the file, Append to the file, or Quit (in the character-mode menu version it also gives the option of writing to a new file whose name you will be asked to supply.

THE OPTIONS

Below I will describe the options one by one; you may prefer to skip reading this unless you are puzzled about one of them.

Postscript Font

(In the character-mode menu version, selection F). Allows you to select the name of the font that you will use for the species names. For each of the plot file formats, this will either choose the Postscript font (if they allow Postscript fonts) or the built-in Hershey font that most closely matches it. Please understand that for plot file formats that lack Postscript font support, you will get one of our five Hershey fonts. The plot file types that allow Postscript fonts are (as far as we know): Postscript, FIG 2.0, and Idraw. In the preview of the tree in the Java-interface version, actual Postscript fonts are always used, but with any plot file type other then these three, the font is replaced by the closest Hershey font. The size of the characters in the species names is scaled according to the character heights you have selected in the menu, whether plotter fonts or the Hershey font are used. Note that for some plotter drivers (in particular FIG 2.0 and PICT) Postscript fonts can be used in the final plot file only if the species labels are horizontal or vertical (at angles of 0 degrees or 90 degrees). Otherwise Hershey fonts will be used.

Tree grows:

(In the character-mode menu version, selection H). Whether the tree grows Horizontally or vertically. The horizontal growth will be from left to right. This option is self explanatory. The other options are designed so that when we switch this direction of growth the tree still looks the same, except for orientation and overall size. This option is toggled, that is, when it is chosen the orientation changes, going back and forth between Vertical and Horizontal. The default orientation is Horizontal.

Style of the tree:

(In the character-mode menu version, selection S). There are six styles possible: Cladogram, Phenogram, Curvogram, Eurogram, Swoopogram, and Circular Tree. These are chosen by the letters C, P, V, E, S and O. These take a little explaining.

In spite of the words "cladogram" and "phenogram", there is no implication of the extent to which you consider these diagrams as being genealogies or phenetic clustering diagrams. The names refer to pictorial style, not your own intended final use for the diagram. The six styles can be described as follows (assuming a vertically growing tree):

Cladogram

nodes are connected to other nodes and to tips by straight lines going directly from one to the other. This gives a V-shaped appearance. The default settings if there are no branch lengths are designed to yield a V-shaped tree with a 90-degree angle at the base.

Phenogram

nodes are connected to other nodes and to other tips by a horizontal and then a vertical line. This gives a particularly precise idea of horizontal levels.

Curvogram

nodes are connected to other nodes and to tips by a curve which is one fourth of an ellipse, starting out horizontally and then curving upwards to become vertical. This pattern was suggested by Joan Rudd.

Eurogram

so-called because it is a version of cladogram diagram popular in Europe. Nodes are connected to other nodes and to tips by a diagonal line that goes outwards and goes at most one-third of the way up to the next node, then turns sharply straight upwards and is vertical. Unfortunately it is nearly impossible to guarantee, when branch lengths are used, that the angles of divergence of lines are the same.

Swoopogram

this option connects two nodes or a node and a tip using two curves that are actually each one-quarter of an ellipse. The first part starts out vertical and then bends over to become horizontal. The second part, which is at least two-thirds of the total, starts out horizontal and then bends up to become vertical. The effect is that two lineages split apart gradually, then more rapidly, then both turn upwards.

Circular Tree

This is a style introduced by David Swofford in PAUP*. The tree grows outward from a central point, being essentially a Phenogram style tree in polar coordinates. The tips form a 360-degree circle. The "vertical" lines run outward radially from the center, and the "horizontal" lines are arcs of circles centered on it.

You should experiment with these and decide which you want -- it depends very much on the effect you want.

Use branch lengths:

(In the character-mode menu version, selection B). Whether the tree has Branch lengths that are being used in the diagram. If the tree that was read in had a full set of branch lengths, it will be assumed as a default that you want to use them in the diagram, but you can specify that they are not to be used. If the tree does not have a full set of branch lengths then this will be indicated, and if you try to use branch lengths the program will refuse to allow you to do so. Note that when you change option B, the node position option A may change as well.

Angle of labels:

(In the character-mode menu version, selection L). The angle of the Labels. The angle is always calculated relative to a vertical tree, whether the tree is actually horizontal or vertical, if the labels are at an angle of 90 degrees they run parallel to direction of tree growth. The default value is 90 degrees. The option allows you to choose any angle from 0 to 90 degrees.

Scale of branch length:

(In the character-mode menu version, selection R). How the branch lengths will be recalculated into distances on the output device. Note that when branch lengths have not been provided, there are implicit branch lengths specified by the type of tree being drawn. 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.

Depth/breadth of the tree:

(In the character-mode menu version, selection D). The ratio between the depth and the breadth of the tree. It is initially set near 0.5, to approximate a V-shaped tree, but you may want to try a larger value to get a longer and narrower tree. Depth and breadth are described as if the tree grew vertically, so that depth is always measured from the root to the tips (not including the length of the labels).

Stem length/tree depth:

(In the character-mode menu version, selection T). The length of the sTem of the tree as a fraction of the depth of the tree. You may want to either lengthen the stem or remove it entirely by giving a value of zero.

Character ht/tip space:

(In the character-mode menu version, selection C). The Character height, measured as a fraction of the tip spacing. If the labels are rotated to a shallow angle, the character height will be automatically adjusted in hopes of avoiding collision of labels at different tips. This option allows you to change the size of the labels yourself. 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.

Ancestral nodes:

(In the character-mode menu version, selection A). Controls the positions of the ancestral (interior) nodes. This can greatly affect the appearance of the tree. The vertical positions (these descriptions assume a tree growing vertically) are not under your control except insofar as you specify the use or non-use of branch lengths. If you choose to change this option you will can choose a number methods in the selection box (in the Java-interface version of the program. In the character-mode menu version you will be asked:

Should interior node positions: be Intermediate between their immediate descendants, Weighted average of tip positions Centered among their ultimate descendants iNnermost of immediate descendants or so that tree is V-shaped (type I, W, C, N or V):

The five methods (Intermediate, Weighted, Centered, Innermost, and V-shaped) are different horizontal positionings of the interior nodes. It will be helpful to you to try these out and see which you like best. Intermediate places the node halfway between its immediate descendants (horizontally), Weighted places it closer to that descendant who is closer vertically as well, and Centered centers the node below the horizontal positions of the tips that are descended from that node. You may want to choose that option that prevents lines from crossing each other.

V-shaped is another option, one designed, if there are no branch lengths being used, to yield a v-shaped tree of regular appearance. At the moment it can give somewhat wierd trees; we intend to make it better in the next release. With branch lengths it will not necessarily make the tree perfectly V-shaped. "Innermost" is the most unusual option: it chooses a center for the tree, and always places interior nodes below the innermost of their immediate descendants. This leads to a tree that has vertical lines in the center, like a tree with a trunk.

If the tree you are plotting has a full set of lengths, then when it is read in, the node position option is automatically set to "intermediate", which is the setting with the least likelihood of lines in the tree crossing. If it does not have lengths the option is set to "V-shaped". If you change the option which tells the program whether to try to use the branch lengths, then the node position option will automatically be reset to the appropriate one of these defaults. This may be confusing if you do not realise that it is happening.

Margins:

(In the character-mode menu version, selection M). The horizontal and vertical margins in centimeters. You can enter new margins (you 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 a future release I hope to do so.

Final plot file type

(in the character-mode menu version, menu selection P). This allows you to choose the Plotting device or file format. We have discussed the possible choices in the draw programs documentation web page. In the Java version they are Postscript, PICT, PCL, Windows BMP, FIG 2.0, Idraw, VRML, or PCX. In the character-mode menu version there is a longer list of plot file types.

#

(character-mode menu version only) The number of pages per tree. Defaults to one, but if you need a physically large tree you may want to choose a larger number. For example, to make a big tree for a poster, choose a larger number of pages horizontally and vertically (the program will ask you for these numbers), get out your scissors and paste or tape, and go to work.

O

(character-mode menu version only) This is an option that allows you to change the menu window to emulate an ANSI terminal or an IBM PC terminal. Generally you will not want to change this.

I recommend that you try all of these options (particularly if you can preview the trees). It is of particular use to try combinations of the style of tree (option S) with the different methods of placing interior nodes (option A). You will find that a wide variety of effects can be achieved.

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