PhyloDet User Manual

PhyloDet
- A Scalable Visualization Tool for Mapping Multiple Traits to Large Evolutionary Trees

PhyloDet User Manual

PhyloDet (Figure 1) is a scalable Phylogenetic Tree Browser that allows biologists to visualize multiple traits mapped to an evolutionary tree. To show the links with different distance, we modified the MSAGL (Microsoft Automatic Graph Layout) algorithm developed at Microsoft Research. PhyloDet consists of a main tree view and three lists (Leaf list, Color Filters list, and Attributes list).

Figure 1. PhyloDet shows four traits mapped to 1134 species in their evolutionary tree.

Download PhyloDet

Note that PhyloDet runs only on Windows and requires Microsoft .NET Framework 3.5 (available for free from Microsoft).

Check if you have .NET: Run Start->Control Panel->Add or Remove Programs. If there is an entry for "Microsoft .NET Framework 3.5," then you have it and you don't have to do anything else.
If you don't have .NET, get it: Download .NET Framework 3.5 from Microsoft.

Open a Tree File
To open a tree file, select "Open Tree..." menu item from the "File" menu (Figure 2), click on the Open Tree button (

) from the tool bar, or press "O" with "Ctrl" pressed from the keyboard.

Figure 2. Open Tree menu.

Open an Attribute File
Once a tree is opened and loaded, users can open attributes files for that tree.
To open an attribute file, first select "Open Attribute..." menu item from the "File" menu (Figure 3) or click on the Open Attribute button (

) from the tool bar.

Figure 3. Open Attribute menu.

Then, select the attribute file using the "Browse..." button in the Attribute File Open dialog (Figure 4). To convert dna sequences to amino acids, check the "convert dna sequences to amino acids" check box.

Figure 4. Attribute File Open dialog.

PhyloDet reads one tree file and multiple attribute files. The tree files are in the Newick tree format and attribute files are tab-delimited text files.

Tree File Format
The name part of the leaf node consists of leaf name and its annotation, delimited by '#'. The annotation for the leaf node D is 'Longest' in the following example.

(A:0.1,B:0.2,(C:0.3,D#Longest:0.4):0.5);

Attribute File Format
PhyloDet supports the following attribute file formats. Note that the headers of these files have to exactly match.

	* Sequence based Fasta Phylip Tab-delimited Two Column: First column is patient name, second is sequence. Columns must have titles, but titles can be anything.
	* HLA based Table: Each row starts with a patient ID, followed by HLA types in any resolution (Figure 5). For missing data, use '?' (without quote). Figure 5. Example attribute file in an HLA table form. Tab-delimited Two Column: Each row starts with a patient, followed by HLA of any resolution, including 'A', 'B' or 'C' (Figure 6). Omit rows corresponding to missing data. Figure 6. Example attribute file in an HLA 2-Column form.
	* Generic Sparse: As shown in Figure 7, the first column is the name of variable, the second column is the patient id, and the third column is whether or not the patient has the variable. Omit rows corresponding to missing data. Note that PhyloDet only supports binary values for now. Figure 7. Example attribute file. Table: Each column is a patient and each row is a variable with entry 1/0/? (Figure 8). Figure 8. Example attribute file in a table form.

When a tree is opened and loaded, PhyloDet shows all the leaf nodes in the Leaf list -- the list shown at the top of the left panel (Figure 1).
PhyloDet provides a way to search for specific leaf nodes � a simple substring match either with node label or with annotation. While users are typing, the Leaf list is updated with search results (Figure 9).

Figure 9. Leaf List is updated with search results.

When users select a leaf from the list, a leaf node mapped to the selected leaf is highlighted in the tree on the right. If the leaf node is off-screen, PhyloDet animates the tree view to show the mapped leaf node.

To annotate a left node, right-click either on the leaf node in the tree view or an item in the Leaf list, and select the "Annotate..." menu from the popup menu (Figure 10). This will open an Annotation dialog (Figure 11).

Figure 10. Annotate popup menu.

Then, type in any annotation in the annotation text box (Figure 11). This annotation will be shown in the Annotation column of the Leaf list and provided as a tooltip when users move the mouse over the leaf node in the tree view.

Figure 11. Annotation dialog.

To set a node as the root of the tree, right-click on the node and select the "Set this as root" menu from the popup menu (Figure 12). Note that there could be some delay until the popup menu shows up after right-click.

Set as Root

Figure 12. Any node can be set as the root of the tree.

To hide a branch of the tree, right-click on the internal node and select the "Hide this subtree" menu from the popup menu. User can show the hidden branch by selecting "Show this subtree" menu from the popup menu (Figure 13).

Set as Root

Figure 13. Users can show/hide any branch of the tree.

PhyloDet allows users to color-code the incoming link for the leaf node and the leaf node itself based on the node labels. This information is saved in the configuration file that can be automatically generated from the PhyloDet user interface - Color Configuration dialog. Available color filters are shown in the Color Filters list -- the list shown at the middle of the left panel (Figure 1). To add a color filter, click "Add" button above the Color Filters list. This will open a Color Configuration dialog (Figure 14). Then, choose color and shape of the leaf nodes and assign the target string and the name of the color configuration. Any leaf whose name contains the target string will be labeled by the new color filter. When a name contains the target string of two different filters, the topmost one in the Color Filters list is applied. Figure 10 shows an example configuration to color the links for the nodes with string "CladeB" with a color "Blue."

Figure 14. Color Configuration dialog.

The name (e.g. "CladeB") will be shown with the mapped color (Blue) in the Color Filters list (Figure 15) and all nodes that include "CladeB" in their name will be colored Blue. To edit a color filter, right-click on the item and select the "Edit..." menu from the popup menu. To delete a color filter, select the "Delete" menu from the popup menu.

Figure 15. Color Filter Edit menu.

When users uncheck the check box by the color filter name, PhyloDet (by default) grays out all the leaf nodes whose link color was the color mapped to that name. To hide the corresponding leaf nodes instead of graying them out, check the "Hide Filtered Nodes and Links" check box.

When users open an attribute file, PhyloDet shows all the attributes specified within the attribute file in the list box so that users can choose which attributes to show (Figure 16). Users can open multiple attributes files.

Figure 16. Attributes dialog.

PhyloDet provides a way to search for specific attributes � a simple substring match with attribute name. While users are typing, the Attributes list is updated with search results.
To show specific attributes in the main window, add them in the Selected Attributes list (on the right) by clicking "Select >>" button after checking the check boxes by the attribute name.
Similarly, to remove attributes from the Selected Attributes list, click "UnSelect <<" button after checking the check boxes by the attribute name in the Selected Attributes list.

Once users press the "OK" button in the Attributes dialog, PhyloDet shows a color bar for the selected attributes (see Figure 1). Depending on the root orientation, the color bar is shown either on the right side or at the bottom of the tree. To help users map the attribute value with the leaf node, the first column of the color bar is the repetition of the link color of leaf nodes. The second column represents the first selected attribute, the third column represents the second selected attribute, and so on. When users move the mouse over a color rectangle (for the mapping leaf node) in the color bar, a tooltip will show both the name of the leaf node (first line) and the name of the attribute (second line).

To select/unselect attributes to be shown, use the Attributes dialog by selecting "Show Attribute..." menu item in the File menu or click on the Show/Hide Attributes button (

) from the tool bar.

The currently shown attributes are listed in the Attributes list at the bottom of the left panel (Figure 1).
When users click on the filter range button in the Filter Range column, PhyloDet opens the Attribute Value Range dialog, which allows users to drag the circular tabs to specify a range of values that should be displayed (Figure 17). To hide the nodes with missing values, uncheck the "Shown N/A" check box under the filter range button (Figure 1). Color blue and red are mapped to minimum value and maximum value respectively (Figure 17), and color black represents a missing value (e.g., not available or not specified).

Figure 17. Attribute Value Range dialog.

Figure 18. PhyloDet Toolbar.

Root Orientation:
PhyloDet supports 4 root orientations; Top, Left, Bottom, and Right.

Open Tree:
Open a tree file.

Save Tree:
Save the tree to the (currently opened) tree file.

Home (or Reset):
Re-opens the currently opened tree file.

Open Attribute File:
Open an attribute file.

Show/Hide Attributes:
Opens an Attributes dialog so that users can select/unselect the attributes to be shown.

Show/Hide Attributes Color Bar:
Show/Hide the attributes color bar.

Attr Bar Height (or Width):
Users can specify the height (or width depending on the root orientation) of the color bar in pixels. This height applies to the color bar regardless of the number of attributes to be shown. Therefore, the more attributes users choose to show, the lower the height (or width) of row (or column) for each attribute is. For example, in Figure 2 with the color bar width of 48, the width for each attribute is 48 / 3 (2 attributes + 1 for the leaf repetition) = 16 pixels.

Zoom Slider and Navigation History:
Users can zoom in to see the details of the part (often a cluster) of the trees. Whenever the zoom factor changes, PhyloDet automatically readjusts the thickness of the links depending on the visible tree size and screen space. PhyloDet also stores the navigation history so that users can easily go back to the previous zoom level.

Min Branch Length:
If the branch length of a link is smaller than the minimum branch length set by users, PhyloDet presents that link with the minimum branch length.

Neg. Branch Length:
If the branch length of a link is negative, PhyloDet either hides that link or presents that link with a dotted line.

Link Thickness:
Specifies the thickness of the link.

Node Thickness:
Specifies the thickness of the border of the nodes.

PhyloDet allows users to copy the currently visible tree to the clip board so that they can paste it into their favorite image editing tool.
Select "Copy" menu item from the "Edit" menu (Figure 19) or press "C" with the "Ctrl" button pressed from the keyboard.

Figure 19. Copy menu.

To print the currently visible tree, select "Print..." menu item from the "File" menu (Figure 20) or press "P" with the "Ctrl" button pressed from the keyboard.

Figure 20. Print menu.

Note that a high resolution image can be achieved by printing it using a Microsoft XPS Document Writer (Figure 21).

Figure 21. Print using a Microsoft XPS Document Writer.