Tree Viewer Formatting

Introduction

This manual demonstrates how to format trees in Genome Workbench Tree view. For additional information please refer to Working with multiple views tutorial.

In order to get the full benefit of this tutorial you will need to download the sample data set for the Barcode project.

Get the tools and sample data

The sample data set contains a project that references a set of sequences for the Collembola species. These sequences are all examples of cytochrome oxidase from several closely related organisms. In addition the project contains a protein multiple alignment generated using MUSCLE and a phylogenetic tree reconstructed from this alignment.

MUSCLE is not distributed with Genome Workbench but it is found here: http://www.drive5.com/muscle/

The sample data can be obtained from: https://ftp.ncbi.nlm.nih.gov/toolbox/gbench/tutorial/Tutorial2/BX530088_BX572102.comp.zip

Labeling

The phylogenetic tree, by default, displays the sequence identifier at each node. This can be changed by using the Settings option in the right-click context menu. When you select this, you see a tabbed dialog. Select the Labels tab to change the labels. This dialog contains some simple labeling options to select the accession or organism name. In addition, you can select Custom Labels to build a label from the available properties in the tree. The example here uses the label

$(label) - $(organism)

To create custom labels like this, select the properties you want from the dropdown list and use the insert button to add them to the label format. Any other text, e.g. "_", can be added by typing it directly into the Format string field.

Once the labels are set, you will see the phylogenetic tree view change to match the image on the right. Each node is now marked with the sequence accession as well as the species name.

Edge color and gradient options

To set an explicit edge color, set the color of the edge in the child node via:

$EDGE_COLOR [255 0 0 255]

The color value is of the form: [0..255, 0..255, 0..255, 0..255]. The updated edge will be the edge from the node where $EDGE_COLOR is set to its parent. To make the color vary between child and parent, set $EDGE_GRADIENT to 1 in that same node:

$EDGE_GRADIENT 1

And the color on the edge will be blended between the child's color and its parent's color.

If the child node has a cluster color set (if it has a cluster id and the current color mode in "Settings.." is 'perform coloration of tree clusters') the cluster color will take precedence over $EDGE_COLOR.

Example

In the following image the rightmost (red) node has the properties:

$EDGE_COLOR: [255 0 0 255]

$EDGE_GRADIENT: 1

The next node from the right (green on one side, red/green on the other) has property:

$EDGE_COLOR: [0 128 0 255]

Its parent node (green on one side, grey to parent) has no properties related to edge coloring.

Node Markers

Sometimes it may be desirable to highlight individual nodes in the tree with a marker attribute that will change the color and size of the displayed node. Markers are added as a property in the "Node Properties" dialog. You can display this dialog by using the Properties option in the right-click context menu for the node.

Markers are created by adding a property with name "marker" to the properties list for a node. The marker value may include one or more colors and, optionally, a size parameter. The colors are specified as RGB values between 0 and 255 between square brackets, e.g. [64 0 128]. The numbers may be separated by commas and/or spaces. If a fourth value, commonly called the alpha channel, is given between the brackets, it is ignored. When multiple colors are given, the marker is divided evenly between the given colors, and looks much like a pie chart.

Examples

Red marker, default size

[255 0 0]

Marker that is 50% red and 50% green with large size

[0 255 0] [255 0 0] size=4

Subtree Boundaries

The phylogenetic tree supports adding a colored boundary to one or more subtrees. Boundaries are added as a property to the parent node of the subtree using the "Node Properties" dialog. You can display this dialog by using the Properties option in the right-click context menu for the node.

Boundaries are created by adding a property with name "$NODE_BOUNDED" to the properties list for a node. There are several parameters for a boundary including its shape, color, border width and whether or not the boundary should include text. It is also possible to define different boundary shapes for each of the different layout methods. Parameters other than the shape will remain the same for each layout method.

Parameters for the boundary regions are not case-sensitive. Colors are specified in the format [0..255, 0..255, 0..255, 0..255] for red, blue, green and, optionally, alpha. The numbers may be separated by spaces and/or commas. Parameters that require a value are specified in the form "parameter=x", and the possible values for 'x' are shown below. Boolean parameters can be 'true', 'yes', 'y', 'false', 'no', or 'n'. Parameters such as color and border that apply to more than one boundary shape will be applied to all applicable shapes.

Shape Parameters

The following parameters specify the shapes to be used for different layouts. If the same boundary shape is to be used for all layouts, specify only the 'Shape' parameter. To override the 'Shape' parameter for other layouts, specify the shape for that layout.

Shape={Rectangle, RoundedRectangle, Triangle}

RectCladogram={Rectangle, RoundedRectangle, Triangle}

SlantedCladogram={Rectangle, RoundedRectangle, Triangle}

Radial={Rectangle, RoundedRectangle, Triangle}

ForceLayout={Rectangle, RoundedRectangle, Triangle}

Appearance Parameters

These parameters apply to all the different shapes. The boundary color is specified as [r, g, b, a] without the 'keyword=' syntax and it can include an optional transparency, or alpha, value where 0 is fully transparent and 255 is fully opaque. The 'DrawEdge' parameter adds a 1-pixel border to the boundary. The edge color defaults to black but can be changed with the 'EdgeColor' parameter. 'Border' expands the overall shape by a specified number of pixels and 'Corner' rounds off the corners in RoundedRectangles and Triangles. Since rounding corners brings corners inward, it may be helpful to increase 'Border' to compensate. If 'IncludeText' is true, the boundary shape will be expanded to include node labels.

[0..255, 0..255, 0..255, 0..255]

Border=n

Corner=n

DrawEdge={true, false}

EdgeColor=[0..255, 0..255, 0..255, 0..255]

IncludeText={true, false}

Triangle Parameters

This last set of parameters applies only to triangles. If 'AxisAligned' is true then the shape is aligned with the nearest x or y axis. This defaults to 'true'. The 'TextBox' parameter forces the text of the bounded nodes to be placed in a square box rather than expanding the triangle to include the text. Lastly, 'TriOffset' is the distance behind the root node at which the triangle apex should be placed. It defaults to '40' units.

AxisAligned={true, false}

TextBox={true, false}

TriOffset=n

Examples

Green rectangle boundary for all layouts with text included but no border or edge.

[0 255 0 255]

shape=Rectangle

IncludeText=true

Red triangle that does not include a text box and has rounded corners and a black edge.

[255 0 0 128]

Shape=Triangle

corner=10

border=10

textbox=false

drawedge=y

AxisAligned=false

Blue rectangle with rounded corners for the rectangular cladogram layout, triangle for slanted cladogram and force layouts and rounded rectangle for radial layouts. Boundaries will not be expanded to include text. Corners will be rounded and a 10-pixel border will expand the boundary size.

[0 0 255 128]

shape=RoundedRectangle

SlantedCladogram=Triangle

Radial=RoundedRectangle

ForceLayout=Triangle

drawedge=n

corner=10

border=10

textbox=false

IncludeText=false

AxisAligned=false

Loading Attributes

To update the properties of nodes in a tree from a file, right-click on the background to bring up the context menu, and then select Load Attributes. The Loading Attributes feature allows you to update the properties of nodes in a tree by loading them from a flat file. The attributes in the file can include both updates to existing nodes attributes as well as new attributes. The first field in the task is used to update the nods in the tree.

The file that provides the updates to the node properties has a well-defined format an example of which is shown below. The first line of the file must contain the file-identifier:

#BKBTA-1

The next line must specify the names of all the node properties that are given in the file. The list of property names should start with # and the individual properties should be separated by spaces or tabs. The first property will be used to match entries in the file with nodes in the tree.

#seq-id cluster-id label dist

After these two lines, the following lines contain the actual node identifiers and properties to update. Additionally, any lines after the first two lines that start with # are read as comments and will be ignored. The list of properties for each node must be separated by tabs, not spaces.

AAT66197 2 Hypogastrura concolor 0.02

This is an example that provides a cluster-id for s set of nodes in the sample barcode project:

#BKBTA-1

#seq-id cluster-id

#Add a cluster id to the tree

AAT66197 9

AAT66196 9

AAT66189 9

AAT66223 2

AAT66236 2

AAT66216 2

AAT66230 2

AAT66203 2

AAT66195 2