iconPhylodendron

an application for phylogenetic tree drawing


version 0.7, beta
October 1997

Copyright 1997 by D.G. Gilbert
email: software@bio.indiana.edu

Phylodendron is an application for drawing phylogenetic trees, used in evolutionary biology. It will read tree data in New Hampshire (Newick) format, then display graphical views of the phylogenetic tree. Various options allow you to modify, adorn and edit the tree. Standard application functions to save, print, edit and manage preferences are included. This program will not estimate nor produce the tree data. For that, software such as Phylip, Clustal W, and others may be used. Phylodendron is available at

ftp://iubio.bio.indiana.edu/molbio/java/apps/trees/
http://iubio.bio.indiana.edu/soft/molbio/java/apps/trees/

Please read the help document and "readme" file for details on how to fetch and install the application on your computer.

Phylodendron is written as a Java application. This means that it will run on most personal computers and workstations as a standard program. This application is an enhancement of the Mac Hypercard program "Tree Draw Deck" released by the author in 1990.

One problem in using this program is that Java is still in preliminary stages. You currently must fetch and install a Java runtime system to use it. This can be obtained freely on the Internet. See for example <http://www.javasoft.com/nav/download/index.html>

Developers will find the source code in the iubio:/molbio/java/source folders. These files are not needed for running the program. Phylodendron is built on the beginnings of an application framework for Java, which may make it easier to develop new applications.



Contents





Fetching and Installing

Perhaps the most annoying problem to me with this software is the complexity of fetching and installing it. If you use Netscape or other Java enabled Internet browsers, you can use a Java applet just by clicking your way to a WWW page that has one embedded. This software is more complex than is suitable for an applet; for one thing it reads and writes files on your computer like any average program, but which applets cannot yet do. I believe that over the coming year, advances in Java technology will make this fetch/install problem all but disappear.

Fetching

The current state of Java applications on computer systems means that you will need to fetch a Java runtime system as well as the files for this specific application. If you have other Java applications on your computer (not applets that run within an http browser like Netscape), you may already have the Java runtime system needed.

Phylodendron is available over the Internet at

ftp://iubio.bio.indiana.edu/molbio/java/apps/trees/
http://iubio.bio.indiana.edu/soft/molbio/java/apps/trees/

The essential files and folders that make up this application are
For Macintosh and MSWindows users, you will find a (large) package that includes all files needed for this application and the Java runtime system. Though this runs to about 5 megabytes for the Macintosh version, the bulk of this code is the runtime system that may well be used for other Java applications.

Macintosh users will find these files in the archive file phylodendron.hqx. MSWindows users will find program files in the archive file phylodendron.zip. Unix and others will find just the program files in the archive file phylodendron.tar.gz. You likely will need to fetch (see below) and install the Java runtime for your system. Newer operating systems (MacOS 8, Warp, Solaris 2.6) include java runtime systems; though you may want to update them to current versions.


As I've learned with other multi-platform applications that I make available to the bioscience community, there are difficulties involved in the time it takes me to update multiple archives for different computer systesm. The simplest way for me to distribute and update this software is to provide it as separate files, e.g., the pictures and documents and p-code files, and to update each one individually as needed. For example, I update this document after I've already produced some of the archive files. So I will also provide the most current version of this software in its un-archived form. You may find the most current versions by looking in the all systems/ folder. Within that, the folder called local/ has those items specific to each computer system. With a bit more programming effort, I hope to have the application do some of its own updating as needed (see below Updates).

This current release is based on the Java Developer Kit 1.0.2. To run it, you should have installed the runtime compatible with JKD1.0.2. This can be found through Javasoft, and at various mirror sites around the world.
http://www.javasoft.com/products/jdk/1.0.2/index.html

For Java runtimes for various operating systems, see
http://www.javasoft.com/products/jdk/jdk-ports.html

A newer Java version, 1.1, became available in 1997. I will provide an update to this program with this new Java version, perhaps by the start of 1998. For now, Java version 1.0.2/1.0.3 runtimes are needed to run the application.


Installing

The program is installed as follows. On all systems, the following files specific to the application should be in one folder:
TreeApp.jcode
data/ folder
TreeApp-doc.html

Then the Java runtime system accessory files need to be placed as per your computer system.


Installing for MacOS


There are various Java runtime systems available for Macintosh. For development, I use one from Metrowerks. But for general use, the Macintosh Runtime Java (MRJ) produced by Apple Computer is the easiest, and in many ways the best. It still has some annoying bugs, as do all Java runtime systems.

1. Keep in the same folder whereever you prefer, the application Phylodendron, the TreeApp.jcode Java class archive, and the data folder.

2. Use the MRJ installer from Apple Computer to install this Java runtime software. If you have MacOS 8, this is included as part of the OS. However, at the first release of MacOS 8, the MRJ included is an early, slower version. You should upgrade to the MRJ 1.5 release.

3. Put the contents of "->System/Extensions" into System Folder:Extensions:

DClap-MRJ-68K.shlb (for 68K macs)
DClap-MRJ-PPC.shlb (for PowerPC macs)
These extensions enable the link from this app to Netscape and other Internet software.

4.Install the Internet Config application, if you don't have it. MacOS 8 includes this program. This free, widely used program enables links among Internet aware applications. This application uses it to call others like Netscape to open network links and the help document.

Installing for MSWindows

The file names used are long file names. It has only been tested with MSWin32 (Win95/NT), and may not work with Win3. When you unzip the archive file, use a current unzipper that preserves long file names.

1. Keep in the same folder whereever you prefer, the program batch file TREEAPP.BAT, the Phylodendron.jcode Java class archive, and the data folder.

2. Install a Java Runtime system for MS Windows. Install it in a standard location, which will be entered in the TREEAPP.BAT file. A recommended Java runtime is found at http://www.javasoft.com/products/jdk/1.0.2/installation-win32-x86.html You may want to install this in the same folder as you store SeqPup (and other java applications). Or you may want to install this in a general MSWindows folder, perhaps C:\WINDOWS\JAVA. I don't know of a prefered location yet on MS Window systems for Java runtime files. You will need to edit the batch file (step 3) to account for this location.

3. Edit the TREEAPP.BAT file to make the path names match the file locations on your computer.

          set base=\temp\java
          set appclass=%BASE%\treeapp\TreeApp.jcode
          set java=%BASE%\java

These three lines should be matched to folders on your system. The base path locates Java runtime and the Phylodendron data files. If you want, these can be in separate folders; in that case, remove the BASE specifier for appclass and java path settings.

The distribution zip archive containes application files in the path \TEMP\JAVA\treeapp\ and Java runtime files in the path \TEMP\JAVA\java\. If you unzip it with those names preserved, then you shoud be able to run the program from the batch file TREEAPP.BAT.

For the application to link properly to Netscape or other Internet browser, you may need to edit the preferences file. You can do this from within the application; see the Options/Edit Framework ... Menu. Or you can edit the file dclap.ini which will be created in the \java\ folder. In either case, you want to enter the variable name user.openurl= then the full path to your browser to be sure that it works properly. This path may well be the same on your system as mine, which is as follows. Note the quote marks (due to space in name) and the double backslashes \\ which are required to insert one \.

user.openurl="C:\\Program Files\\Netscape\\Navigator\\Program\\netscape.exe"


If you use the Edit prefs menu, after editing close the window. You should be prompted to save changes; do so.


Installing for Unix and others

Besides the application files, you will need a Java runtime system for your operating system. Some of these are listed at http://www.javasoft.com/products/jdk/jdk ports.html.

For Sun Solaris computers (SPARC and Intel):
http://www.javasoft.com/products/jdk/1.0.2/installation-solaris2.html

For IBM Warp on Intel, IBM AIX, and MS Windows 3.1 computers:
http://www.ibm.com/Java/tools/jdk.html
http://ncc.hursley.ibm.com/javainfo/hurindex.html

For DEC Digital Unix computers:
http://www.unix.digital.com/products/internet/jdk102_main.html

For various Linux on Intel systems:
http://www.blackdown.org/java-linux.html

For Silicon Graphics IRIX computers:
SGI has hidden their Java runtime version 1.0.2. Sorry.
contact SGI for more details at http://www.sgi.com/


Whatever runtime system you install, it must be called with the TreeApp.jcode file. See the file treeapp which is a small shell script to do this on Unix. Edit that to suit your system needs.

You need to define the user.openurl= variable to find your Netscape or equivalent. You can do this from within the application; see the Options/Edit basic prefs... Menu. Or edit the file ~/.dclaprc directly to enter such a line. The variable line for my unix system is

user.openurl=/usr/local/bin/netscape

Also, you might instead use a shell script (like the "netscape.sh" included). If you rename that to netscape, edit it to suit, and put in the folder with TreeApp.jcode file, it may take the place of editing the preference file.

Currently Java 1.0.3 does not understand printing (a slight oversight due to the Xwindow history of Java). The current Print command just sends postscript of a drawing to the user.print file.




Genesis of Phylodendron

I did not set out to write a good phylogenetic tree drawing application. Perhaps, and I hope, this application will compare favorably to other tree drawing programs. My motives behind this were to test if the Java language was at a stage where one could write robust, complex applications with it.

Joe Felsenstein has provided for many years the excellent phylogenetic analysis package PHYLIP that most of you are likely familiar with. While most of the applications in this package don't require any fancy user-interface, the drawing programs DRAWTREE and DRAWGRAM were, to my mind, just begging for a better user interface for Macintosh users to see and print trees. In 1990, I took Joe's code and stuffed it into a Mac Hypercard application within a few weekends, producing Tree Draw Deck.

This Hypercard version proved useful to people, but wasn't a complete drawing application. It had shortcomings in saving and editing files. An attempt of mine to overcome this a few years later wasn't successful. With enough time..., but I was fighting Hypercard's limitations then.

One of the very nice features of Hypercard is that one can put easy-to-use faces onto programs quickly. Since the decline of Hypercard and Macintoshes, I've missed this form of rapid application development, and haven't yet found an equivalent. With some more work, I hope that Java can take its place. Those of you who have seen Tree Draw Deck should note similarities with the "About Phylodendron" window.

I do have high hopes now for Java as an Internet Hypercard. Phylodendron, and its companion test app LoopDloop [java], gave me a feeling that Java is ready for complex application development, and it has the potential for rapid application development with a good app framework. The two programs I have now in it are both small, MacDraw style scientific drawing apps. They share about 60 - 70% of their code. Improvements in one will lead to improvements in the other in many cases, and that also will hold for future applications written to this framework. I hope to provide at least one application for the FlyBase drosophila database and at some point a version of the sequence analysis application SeqPup in this Java framework.

This framework,dubiously named DCLAP, was started with the NCBI toolkit, a cross platform C toolkit on which Entrez, Sequin and other apps from NCBI are written (thank you Jonathan Kans and colleages at NCBI for this wonderful, free toolkit). On top of this toolkit I wrote a C++ framework which is meant to handle much of the basic application chores such as document opening, saving, doc and window management, menu and command management, etc. With the advent of Java as a C++-like language that has broad support and funding of tools from the commercial sector, but which also is available in free form at its basics, it looked like a good underpining for rapid, cross-platform app development. However, neither NCBI toolkit nor Java nor other sources provide the kind of application framework freely that makes it quick and easy to produce robust, easy to use, full featured applications for the biosciences. As I write new applications, I aim at improving such a framework so that the next application can be written more quickly than the last. The source code for this framework, in C++ and now its beginnings in Java, is available freely to others for scientific application development. The current Java version of DCLAP is preliminary, and will change significantly when converted to JDK version 1.1, and has a ways to go for being a good app framework. However I find it now very helpful in producing new applications, and hope that other programmers may also find it useful.

Developers will find the source code for this application and others in the iubio:/molbio/java/source folders.

Searching for a name for an application is always a chore for programmers. A memorable name and cute icons are de rigueur for successful software these days; functionality can be secondary. I didn't want another variation on treedraw, drawtree, treetool, etc. Phylodendron just struck me as a natural for this sort of software. The cute icon was modelled by a pretty Philodendron plant here. The working name has been TreeApp; you will find that name used some places (e.g., the TreeApp.zip file).





Acknowledgements

This work rests in a large part on the tree drawing algorithms of Joseph Felsenstein and Chris Meacham, as part of the Phylogeny Inference Package (PHYLIP). These are copyrighted 1986 and 1990 by those authors. Description of tree styles here are based on documentation written by Joseph Felsenstein. Problems and shortcomings of this software are the responsibility of Don Gilbert, to who any correspondence regarding problems should be addressed.


Help

Program help is available from this document. Typically the program documentation that I write gets done last and doesn't receive the effort that it deserves (because typically I haven't enough time to finish the software either, which is written in my spare, unpaid time). The help that I can offer to individual questions may be very limited. But please do send your questions and comments by e-mail to the address "software@bio.indiana.edu", and these will be taken into account for future updates.

Updates and source Internet links

This software is testing use of Java network methods to offer easy access to software source and updates. There are two hyperlink "buttons" on the main splash-screen. These connect by Internet to the home archive for the software. The Updates button (on the "version" label) will check whether the software version you have is out-of-date.

Both of these options, and the help command, link through an accessory program for opening URLs (Internet universal resource locators). Typically this accessory will be Netscape or the like software. In order to use this accessory program properly, it must be configured on your computer.

For Macintosh users, this involves installing Internet Config, a small free program used by many other Internet applications. Internet Config must be installed on your system, and you need to configure it to specify Helpers for at least the following protocols: ftp, file, http, mailto.
These helpers may all be Netscape.

For Unix users, this involves setting the preference called "user.openurl" to the proper path to reach Netscape or other Internet applications. See also the small shell script that can be used to customize this function.

For MsWindows users, this also involves setting the preference called "user.openurl" to the proper path to reach Netscape or other Internet applications.

Usage

This program is designed to work as a standard application on your computer. It has a menu of primary commands, including File, Editing, Options and Windows.

Front window

The opening window, titled "About Phylodendron", includes short-cut hyperlink buttons (after its HyperCard progenitor Tree Draw Deck). If you click on one of the tree drawings, you will be prompted to open a data file, then a drawing of that style will be done. If you click on the Help button, the help document (this) will be displayed (if configured properly). If you click on the source or version buttons, those Internet links will be opened (see below).


Opening tree files

Use the File/Open menu command to read in and display a tree. The current version understands New Hampshire format trees, including the Clustal-W variant that appends bootstrap values, and internal comments in [brackets]. See the samples folder to find sample data files. Many phylogeny applications, including Phylip package, ClustalW and others produce this tree data format.

Saving documents

The initial release supports Postscript and PICT output formats. It lacks a data format that would let you save and re-read the drawing, however. PICT format is a compact vector drawing format that many drawing applications will read and allow you to further edit the drawing. For PICT output on a Macintosh, the current release does not set the file type as PICT. See the accessory PICT-Typer Mac program to do this.


Tool palette

The tool palette includes drawing manipulation tools.
arrow the primary selection tool, for selecting tree, nodes, and other objects. Also for moving objects.

movenodeshift a node within a tree. This tool lets you change node positions at the same branching level. This changes the overall format of the tree without affecting the meaning of the dendrogram. When you select this tool, use the mouse to select a node first, then drag that node toward other nodes. While you drag, a rectangle will hilight to show which other nodes are at the same level and capable of interchange with the selected node. Node shifting for unrooted trees uses a smaller highlit box than for rooted. For rooted trees, you may use a shift-key plus this tool to have the smaller highlit box and avoid some node conflicts.

grow

resize an object. Use the mouse cursor after selecting this tool to frame the rectangle which will contain the tree. The tree will be drawn to fit that rectangle.

The other basic shape drawing tools are functional. They may not be particularly useful in the current release.



Tree styles

The Options/Tree Style... Menu allows choices in the drawing style for the overall tree, including unrooted (tree diagram) versus rooted, and other options.

Tree style:

This offers the choices of Tree diagram (unrooted), or the rooted forms of Cladogram, Phenogram, Curvogram, Eurogram and Swoopogram. The styles are described as:

treediag Tree diagram -- draws an unrooted tree diagram.

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

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 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 Eurogram -- so-called because it is a version of cladogram diagram popular in Europe (name courtesy of David Maddison). Nodes are connected to other nodes and to tips by a diagonal line that goes outward 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 Swoopogram -- this option (suggested by James Archie), 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.


Tree growth:

Horizontal or vertical - specifies orientation of a tree.

Regular - will make an unrooted tree have regular angles. This 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.

Use node lengths - if a tree has branch lengths, these may be use to specify the length of each node, or not.



Node position:

For rooted trees, this affects the positioning of nodes. It controls the horizontal positions (for a tree growing vertically) of the nodes and can greatly affect the appearance of the tree. Try them to see what suits your preference for a particular tree.

Intermediate places a node halfway between its immediate descendants.

Weighted
places it closer to that descendant who is closer vertically as well.

Centered
centers the node below the horizontal positions of the tips that are descended from that node.

V-shaped is designed to yield a v-shaped tree of regular appearance,, if there are no branch lengths being used. With branch lengths it will not necessarily do so.

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



Node style

The Options/Node style... Dialog offers you a choice of how to display any selected nodes, or all nodes if none are selected. With this dialog you can highlight sections of a tree using styles.

Adornments -
Circle - append a circle to the node.
Box - append a box to the node.
Hide - make invisible the node, and all descendant nodes.
Fill symbol - fill the circle or box
No label - don't draw a label for this node.
Future releases may offer more node adornment symbols.

Font style - choose the font, font size, font face, and color for selected nodes. Currently the color also is applied to branch lines and adornments as well as font [future releases may separate this].

Show node comments - display any comment field associated with a node. Comments are entered in a tree file in [brackets].

Number inner nodes - put a number beside each inner node.




Tree Data


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

The New Hampshire Standard for representing trees in computer-readable form makes use of the correspondence between trees and nested parentheses, noticed in 1857 by the famous English mathematician Arthur Cayley. If we have this rooted tree:

                        A                   D
                         \           E     /
                          \    C    /     /
                           \   !   /     /
                            \  !  /     /
                        B    \ ! /     /
                         \     o      /
                          \    !     /
                           \   !    /
                            \  !   /
                             \ !  /
                              \! /
                               o
                               !
                               !

then in the tree file it is represented by the following sequence of printable characters, starting at the beginning of the file:

(B,(A,C,E),D);

The tree ends with a semicolon. Everything after the semicolon in the input file is ignored, including any other trees. The bottommost node in the tree is an interior node, not a tip. Interior nodes are represented by a pair of matched parentheses. Between them are representations of the nodes that are immediately descended from that node, separated by commas. In the above tree, the immediate descendants are B, another interior node, and D. The other interior node is represented by a pair of parentheses, enclosing representations of its immediate descendants, A, C, and E.

Tips are represented by their names. A name can be any string of printable characters except blanks, colons, semicolons, parentheses, and square brackets. In the programs a maximum of 30 characters are allowed for names: this limit can easily be increased by recompiling the program and changing the CONSTant declaration for "nch" at the beginning of the program. Trees can have 300 nodes (including tips), this is controlled by the CONSTant "maxnodes" and can also be changed.

Because you may want to include a blank in a name, it is assumed that an underscore character ("_") stands for a blank; any of these in a name will be converted to a blank when it is read in. Any name may also be empty: a tree like

(,(,,),);

is allowed. Trees can be multifurcating at any level (while in many of the programs multifurcations of user-defined trees are not allowed or restricted to a trifurcation at the bottommost level, these programs do make any such restriction).

Branch lengths can be incorporated into a tree by putting a real number, with or without decimal point, after a node and preceded by a comma. This represents the length of the branch immediately below that node. Thus the above tree might have lengths represented as:
(B:6.0,(A:5.0,C:3.0,E:4.0):5.0,D:11.0);

These programs will be able to make use of this information only if lengths exist for every branch, except the one at the bottom of the tree.

The tree starts on the first line of the file, and can continue to subsequent lines. It is best to proceed to a new line, if at all, immediately after a comma. Blanks can be inserted at any point except in the middle of a species name or a branch length.

The above description is of a subset of the New Hampshire Standard. For example, interior nodes can have names in that standard, but if any are included the present programs will omit them.

To help you understand this tree representation, here are some trees in the above form:

((raccoon:19.19959,bear:6.80041):0.84600,((sea_lion:11.99700,
seal:12.00300):7.52973,((monkey:100.85930,cat:47.14069):20.59201,
weasel:18.87953):2.09460):3.87382,dog:25.46154);

(Bovine:0.69395,(Gibbon:0.36079,(Orang:0.33636,(Gorilla:0.17147,(Chimp:0.19268,
Human:0.11927):0.08386):0.06124):0.15057):0.54939,Mouse:1.21460);

(Bovine:0.69395,(Hylobates:0.36079,(Pongo:0.33636,(G._Gorilla:0.17147,
(P._paniscus:0.19268,H._sapiens:0.11927):0.08386):0.06124):0.15057):0.54939,
Rodent:1.21460);

();

((A,B),(C,D));

(Alpha,Beta,Gamma,Delta,,Epsilon,,,);

The New Hampshire Standard was adopted June 26, 1986 by an informal committee meeting during the Society for the Study of Evolution meetings in Durham, New Hampshire and consisting of James Archie, William H.E. Day, Wayne Maddison, Christopher Meacham, F. James Rohlf, David Swofford, and myself.



Progenitors: DRAWTREE and DRAWGRAM


(c) Copyright 1990 by Joseph Felsenstein. 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 and DRAWGRAM are interactive tree-plotting programs that take a tree description and read it. DRAWTREE plots unrooted trees and DRAWGRAM plots rooted cladograms and phenograms. These programs are descended from PLOTGRAM and PLOTREE written by Christopher Meacham. I have incorporated his code for fonts and his plotter drivers, and in DRAWTREE have used some of his code for drawing unrooted trees. In both programs I have also included some plotter driver code by David Swofford, Julian Humphries and George D.F. "Buz" Wilson, to all of whom I am very grateful. Mostly, however, they consist of my own code.