PROGRAM 'paloverde' v.1.1 A three-D large tree visualization tool Copyright (C) 2006 Michael J. Sanderson Section of Evolution and Ecology UC Davis Davis, CA 95616 USA INTRODUCTION This is a simple program to do three-D visualizations of moderately large phylogenies. Trees with between 100 and 5000 taxa seem to work best (more if subclades are defined by the user). Faster graphics hardware than is available by default on my Powerbook G4 laptop extends the range upward. The program allows the user to examine the tree from various perspectives and distances. The basic "circle" layout has the most features, but three other true 3-D layouts are also available. Several display modes are provided that change the kind of information displayed on large trees, especially with respect to user-defined subclades. These can be defined by the user in the input file, or they can be generated on the fly based on grouping, e.g., all species in the same (monophyletic) "genus" together. Subclades can be displayed as single terminal taxa or they can be displayed in their entirety with visual cues about their membership. A pop-up menu permits the user to select any of these subclades, which are then presented in their own 3D world. Finally, a search function permits the user to zoom in on any selected terminal taxon. The program was written and compiled under Mac OS 10.3 and Linux. It is most convenient to use with a mouse with left and right buttons, although almost all features require only the "left" (standard on Mac) button. The program is written in C using the OpenGL library and two libraries for phylogenetics programs that I have written, also in C (available in subdirectories of the distribution). This is my first OpenGL program, and it undoubtedly does a lot of things inefficiently or inelegantly. I welcome suggestions for improvement (mjsanderson@ucdavis.edu). ---------------------------------------------------------------------- INSTALLATION (Mac OS 10.3 or later) Download the README file, the sample data file, and the executable file from the web site and put all of these files into some working directory (we'll call it WORKING_DIR). The executable is only compiled for Mac OS 10.3. I do not know if it works on earlier versions of OS X. The executable will be called paloverde.XXXX.OSX.bin, where XXXX is the current version number. Open a terminal shell with the Mac Terminal utility. Move into your directory with the command cd WORKING_DIR Change the name of the executable file (for convenience) by the UNIX command mv paloverde.0.XXXX.OSX.bin paloverde Make the program executable: chmod +x paloverde ---------------------------------------------------------------------- INSTALLATION (Building from source on Linux or Mac OS X) Download the compressed distribution file, paloverde.XXXX.tar.Z, and uncompress and untar: uncompress paloverde.XXXX.tar.Z untar paloverde.XXXX.tar Then cd paloverde to get into the distribution directory and type either make -f makefile.linux ... or make -f makefile.macosx depending on which operating system you are working in. Note that I have done my best to get the Linux X library and OpenGl library and header calls right, but your system may be set up differently. This is a pretty standard way to do it, but if you have problems, contact your local system administrator. The code *does* compile and run on Linux, so if it isn't working it is a local issue. Finally, you may have to change permissions on the executable: chmod +x paloverde ---------------------------------------------------------------------- TESTING THE DOWNLOAD A sample input tree is included. Type ./paloverde -f rbcl.nex to run the sample data. This should open a graphics window with a 500-taxon circular tree. Try thickening the branches with the keyboard 'C' toggle. Also you may want to change the size of the taxon labels using the 'l/L' keyboard toggle. Finally, switch to full screen mode with the 'f' key. Right-clicking the mouse (or cntl-click on Mac single-button mouse) displays a pop-up menu of all terminal taxa. Selecting one will zoom to that part of the tree. After experimenting with mouse controls (see below) try ./paloverde -f rbcl.nex -m This will collapse two of the clades, making them available in a popup window. Alternatively, type ./paloverde -f rbcl.nex -a This will display the original tree but with arcs showing the position and names of these two clades. You probably want to either turn off taxon names with the 'T' keyboard toggle or move the arcs outward from the center by punching the 'A' key. For further explanation see below. ---------------------------------------------------------------------- INPUT The program takes a nexus tree file as input. The nexus parser I use is not very smart. The file can only contain a TREES block and there can only be one tree in the block. However, it does read a translation table if present. In other words, your file should look like this: #nexus begin trees; tree treeName=(a,b,(d,e)); end; where obviously your treeName and actual tree description are different. In addition, user defined subclades can be defined with the MRCA command within the trees block (note the syntax is slightly different than in my r8s program and more like standard nexus format). For example mrca monocots = zingiber, zea; The clade named monocots will be defined as all taxa descended from the most recent common ancestor of the two or more taxa listed on the right of the equals sign. This command can be inserted after the tree command in the trees block. Multiple mrca commands can be included. The 'rbcl.nex' sample tree file has two clades defined using MRCA commands. Note, the program will read Nexus tree files that have internal node names built-in: for example tree treeName=(a,b(d,e)cladeName)); However, this will not be available as a subclade that can be displayed with the -m option (see below). Use the mrca command for full functionality. ---------------------------------------------------------------------- RUNNING THE PROGRAM (QUICK START) On the command line of a terminal shell, type ./paloverde -f nexusTreeFileName where the file is a properly formatted nexus file as described above. The program takes input from the mouse and from the keyboard. The program should open a window and display the tree in circular layout, with its axis of rotation, the Z-axis, coming straight out of the screen toward your eyes. (Left) clicking and dragging the mouse right or left rotates the tree around the Z-axis. (Left) clicking and dragging up or down rotates it about the X-axis (try it). To move or zoom in, (left)-shift-click . Shift-clicking and moving up or down zooms the view. Shift-clicking and moving right or left with the mouse moves the tree right or left. With a small amount of practice it becomes quite easy to quickly navigate around the tree. The up/down arrow keys are for "slow motion". As is they control rotations. If you hit the shift key and move the arrow keys they zoom or move the tree in the analogous way as the mouse. Other useful keyboard functions: f toggle full screen mode l/L decreases/increases the size of the taxon labels w toggle labels always face viewer g/G pushes all nodes out toward tips, or in toward center c/C decreases/increases the width of the tree's branches s toggles the tree-drawing to be smooth or rough at the internal nodes (affects rendering speed) T toggle display of terminal names on/off a/A decreases/increases the distance of arcs from center of layout in "arc" mode x/X,y/Y,z/Z move the tree in these six possible directions ESC quit ---------------------------------------------------------------------- SEARCHING FOR TAXA In the default circular layout, you can search for a particular terminal taxon name via a pop-up menu displayed with right-click of the mouse (or cntl-click on a Mac single-button mouse). Note that if you have warped the perspective too much, the routine may not place the desired taxon right in the center of the screen, but hopefully it will be close. This option is not available in other layouts or when subclades are defined and used. ---------------------------------------------------------------------- OTHER TREE LAYOUTS In addition to the standard circular (radial) layout, three true 3-D layouts are implemented. Not all features are available in all layouts. Layouts are selected with the command line switch '-l' (see below). Spiral -- the standard 2-D circular layout is extended along its z-axis. The angular extent of the spiral can be controlled by the '-c' command line switch (see below). Cone -- the leaf nodes (terminal taxa) stay in a circle, but the internal nodes are pushed in the negative z direction, forming a conical tree-like structure. Adjustments of the -c switch make the cone open up for part of its radial dimension. Hemisphere -- a true 3-D "tree" is drawn with the root on the "ground" and branches spreading above it in the z-axis direction. The initial view is from above looking down toward the root and "ground". An artificial horizon is included for perspective. The 'w' keyboard toggle is useful here for forcing the taxon names to always face the viewer. Note that the clade annotation options (-a, -m, -g) are not implemented for this layout. ---------------------------------------------------------------------- RUNNING THE PROGRAM (ADVANCED) The program has several display modes that are activated with command line arguments: Default mode: all terminal taxa described in the tree description statement in the input file are displayed with their labels present MRCA mode (-m switch): Any clade defined with an MRCA command in the input file is "collapsed" in the tree into a single terminal branch with an enlarged label and an indication of how many terminals are included. In addition, a pop-up list is maintained by the program and can be viewed by right-clicking the mouse (cntl-click on Macs without a two button mouse). Clicking on one of these names in the menu displays the subclade. The original tree is referred to as the "root" in this list. [Not implemented for hemisphere layout] Arc mode (-a switch): Trees are drawn as in default mode with all terminal taxa listed, but any clade named by an MRCA command appears with an annotation around the periphery of the tree. This annotation consists of a colored arc and the name of the clade, including the number of terminals contained in it. Display is enhanced by toggling off the taxon names with the 'T' keyboard toggle. It is also helpful to move the arcs in or out radially with the 'a/A' toggle. [only implemented in circular layout] Genus mode (-g switch): This is complicated but useful for large trees. It permits the names of terminals to be parsed and clades defined automatically in the following way. Assuming that all terminal taxon names consist of something like latin Linnean binomials with the elements separated by an underscore, the program will collect all terminals with matching kth elements into the same group as long as that group is a clade. If the group is paraphyletic, it will name a set of separate clades with the same name to account for all taxa. For example, suppose there were a set of terminal names on the tree such as this: Astragalus_lentiginosus Astragalus_coccineus Astragalus_molybdenus Colutea_arborescens Colutea_istrea then using the -g 1 option (where 1 refers to collecting the "first" element in the taxon name), will display a tree with two terminals named Astragalus and Colutea-as long as the two groups are monophyletic on the tree. If they are *not* monophyletic, then the program may display multiple groups with the name Astragalus or Colutea. In other words, it *never* displays a taxon name that refers to a nonmonophyletic group. [Not implemented in hemisphere layout] ---------------------------------------------------------------------- TIPS FOR VIEWING VERY LARGE TREES Trees with > 1000 tips viewed in default mode can be challenging. I have found it useful to zoom into the right side of the screen, reasonably close to the labels, set the labels to a readable size, set the label display toggle (w) so that labels always face viewer, tilt the circle tree away from you so that the top of the tree (part of the tree toward top of screen) is visible in the far distance. It also helps to move the whole tree down a bit using the Y key, so that you get a better perspective. Then, rotating the tree with the slow motion left/right arrows can be illuminating. Another trick that helps is to use the (G) toggle to push internal nodes out toward the tips. The search utility can make it easier to get close to the readable part of the tree. Finally, if you have the chance, try a very large display, like the Apple Cinema display. It makes all the difference. ---------------------------------------------------------------------- SUMMARY OF COMMAND LINE ARGUMENTS paloverde [-m] [-A] [-p] [-c [X]] [-g [N]] [-h] [-l layout_style] -f file -m Collapse clades defined by MRCA command in input file -a "Arc" view: Display all terminals plus annotations about MRCA clades from input file -g Use "genus" mode (Parse terminal binomial names and collapse all genera) (N is an integer specifying which term in underscore- delimited taxon name is used, default=1) -l Specify type of layout:circle cone spiral hemisphere -p Display as a phylogram with branch lengths -c Control fractional amount of circle to display (01) -h Print this message -f Input file name ---------------------------------------------------------------------- THE NAME Palo verde (Cercidium spp.) is a Sonoran desert tree with greenish bark, similar to the tree in the program (especially an earlier layout). It is a legume, related rather distantly to mesquite, but there is no actual or implied similarity in the code or design to the elegant 'Mesquite' phylogenetics package. ---------------------------------------------------------------------- LICENSE This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.