Using the Phylogenetic Tree App

Overview of the Phylogenetic Tree App

The Phylogenetic Tree app allows you to view, edit, format, and explore phylogenetic tree data. With this app you can prune, reorder, rename branches, and explore distances. You can also open or save Newick or ClustalW tree formatted files. The following sections give a description of menu commands and features for creating publishable tree figures.

Opening the Phylogenetic Tree App

This section illustrates how to draw a phylogenetic tree from data in a phytree object or a previously saved file.

The Phylogenetic Tree app can read data from Newick and ClustalW tree formatted files.

This procedure uses the phylogenetic tree data stored in the file pf00002.tree as an example. The data was retrieved from the protein family (PFAM) Web database and saved to a file using the accession number PF00002 and the function gethmmtree.

Create a phytree object. For example, to create a phytree object from tree data in the file pf00002.tree, type
```
tr = phytreeread('pf00002.tree')
```
The MATLAB^® software creates a phytree object.
```
Phylogenetic tree object with 33 leaves (32 branches)
```
View the phylogenetic tree using the app.
```
phytreeviewer(tr)
```
Alternatively, click Phylogenetic Tree on the Apps tab.

File Menu

The File menu includes the standard commands for opening and closing a file, and it includes commands to use phytree object data from the MATLAB Workspace. The File menu commands are shown below.

New Viewer Command

Use the New Viewer command to open tree data from a file into a second Phylogenetic Tree viewer.

From the File menu, select New Viewer.
The Open A Phylogenetic Tree dialog box opens.
Choose the source for a tree.
- MATLAB Workspace — Select the Import from Workspace options, and then select a phytree object from the list.
- File — Select the Open phylogenetic tree file option, click the Browse button, select a directory, select a file with the extension .tree, and then click Open. The toolbox uses the file extension .tree for Newick-formatted files, but you can use any Newick-formatted file with any extension.
A second Phylogenetic Tree viewer opens with tree data from the selected file.

Open Command

Use the Open command to read tree data from a Newick-formatted file and display that data in the app.

From the File menu, click Open.
The Select Phylogenetic Tree File dialog box opens.
Select a directory, select a Newick-formatted file, and then click Open. The app uses the file extension .tree for Newick-formatted files, but you can use any Newick-formatted file with any extension.
The app replaces the current tree data with data from the selected file.

Import from Workspace Command

Use the Import from Workspace command to read tree data from a phytree object in the MATLAB Workspace and display the data using the app.

From the File menu, select Import from Workspace.
The Get Phytree Object dialog box opens.
From the list, select a phytree object in the MATLAB Workspace.
Click the Import button.
The app replaces the current tree data with data from the selected object.

Open Original in New Viewer

There may be times when you make changes that you would like to undo. The Phylogenetic Tree app does not have an undo command, but you can get back to the original tree you started viewing with the Open Original in New Viewer command.

From the File menu, select Open Original in New Viewer.

A new Phylogenetic Tree viewer opens with the original tree.

Save As Command

After you create a phytree object or prune a tree from existing data, you can save the resulting tree in a Newick-formatted file. The sequence data used to create the phytree object is not saved with the tree.

From the File menu, select Save As.
The Save Phylogenetic tree as dialog box opens.
In the Filename box, enter the name of a file. The toolbox uses the file extension .tree for Newick-formatted files, but you can use any file extension.
Click Save.
The app saves tree data without the deleted branches, and it saves changes to branch and leaf names. Formatting changes such as branch rotations, collapsed branches, and zoom settings are not saved in the file.

Export to New Viewer Command

Because some of the Phylogenetic Tree viewer commands cannot be undone (for example, the Prune command), you might want to make a copy of your tree before trying a command. At other times, you might want to compare two views of the same tree, and copying a tree to a new tool window allows you to make changes to both tree views independently .

Select File > Export to New Viewer, and then select either With Hidden Nodes or Only Displayed.
A new Phylogenetic Tree viewer opens with a copy of the tree.
Use the new figure to continue your analysis.

Export to Workspace Command

The Phylogenetic Tree app can open Newick-formatted files with tree data. However, it does not create a phytree object in the MATLAB Workspace. If you want to programmatically explore phylogenetic trees, you need to use the Export to Workspace command.

Select File > Export to Workspace, and then select either With Hidden Nodes or Only Displayed.
The Export to Workspace dialog box opens.
In the Workspace variable name box, enter the name for your phylogenetic tree data. For example, enter MyTree.
Click OK.
The app creates a phytree object in the MATLAB Workspace.

Print to Figure Command

After you have explored the relationships between branches and leaves in your tree, you can copy the tree to a MATLAB Figure window. Using a Figure window lets you use all the features for annotating, changing font characteristics, and getting your figure ready for publication. Also, from the Figure window, you can save an image of the tree as it was displayed in the Phylogenetic Tree app.

From the File menu, select Print to Figure, and then select either With Hidden Nodes or Only Displayed.
The Print Phylogenetic Tree to Figure dialog box opens.

Select one of the Rendering Types.

Rendering Type	Description
`'square'` (default)
`'angular'`
`'radial'`
`'equalangle'`	Tip This rendering type hides the significance of the root node and emphasizes clusters, thereby making it useful for visually assessing clusters and detecting outliers.
`'equaldaylight'`	Tip This rendering type hides the significance of the root node and emphasizes clusters, thereby making it useful for visually assessing clusters and detecting outliers.

Select the Display Labels you want on your figure. You can select from all to none of the options.
- Branch Nodes — Display branch node names on the figure.
- Leaf Nodes — Display leaf node names on the figure.
- Terminal Nodes — Display terminal node names on the right border.
Click the Print button.
A new Figure window opens with the characteristics you selected.

Print Preview Command

When you print from the Phylogenetic Tree app or a MATLAB Figure window (with a tree published from the viewer), you can specify setup options for printing a tree.

From the File menu, select Print Preview.
The Print Preview window opens, which you can use to select page formatting options.
Select the page formatting options and values you want, and then click Print.

Print Command

Use the Print command to make a copy of your phylogenetic tree after you use the Print Preview command to select formatting options.

From the File menu, select Print.
The Print dialog box opens.
From the Name list, select a printer, and then click OK.

Tools Menu

Use the Tools menu to:

Explore branch paths
Rotate branches
Find, rename, hide, and prune branches and leaves.

The Tools menu and toolbar contain most of the commands specific to trees and phylogenetic analysis. Use these commands and modes to edit and format your tree interactively. The Tools menu commands are:

Inspect Mode

Viewing a phylogenetic tree in the Phylogenetic Tree app provides a rough idea of how closely related two sequences are. However, to see exactly how closely related two sequences are, measure the distance of the path between them. Use the Inspect command to display and measure the path between two sequences.

Select Tools > Inspect, or from the toolbar, click the Inspect Tool Mode icon .
The app is set to inspect mode.
Click a branch or leaf node (selected node), and then hover your cursor over another branch or leaf node (current node).
The app highlights the path between the two nodes and displays the path length in the pop-up window. The path length is the patristic distance calculated by the seqpdist function.

Collapse and Expand Branch Mode

Some trees have thousands of leaf and branch nodes. Displaying all the nodes can create an unreadable tree diagram. By collapsing some branches, you can better see the relationships between the remaining nodes.

Select Tools > Collapse/Expand, or from the toolbar, click the Collapse/Expand Brand Mode icon .
The app is set to collapse/expand mode.
Point to a branch.
The paths, branch nodes, and leaf nodes below the selected branch appear in gray, indicating you selected them to collapse (hide from view).
Click the branch node.
The app hides the display of paths, branch nodes, and leaf nodes below the selected branch. However, it does not remove the data.
To expand a collapsed branch, click it or select Tools > Reset View.

Tip

After collapsing nodes, you can redraw the tree by selecting Tools > Fit to Window.

Rotate Branch Mode

A phylogenetic tree is initially created by pairing the two most similar sequences and then adding the remaining sequences in a decreasing order of similarity. You can rotate branches to emphasize the direction of evolution.

Select Tools > Rotate Branch, or from the toolbar, click the Rotate Branch Mode icon .
The app is set to rotate branch mode.
Point to a branch node.
Click the branch node.

The branch and leaf nodes below the selected branch node rotate 180 degrees around the branch node.
To undo the rotation, simply click the branch node again.

Rename Leaf or Branch Mode

The Phylogenetic Tree app takes the node names from a phytree object and creates numbered branch names starting with Branch 1. You can edit any of the leaf or branch names.

Select Tools > Rename, or from the toolbar, click the Rename Leaf/Branch Mode icon .
The app is set to rename mode.
Click a branch or leaf node.

A text box opens with the current name of the node.
In the text box, edit or enter a new name.
To accept your changes and close the text box, click outside of the text box. To save your changes, select File > Save As.

Prune (Delete) Leaf or Branch Mode

Your tree can contain leaves that are far outside the phylogeny, or it can have duplicate leaves that you want to remove.

Select Tools > Prune, or from the toolbar, click the Prune (delete) Leaf/Branch Mode icon .
The app is set to prune mode.
Point to a branch or leaf node.

For a leaf node, the branch line connected to the leaf appears in gray. For a branch node, the branch lines below the node appear in gray.

Note
If you delete nodes (branches or leaves), you cannot undo the changes. The Phylogenetic Tree app does not have an Undo command.
Click the branch or leaf node.
The tool removes the branch from the figure and rearranges the other nodes to balance the tree structure. It does not recalculate the phylogeny.

Tip

After pruning nodes, you can redraw the tree by selecting Tools > Fit to Window.

Zoom In, Zoom Out, and Pan Commands

The Zoom and Pan commands are the standard controls for resizing and moving the screen in any MATLAB Figure window.

Select Tools > Zoom In, or from the toolbar, click the Zoom In icon .
The app activates zoom in mode and changes the cursor to a magnifying glass.
Place the cursor over the section of the tree diagram you want to enlarge and then click.
The tree diagram doubles its size.
From the toolbar click the Pan icon .
Move the cursor over the tree diagram, left-click, and drag the diagram to the location you want to view.

Tip

After zooming and panning, you can reset the tree to its original view, by selecting Tools > Reset View.

Select Submenu

Select a single branch or leaf node by clicking it. Select multiple branch or leaf nodes by Shift-clicking the nodes, or click-dragging to draw a box around nodes.

Use the Select submenu to select specific branch and leaf nodes based on different criteria.

Select By Distance — Displays a slider bar at the top of the window, which you slide to specify a distance threshold. Nodes whose distance from the selected node are below this threshold appear in red. Nodes whose distance from the selected node are above this threshold appear in blue.
Select Common Ancestor — For all selected nodes, highlights the closest common ancestor branch node in red.
Select Leaves — If one or more nodes are selected, highlights the nodes that are leaf nodes in red. If no nodes are selected, highlights all leaf nodes in red
Propagate Selection — For all selected nodes, highlights the descendant nodes in red.
Swap Selection — Clears all selected nodes and selects all deselected nodes.

After selecting nodes using one of the previous commands, hide and show the nodes using the following commands:

Collapse Selected
Expand Selected
Expand All

Clear all selected nodes by clicking anywhere else in the Phylogenetic Tree app.

Find Leaf or Branch Command

Phylogenetic trees can have thousands of leaves and branches, and finding a specific node can be difficult. Use the Find Leaf/Branch command to locate a node using its name or part of its name.

Select Tools > Find Leaf/Branch.
The Find Leaf/Branch dialog box opens.
In the Regular Expression to match box, enter a name or partial name of a branch or leaf node.
Click OK.
The branch or leaf nodes that match the expression appear in red.

After selecting nodes using the Find Leaf/Branch command, you can hide and show the nodes using the following commands:

Collapse Selected
Expand Selected
Expand All

Collapse Selected, Expand Selected, and Expand All Commands

When you select nodes, either manually or using the previous commands, you can then collapse them by selecting Tools > Collapse Selected.

The data for branches and leaves that you hide using the Collapse/Expand or Collapse Selected command are not removed from the tree. You can display selected or all hidden data using the Expand Selected or Expand All command.

Fit to Window Command

After you hide nodes with the collapse commands, or delete nodes with the Prune command, there can be extra space in the tree diagram. Use the Fit to Window command to redraw the tree diagram to fill the entire Figure window.

Select Tools > Fit to Window.

Reset View Command

Use the Reset View command to remove formatting changes such as collapsed branches and zooms.

Select Tools > Reset View.

Options Submenu

Use the Options command to select the behavior for the zoom and pan modes.

Unconstrained Zoom — Allow zooming in both horizontal and vertical directions.
Horizontal Zoom — Restrict zooming to the horizontal direction.
Vertical Zoom (default) — Restrict zooming to the vertical direction.
Unconstrained Pan — Allow panning in both horizontal and vertical directions.
Horizontal Pan — Restrict panning to the horizontal direction.
Vertical Pan (default) — Restrict panning to the vertical direction.

Window Menu

This section illustrates how to switch to any open window.

The Window menu is standard on MATLAB interfaces and Figure windows. Use this menu to select any opened window.

Help Menu

This section illustrates how to select quick links to the Bioinformatics Toolbox™ documentation for phylogenetic analysis functions, tutorials, and the Phylogenetic Tree app reference.

Use the Help menu to select quick links to the Bioinformatics Toolbox documentation for phylogenetic analysis functions, tutorials, and the phytreeviewer reference.