TreeTool User Manual Copyright (c) 1992, 1993, 1994 University of Illinois board of trustees. All rights reserved. Written by Michael Maciukenas for the Ribosomal Database Project. 1. Preface Treetool was written by Mike Maciukenas, for the Ribosomal Database Project (RDP), with assistance from Gary Olsen, Niels Larsen, and Carl Woese. The Ribosomal Database Project is at the University of Illinois. Treetool is a copyrighted program, not in the public domain, all rights are reserved. Permission is granted to copy and distribute the program, as long as all copyright messages are left intact, and the program is copied and distributed for free. Treetool is currently maintained by Mike McCaughey of the RDP. Bug reports, questions and comments should be addressed to mrmike@geta.life.uiuc.edu. 2. Introduction Treetool is an interactive tool for displaying, editing, and printing phylogenetic trees. The tree is displayed visually on screen, in various formats, and the user is able to modify the format, structure, and characteristics of the tree. Trees may be viewed, compared, formatted for printing, constructed from smaller trees, etc... Treetool works with Newick format tree files (Paup and Phylip compatible). It handles multifurcating trees, branch lengths (evolutionary distances), rooted/unrooted trees, and multiple trees per file. It can print to a PostScript printer, or output PICT graphics for Macintosh drawing programs (MacDraw). 3. Trees Treetool works on phylogenetic trees. Trees consist a set of nodes connected by branches. Each branch connects a parent node to a child node. Each node has only one parent, and may have any number of children (normally two in a phylogenetic tree). The base node is called the root node; by definition it has no parent. The terminal nodes in the tree, called leaf nodes, have no children. In a phylogenetic tree, the leaf nodes represent organisms, or taxa. Each branch has a length, corresponding to the evolutionary distance between the two nodes. The evolutionary distance between two organisms is found by adding the lengths of all the branches that lie on the path from one organism to another. Treetool operates on bifurcating (two children per node) or multifurcating (varying numbers of children per node) phylogenetic trees. The user can modify the structure, format, and size, all on screen, and see the results instantly. Treetool maintains the relationship between the nodes and the branch lengths and other important aspects of the tree. Treetool may operate on multiple trees at once, and allows exchanging of data between the trees. There are two display formats supported by Treetool. One is a "Radial" format (also called "Unrooted" or "Flower"). In this format the branches may extend in any direction, and the evolutionary distance is indicated by the length of the branch. The root node is not visually distinct in this format, which is why it is used to represent an a tree in which the location of the root node is not definite (an unrooted tree). The other format is the "Phenogram" (also called "Boxed" or "Rooted"). In this format, the root node is on the left, and all branches extend to the right. Evolutionary distance is indicated by the length of the horizontal portion of the branch only. This format is useful for a tree with a known root (a rooted tree), as the location of the root node can be shown clearly. The "scale bar" is a reference, basically a ruler, allowing someone viewing the tree to measure the lengths of the branches in the tree, and to compare different trees. Typically, the scale bar line represents an evolutionary distance of 0.10 or 0.05. The "outgroup" is an organism or a group of organisms relatively distantly related to the "ingroup", i.e., all other organisms in the tree. The outgroup is used to establish the root of the ingroup subtree. In a Phenogram (boxed) tree, the outgroup is placed at the bottom of the page, as a child of the root node. 4. Files and File Formats Treetool stores trees in files, in the Newick format (with treetool formatting comments). Treetool output files are compatible with Paup, Phylip, and many other tree manipulation programs. Output from Paup or Phylip may be sent directly to Treetool and displayed immediately. Treetool also outputs trees in various other formats. They are: Treetool format. This format is described above, it includes all information Treetool requires to display the tree in the correct format. It is Newick compatible. Newick format. This is the flat Newick format, without Treetool formatting comments. Prolog format. This is a special purpose format, used by the RDP. It is a representation of the tree in the Prolog language. PICT format. This is the Macintosh standard picture format. A PICT file created by Treetool may be copied to a Macintosh (when using ftp, binary mode must be used). It may then be loaded into MacDraw, or any other Macintosh drawing program. PostScript format. This format is a PostScript program for drawing the tree on a PostScript printer. It is used when the PostScript file must be kept (to print the tree, just use the "Print" item in the "File" menu, there is no need to save a PostScript file). Species List format. This format allows the user to save a selection. Later, the selection may be loaded. To save a species list, select some organisms on the tree, and then save with this format (see "Save File Window" below). The saved file will contain a list of the selected organisms. Later, the list may be loaded. When the list is loaded, the organisms in the list will be selected on screen. 5. Selections To make changes in the tree, the user must first select a part of the tree. This is done by clicking on the part to be selected. Once a part of the tree is selected, various operations may be performed on that part, such as: changing the font of node labels, changing the thickness of branches, etc... A single node may be selected, an branch may be selected, or an entire subtree (a node, all of its descendants, and all connecting branches) may be selected. More than one subtree, node, or branch may be selected at once, easily allowing simultaneous changes to many parts of the tree. To learn how to select the various parts of the tree, see the topic "Tree Tool" below. 6. Clipboard The clipboard is a hidden area where trees can be temporarily stored. When a tree or subtree is selected, it may be cut or copied to the clipboard. It is held there, so that later it may be pasted back into a tree. It remains on the clipboard until something else is cut or copied to the clipboard (it is not removed when pasted). The clipboard is useful when subtrees must be added to a tree, moved between trees, or extracted. The clipboard can be used, for example, to cut a subtree from one tree and then paste it into another tree. For information on the various cut/paste commands, see the topic "Edit Menu" below. Note: Treetool can cut (and therefore, you must select for cutting) only one subtree, for there is room on the clipboard for only a single subtree. The clipboard cannot hold branches, or nodes by themselves (when using the "Text" tool, the clipboard may hold text). 7. Tools Each tool allows the user to perform a group of related operations. To use a tool, press the button for the tool, and then move the pointer to the canvas to start using the tool. Each tool has its own button, with an tool icon on it. The tools and their uses are described in the next five sections. 7.1. The Tree Tool The "Tree" tool is represented by the pine tree cursor (and button icon). This tool allows the user to move and select parts of the tree. Click on parts of the tree to select them, and drag parts of the tree to move them. Selecting a subtree: click on the parent node (or label). Selecting nodes: click on the node (or label) with "CTRL" key down. Selecting branches: click on the branch; drag it to desired position. Multiple Selections: click with "SHIFT" key down for all (after the first). Moving a node: click on the node and drag it. Moving the scale bar: click on its handle and drag it. Moving a label: click on the label and drag it. 7.2. The Text Tool The "Text" tool is represented by the "i-beam" cursor (and button icon), and is used to edit the labels on the tree. To edit a label, click on it, and then type, using arrow keys and the delete key. To add a label to a node, click on the node, and then type text. To select text, click on the text and drag it. 7.3. The Move Tool The "Move" tool is represented by the dual arrow (one pointing right, one pointing down); it is used to position the tree on the page, and to resize the tree. When the move tool is chosen, a box appears around the tree, with squares at each corner. This is the resize box, and it can be used to move and resize the tree. To move the tree, click within the tree's boundary and drag. To resize the tree, click on a resize corner and drag. 7.4. The Flip Tool The "Flip" tool is represented by two spiraling arrows, and is used to exchange, or invert, the positions of the children of a node. It is most useful on a Phenogram (Boxed) tree, to interchange the order of the children of a node. Click on a node, and the children swap positions. 7.5. The Hide Tool The "Hide" tool is represented by a circle with a slash, and is used to hide the children of a node. Click on a node, and its children disappear. They are still present, but no editing operations will affect them, and they will not show on screen. A node with its children hidden is indicated on screen by a large circle around the node's handle. To make the children reappear, click on the node again. 8. The Help Window The "Help" window provides on-line information about using treetool. To see the help window, choose the "Help..." item from the "Help" menu. The help window has two parts. To the left is the topic window, which displays the information about a particular topic. To the right is the topic list, from which a topic may be selected. To select a topic, click on the name in the topic list. The information for the topic will be displayed in the topic window. Use the scrollbars to display more of the topic, and to display more of the topic list. 9. File Menu The File menu has items for saving, loading, and printing trees, and for quitting Treetool. 9.1. Load File Window The "Load File" window allows the user to choose a file to load. When the file is chosen, the trees stored in the file will appear on screen. If there are already trees on screen, they will remain, and the new trees will appear in addition. There are two ways to select a file: click on a name in the list and press the "Open" button, or double-click on the name in the list. There are four ways to change directories: press the "Up Dir" button to see the parent directory, type a new directory name into the "Directory" field, click on the directory name (indicated by a trailing slash "/") in the list and press the "Open" button, or double-click on the directory name in the list). To load a species list (explained in the Treetool User Manual), check the "Load Species List" checkbox, and then choose a file to open. 9.2. Save File Window The "Save File" window allows the user to save trees in a file. When the file is chosen, the trees currently loaded will be stored in the file. To select the filename, type it into the "File name" field, and then press the "Save" button. To select the file type, choose one from the "Format" menu. The filename will be updated to contain the right suffix (.PICT, .ps, etc.). The current directory can be changed as described above under "Load File Window" (use "Open Dir" instead of "Open" to view the contents of the selected directory). 9.3. Print Window The print window allows the user to choose a printer to which to print the trees. Enter the name of the printer name and press "Ok," or just press "Ok." Treetool usually recognizes the correct printer. 9.4. Quit The "Quit" item on the "File" menu exits Treetool. If the current file has not been saved since it was last modified, the user will be prompted. 10. Edit Menu The "Edit" menu allows operations to rearrange the structure of the tree. The items in the "Edit" menu move data back and forth between the trees and the clipboard (see "Clipboard" above). Note: it is recommended that Automatic Formatting (see the topic "Preferences" below) be used when using the items in the "Edit" menu. If Automatic Formatting is not used, the tree will not be formatted as expected. 10.1. Cut The "Cut" item removes the selected part of the tree, and places it on the clipboard (see "Clipboard" above). Cut may be chosen either by selecting the "Cut" item from the "Edit" menu, or by pressing the "Cut" key on the keyboard. Note that the clipboard holds only one full subtree or tree, it cannot hold single nodes, branches by themselves, or groups of subtrees. It is recommended that "Automatic Formatting" (see the topic "Preferences" below) be used when using the "Cut" menu item. 10.2. Copy The "Copy" item places the selected part of the tree on the clipboard (see "Clipboard" above). It does not remove the selected part from the tree. Copy may be chosen either by selecting the "Copy" item from the "Edit" menu, or by pressing the "Copy" key on the keyboard. Note that the clipboard holds only one full subtree or tree, it cannot hold single nodes, branches by themselves, or groups of subtrees. It is recommended that "Automatic Formatting" (see the topic "Preferences" below) be used when using the "Copy" menu item. 10.3. Paste The "Paste" item takes the data on the clipboard (see "Clipboard" above) and places it in the tree. How it is placed is dependent on what is currently selected. If nothing is selected, the subtree on the clipboard is pasted as a new tree in the upper left corner of the canvas. If a subtree is selected, the subtree on the clipboard replaces the selected subtree. If a node is selected, it and all of its descendants will be replaced by the subtree on the clipboard (as if a subtree had been selected). If a branch point is selected, a new node is added at that point in the branch. The subtree on the clipboard is added as a child of the new node. Paste may be chosen either by selecting the "Paste" item from the "Edit" menu, or by pressing the "Paste" key on the keyboard. It is recommended that "Automatic Formatting" (see the topic "Preferences" below) be used when using the "Paste" menu item. 10.4. Add The "Add" item takes the data from the clipboard (see "Clipboard" above) and places it as a child of a selected node in the tree. Its operation depends upon whether a node or a subtree is selected. If a node is selected, the subtree on the clipboard will be placed as a child of the node. If a subtree is selected, the subtree on the clipboard will be added as a child of the top node in the subtree. It is recommended that "Automatic Formatting" (see the topic "Preferences" below) be used when using the "Add" menu item. 10.5. Delete The "Delete" menu item is used to remove a subtree from the tree without placing it on the clipboard. This is useful when there is already something on the clipboard that will be needed after the Delete operation is performed. It is recommended that "Automatic Formatting" (see the topic "Preferences" below) be used when using the "Delete" menu item. 11. Utilities Menu The "Utilities" menu contains commonly used options: 11.1. Find Window The "Find Node" window allows the user to search for a node by name. When the node is found, it is automatically selected. To find a node, type the name in the "Node name" field, and then press the "Find" button. The next node in the tree that matches the given name will be selected. If the whole name is not known, part of the name may be given, and the node will still be found. For example, to find the node "Sul.solfat," use any one of these search strings: "Sul.solfat," "Sul," "sol," etc. To find all nodes that match the specified name, press the "Find All" button (instead of "Find"). Each node that matches the node name will be selected. When a match is found, Treetool clears the current selection and selects only the matching node. The user loses the current selection. This operation is modified by the "Replace Current Selection" checkbox. When this box is checked, Treetool clears the current selection when a node is found. If this box is not checked, Treetool will not clear the current selection, and the node that is found will be added to the selection. 11.2. Zoom Zoom allows the user to look more closely at the tree, or to see more of the tree at once. Zooming In magnifies the tree, zooming out the opposite. The true size of the tree is unchanged, only its scaling on screen is affected. Zooming In is effective with very large trees, with many leaves. Some operations are difficult to do on a tree of this type, since nodes may be very close together. Zooming In shows gives greater resolution and detail, and makes feasible certain otherwise untractable operations. Note: concerning text and Zooming. This release of treetool is not able to scale fonts during Zoom operations. When Zooming Out, the node labels do not become smaller (even though the tree does become smaller). Therefore, the labels tend to overlap. This is normal, when the user Zooms In again to return the tree to its normal size, the labels will return to their normal form also. Similar problems occur when Zooming In. 11.3. Tree Settings Window The "Tree Settings" window allows the user to change global formatting information regarding the selected trees. The format of the trees may be changed, and various options are available. A tree is considered selected if any node, subtree, or branch in it is selected. The tree can appear in one of two formats, "Phenogram" and "Radial" (see the topic "Trees" above). To change the format, choose another format from the "Tree Format" menu in the "Tree Settings" window. The formatting information for each format (phenogram and radial) is kept separately, so that the user may switch from phenogram to radial and back to phenogram without losing the formatting of the phenogram. For more information on the two tree formats, see the topic "Trees" above. The scale bar may be hidden by unchecking the "Show Scale Bar" checkbox. Internal names (names associated with nodes that are not leaf tips) may be hidden by unchecking the "Show Internal Names" checkbox. Terminal names (names associated with leaf tips) may be hidden by unchecking the "Show Terminal Names" checkbox. 11.4. Node Settings Window The "Node Settings" window allows the user to change the format of labels for selected nodes. Color, and the font type and size may be changed. To change the color, press the "Change Color" button. The "Choose a Node Color" window will appear. A color is specified by its red, green, and blue composition, or by a name. To choose a color, drag the sliders for the red, green, and blue composition back and forth. The large area at the bottom of the window will change color accordingly. Alternatively, type a color name (such as "red" or "green4") in the "Choose by name" field, and press the "Return" key on the keyboard. Press the "Ok" button to change the color of the selected nodes. To change the font type and size, choose among the items provided by the three menus, "Font," "Style," and "Size." The font type and size of the selected nodes will be changed immediately. 11.5. Branch Settings Window The "Branch Settings" window allows the user to change the format of selected branches. The line width and the color may be changed. To change the line width, drag the slider back and forth. The line width of the selected branches will be changed immediately. To change the color, press the "Change Color" button. The "Choose a Branch Color" window will appear. A color is specified by its red, green, and blue composition, or by a name. To choose a color, drag the sliders for the red, green, and blue composition back and forth. The large area at the bottom of the window will change color accordingly. Alternatively, type a color name (such as "red" or "green4") in the "Choose by name" field, and press the "Return" key on the keyboard. Press the "Ok" button to change the color of the selected branches. 11.6. Scale Bar Settings Window The "Scale Bar Settings" window allows the user to change formatting information about the scale bar (see the topic "Trees" above) for the selected trees. The scaling factor, percentage value, color, and font type and size may all be changed. A tree is considered to be selected if any node, subtree, or branch in it is selected. The "Scale for Scale Bar" field contains the scaling factor for the scale bar. Evolutionary distance units are normally presented on a scale from 0.0 (completely similar) to 1.0 (completely dissimilar). However, in some applications, evolutionary distance units are presented on a scale from 0.0 to 100.0. Treetool allows the user to specify the scale so that all tree types may be handled correctly. To change the color, press the "Change Color" button. The "Choose a Color for the Scale Bar" window will appear. A color is specified by its red, green, and blue composition, or by a name. To choose a color, drag the sliders for the red, green, and blue composition back and forth. The large area at the bottom of the window will change color accordingly. Alternatively, type a color name (such as "red" or "green4") in the "Choose by name" field, and press the "Return" key on the keyboard. Press the "Ok" button to change the color of the scale bar for the selected trees. To change the font type and size, choose among the items provided by the three menus, "Font," "Style," and "Size." The font type and size of the scale bars for the selected trees will be changed immediately. 12. Extras Menu The "Extras" menu contains items for doing various tree manipulations. 12.1. Preferences When the "Preferences..." item is chosen, the "Preferences" window appears, with four checkboxes. Automatic Formatting is used when the user wants to make structural changes to the tree. It repositions the nodes into their default positions every time a change is made to the tree. This is useful when cutting, pasting, adding, or deleting subtrees, and when changing the outgroup. Since nodes are kept in their default positions, dragging nodes is not permitted while Automatic Formatting is on. Note: if nodes have been moved from their default positions, they will be moved back when Automatic Formatting is switched on. To turn on Automatic Formatting, check the "Automatic Formatting" checkbox in the "Preferences" window. Automatic Node Merging is used when the user is cutting or deleting many subtrees from a given tree. As subtrees are cut, nodes that have only one child may remain in the tree. Under Automatic Node Merging, any time an operation produces a node that has a single child, that child is immediately merged. Merging is described below under "Structure Commands." To turn on Automatic Node Merging, check the "Automatic Node Merging" checkbox in the "Preferences" window. Treetool has the capability to display dashed lines at the edge of each page in the canvas. This gives the user an indication of the size of each page, and helps in positioning trees, and choosing their sizes. To make the page lines appear, check the "Show Page Lines" checkbox in the "Preferences" window. Treetool can hide the handles that appear at every node, and on the scale bar, which allows the user to view the tree exactly as it would appear in print, since these handles are not printed. To hide the handles, uncheck the "Show Tree Handles" checkbox in the "Preferences" window. 12.2. Selection Commands The "Extras" menu has several commands for working with selections. "Connect Selections" selects all branches and nodes that connect the currently selected nodes (in other words, those that lie on the path between the currently selected nodes). "Select Common Ancestor" selects the lowest common ancestor of all of the currently selected nodes. "Select All" selects all of the nodes in all of the trees. 12.3. Structure Commands "Representative Tree" is used to prune the tree. It can be used to reduce a tree containing many organisms into one containing a selected subset thereof. To do this, select the organisms that will be kept, and then choose "Representative Tree" from the "Extras" menu. Everything except the selected nodes and their ancestors is removed from the tree. It is recommended that the item "Merge Mergeable Nodes" (described below) be used after "Representative Tree," since many nodes having a single child will have been created. "Merge Mergeable Nodes" removes any selected nodes that have only one child. This process is called "merging a node." The node is removed, and the two branches (one between the node and its parent, one between the node and its child) are added together to form a single long branch. "Change Outgroup" can be used restructure the tree so that a different subtree is used as the outgroup (the outgroup is discussed under the topic "Trees" above). To choose an outgroup, use the "Tree" tool to select a branch point at which to place the new root. Then choose the "Change Outgroup" item from the "Extras" menu. The subtree at the child end of the selected branch becomes the new outgroup, and the break-point in that branch (on a phenogram) will appear at the selection point (thereby determining the length of the branch leading to the outgroup). 12.4. Format Commands "Even Spacing" is used to return nodes to their default spacings. It can be used when the tree has been messed up (by repeated dragging of nodes), to return the tree to a reasonable format. It performs the same function that Automatic Formatting (see the topic "Preferences" above) performs, except in this case the effect is only temporary. "Justify Selected Labels" is used to return the labels of the selected nodes to their original positions. In the Phenogram, the default position is immediately to the right of the node. In the Radial tree, the default position is centered and in the direction of the node's parent branch. 12.5. Hiding Commands Hiding is described above, under the topic "Hide Tool." The "Extras" menu has additional ways for hiding nodes. "Hide Selected Nodes" hides the children of all of the selected nodes, and "Show Selected Nodes" shows the children of all selected nodes. "Hide Level" hides all of the nodes below the selected level in the tree. This can be used to provide an overview of the tree. Use "Show Selected Nodes" to cause those nodes to reappear. 13. Command Line Options Various Treetool options can be controlled from the command line: Filename option. Specifies file to be loaded, as in "treetool treefile." More than one file may be specified, the trees in all of the files will be displayed when Treetool starts up. "-h" option. Instructs Treetool to print out a help message, describing these options. Treetool does not start up. -phenogram (-p) [-radial (-r)]; causes Treetool to start up with Phenogram [Radial] as the initial tree format. Default is -p. -auto [-noauto]; causes Treetool to start up with [without] Automatic Formatting on. Default is -noauto. -merge [-nomerge]; causes Treetool to start up with [without] Automatic Node Merging on. Default is -nomerge. Treetool also accepts the standard X-windows and Xview options.