Chapter 10 Annotations

Notung can annotate the leaf nodes of both gene and species trees with colors specified by the user. For example, the annotation function can be used to color all nodes associated with a particular taxonomic group (e.g., plants) or a particular subfamily (e.g., HSP70). This can help visually differentiate gene clusters in a large and complex tree, or highlight related nodes that are distantly located in a tree.

The “New” button in the Annotations task panel opens the annotations dialog window (see Figure 10.1), where the user can set the annotation parameters. Each annotation consists of a title used to identify it, a color, and a specification of the nodes that are included in the annotation. The title of an annotation is simply an alphanumeric string used to distinguish it. You may use any string of characters as long as it is unique. The set of nodes associated with a given annotation can be specified in two ways, by pattern matching or by selecting them manually. In the first case, the user provides one or more alphanumeric strings, which are compared with all leaf node names. Leaf nodes that contain one or more of the specified strings as a substring are added to the annotation. Alternatively, nodes can be manually added to the annotation by clicking on them.

Click on image to see larger version

Figure 10.1: (a) The annotations dialog box. This figure shows the creation of an annotation, with the title “primates”, associated with the color red, and the pattern matching terms “hu”. (b) In the Annotations task panel, the list box shows the annotations associated with the currently selected tree. A check box indicates whether the annotation is hidden (unchecked) or showing (checked). The number next to each annotation refers to the number of leaf nodes currently colored by that annotation. If the annotation is hidden, this number is zero.

All annotations for the currently selected tree are shown in the list box in the Annotations task panel (see Figure 10.1b). After an annotation is created, individual nodes can be added to it or removed from it, manually. Annotations can be edited to modify the list of pattern matching terms or to change the color associated with the annotation. Annotations can be shown or hidden at any time.

NOTE: A single node can match more than one annotation, but will only be colored by the most recently created annotation.

NOTE: Annotations only apply to the tree that is currently selected, but can be exported and then imported into another tree. See subsections on importing and exporting annotations at the end of this section.

To create an annotation using pattern matching (recommended):

Click the Annotations tab to enter Annotations mode.
Click the “New” button in the task panel. A dialog box appears.
Select a color in the color palette for the annotation. If you do not select a color, Notung selects red by default.
Enter the title of the annotation in the text field in the center of the dialog box.
Select the radio button marked “Use this comma-delimited list to add nodes.” (This button is selected by default.)
Enter the pattern matching term(s) in the text field, separated by commas. If no terms are entered, Notung will use the title of the annotation as a pattern matching term.
For example, if you want to annotate all the node labels containing HU, enter “HU” in the text field. Notung will annotate any node with a label that contains “HU” as a substring, such as g1_human and g2_human. If you want to annotate all node labels containing “HU” and “GO,” enter “Hu, Go” in the text field. This will also annotate the node g1_gorilla, as seen in Figure 10.2.

NOTE: This process is not case sensitive.
Click “OK.”
Nodes with names that match a string in the comma-delimited list will change color (e.g., Figure 10.2).

If a single node corresponds to more than one annotation, the node will be in the color dictated by the most recently added annotation. The newer annotation will continue to take precedence until the shared node is manually removed from that annotation, the annotation is hidden, or a new, conflicting annotation is added. For example, adding an annotation in yellow for “g1” would change the color of g1_human, g1_cow, g1_mouse, and g1_gorilla to yellow.

Click on image to see larger version

Figure 10.2: A fully annotated gene tree.

To create an annotation with manually added nodes:

Click the Annotations tab to enter Annotations mode.
Click the “New” button in the task panel. A dialog box appears.
Select a color in the color palette to use for the annotation (if you do not select a color, Notung selects Red by default.)
Enter the title of the annotation in the text field in the center of the dialog box.
Select the radio button marked “I want to manually select the nodes and subgroups to add.”
Click “OK.” This will create an empty annotation that does not color any nodes. To color nodes, you must add them to the annotation as described below.

To add nodes to an annotation manually:

NOTE: This operation can only be performed if an annotation has already been created.

Click the “Add Nodes” button in the Annotations task panel
Select the desired annotation by clicking on it in the list box.
Click on nodes in the tree panel. Clicking on an internal node will color all the leaf nodes in the subtree beneath it.
If a selected node is a leaf node, it will be highlighted with the color of the annotation. If it is an internal node, all of leaf nodes below it will be highlighted with the color of the annotation.
If you want to add nodes to another annotation, repeat steps 2 and 3.
When you are finished adding nodes to annotations, click the “Add Nodes” button again to deselect it.

To remove nodes from an annotation manually:

NOTE: This operation can only be performed if an annotation has already been created and nodes have been assigned to it.

Click the “Remove Nodes” button in the Annotations task panel, and then select the desired annotation from the list of annotations.
Click on nodes in the tree panel.
If a selected node is a leaf node, it will be removed (i.e., disassociated) from the annotation and the color of its label will revert to black (unless an earlier annotation also colors that node). Clicking on an internal node removes all of the leaf nodes in the subtree rooted at that node.
When you are finished, click the “Remove Nodes” button again to deselect it.

To edit an annotation:

Select the annotation you want to edit in the list box.
Click the “Edit” button in the task panel. The annotation dialog box will reappear. You can now change the color, title or pattern matching term(s) for this annotation.
Click “OK” when you are done making changes.

To hide/view an annotation:

Select the annotation in the list box.
Click the “Show/Hide” button.
If the annotation was displayed prior to clicking the “Show/Hide” button, the nodes associated with the annotation will revert to black (unless an earlier annotation also colors that node). If the annotation was hidden, the associated nodes will appear in color. A check mark next to the annotation’s name denotes that it is visible (i.e., the current state is “Show”). This is the default status.

To delete an annotation:

This function will remove an annotation from the list of annotations. All nodes associated with it will revert to black. Warning: this operation is not reversible.

Select the annotation in the list box.
Click the “Delete” button in the task panel.
A dialog box will appear to confirm that you really want to delete the annotation. Click “Yes.”

To export an annotation:

Annotations can be exported to a separate file for import into another tree.

Click “File → Export Annotations.”
A file dialog box will appear. Enter a name for the annotation, and click “Save.” The annotations can now be imported from this file to another tree.

To import an annotation:

Annotations can be imported from any file that contains an annotation, including a Notung format tree or an exported annotation file.

Click “File → Import Annotations.”
An open file dialog box will appear, select the annotation file or annotated tree, and click “Open.” The annotations from the file will be added to the open tree. If the open tree was previously annotated, those annotations will still be present.
NOTE: Imported annotations are added to the existing list of annotations. If an imported annotation and a previously existing annotation correspond to the same node, the imported annotation will take precedence.