Whenever any tree annotation is added or changed, a warning dialog shown on the right will be displayed. If you want to commit your newly added or updated annotations, simply click Save all changes button. This will store all new data into the iTOL database. If you do not save them, all changes will be lost when the tree is reloaded, or the browser page closed.

Unsaved changes warning dialog

When assigning annotations to internal tree nodes, there are two possibilities:

1. Internal nodes already have IDs assigned (as shown in the tree above): In this case, you can use these IDs directly in all annotation template files.
2. There are no internal tree node IDs: You can specify the nodes using the Last common ancestor method. Select two leaves whose last common ancestor is the node of interest, and use their IDs separated with three minus signs ('---') or a vertical line ('|'). In the example on the right:

   Gallus_gallus|Homo_sapiens   = node INT1
   Mus_musculus---Homo_sapiens  = node INT2
   Pan_troglodytes|Homo_sapiens = node INT3
       

Depending on the dataset type, values associated to internal nodes will only be visible when the node is collapsed. However, such dataset types have an additional option Show internal values, which can force the display of internal node values even when these are not collapsed. Note that this could result in overlapping displays, if there are values for the leaf nodes present as well.

Defining internal nodes through last common ancestor method

iTOL can annotate trees with several types of data, described in detail below. Simply customize a dataset template file with your information and drop it onto the tree. Several dataset types can be created directly in the iTOL web interface.

Dataset display can be switched off and on by using the toggle button () next to each dataset label in the legend box.

Access the dataset options by clicking the corresponding gear icon () in the legend box.

To delete a dataset, hover over its label in the legend box and a click the trashcan icon that appears ().

Number of datasets is limited only by the available memory, and they can all be displayed simultaneously. You can adjust the dataset position by changing the Left margin option, which can be positive or negative.

Several dataset types support editing of their underlying data directly in the web interface. If supported, a button labeled Edit raw data will be present below the dataset options.

Datasets legend and example controls tab

Some dataset types can be created directly in the web interface, without any text templates. Simply click the 'Create a dataset' button in the 'Datasets' control tab (or in the Datasets floating legend box), specify the label and type, and enter the data through the simple spreadsheet-like interface.

For dataset types which support multiple value fields for each node (e.g. Multi value bar charts, Pie charts or Binary datasets), a separate section of the dataset editor is provided to add, remove or change the individual fields.

To edit the data in any cell, double click it and type or select the value, depending on the cell type. Tree node column will provide auto-complete based on the tree IDs and labels. You can select internal nodes which do not have IDs assigned by using the last common ancestor method.

In addition to manual editing of cells, you can simply paste the information from external spreadsheets (for example from Microsoft Excel). Make sure the selected data columns match the dataset editor. Tree node IDs should always be in the first column.

Existing datasets, even if created from template files, can be edited at any time. Simply click the Edit raw data button in the dataset options tab to access the dataset editor interface.

When you are finished with entering new data, or editing existing one, don't forget to save the changes.

Dataset editor

In addition to the regular Datasets legend box, which contains the dataset labels and toggle/configuration buttons, you can define individual dataset legends. These will be displayed only when the dataset is visible, and will also be included in the exported tree figures.

Individual legends are defined in the dataset annotation files using the fields LEGEND_TITLE, LEGEND_SHAPES, LEGEND_COLORS and LEGEND_LABELS.

Legends can also be created or edited by clicking the Edit legend button in the dataset options tab.

Shapes are defined with a number between 1 and 6, or with any domain shape code:

1	square
2	circle
3	star
4	right triangle
5	left triangle
6	checkmark

LEGEND_TITLE,Example legend title
LEGEND_SHAPES,1,2,3,4,5,HV,PD,OC
LEGEND_COLORS,#ff0000,#00ff00,#00ffff,#0000ff,#ff00ff,#ffff00,#ffaabb,#00aa33
LEGEND_LABELS,value1,value2,value3,value4,value5,value6,value7,value8

Example individual dataset legend

Several dataset types support the display of custom scales: Simple bar chart, Multi value bar chart, Boxplot and Protein domains. Scales are defined in the dataset annotation files using the field DATASET_SCALE.

Scales can also be created or edited by clicking the Edit scale button in the dataset options tab.

You can simply provide a list of values which define where the scale lines will be displayed (Example 1 below and in the figure on the right). Optionally, it is possible to define the line color and a label to be displayed with each line, as well as the line style (Example 2 below and in the figure on the right). Label, color, width and style (normal or dashed) for a scale line are added after the value, separated with dashes (format: VALUE-LABEL-COLOR-WIDTH-DASHED-LABEL_SCALE_FACTOR):

• VALUE: the value where the scale line will be displayed
• LABEL: label to be displayed next to the scale line
• COLOR: color of the scale line
• WIDTH: width of the scale line in pixels. If omitted, line will be 1 px wide.
• DASED: if set to 1, scale line will be dashed. If omitted or set to 0, scale line will be normal.
• LABEL_SCALE_FACTOR: font size of the scale label will be multiplied by this number, if specified

To specify negative values, use the keyword − instead of the actual minus sign (e.g. to draw a line at -200px, the value definition would be −200)

Datasets scales

Binary datasets are visualized as filled or empty symbols, depending on the value associated with a node (0 or 1). Each node can have multiple associated values, and each value will be represented by a symbol (defined in FIELD_SHAPES) with corresponding color and label (defined in FIELD_COLORS and FIELD_LABELS). Possible values for each node are:

•  1 : filled shape
•  0 : empty shape
• -1 : shape completely omitted

Shapes are defined in FIELD_SHAPES, with a number between 1 and 6:

1	square
2	circle
3	star
4	right triangle
5	left triangle
6	checkmark

Binary dataset with multiple columns

In simple bar charts, each node is associated to a single numeric value which is displayed as a bar outside the tree. Maximum value in the dataset will correspond to MAXIMUM_WIDTH specified, while COLOR field will define the color of the bars. These can be changed later through the dataset options tab.

In the example on the right, three simple bar charts are displayed. Their position and relation of the individual bars has been adjusted through MARGIN, BAR_SHIFT and HEIGHT_FACTOR options, directly though the web interface.

3 simple bar chart datasets with a custom scale

In multi-value bar charts, each node is associated to multiple numeric values, which are displayed as a stacked or aligned bar chart outside the tree.

Individual fields (values) must have a corresponding label and color, which are defined using FIELD_LABELS and FIELD_COLORS. Maximum sum of field values in the dataset will correspond to MAXIMUM_WIDTH specified, which can also be changed later through the dataset options tab.

Note about the scales: If a custom scale is defined in a multi value bar chart dataset, and individual fields are aligned, the scale will be duplicated and shown in each individual field (like in the example on the right).

10 value bar chart dataset with aligned fields

In pie chart datasets, each node is associated to multiple numeric values, which are displayed as a pie chart directly on the node branch, or outside the tree. Individual fields (values) must have a corresponding label and color, which are defined using FIELD_LABELS and FIELD_COLORS.

First value after each node ID in the DATA section specifies the pie chart position. If this value is -1, pie chart will be external (ie. displayed outside the tree). Otherwise, it should be a number between 0 and 1, and the pie chart will be positioned at the specified value along the node branch (for example, position 0 is exactly at the start of node branch, position 0.5 is in the middle, and position 1 is at the end).

Two pie chart datasets, one with internal and one with external pie charts

In text label datasets, each node is associated to a single text label, which can be displayed directly on the node branch, or outside the tree.

For each label, exact position, color, font style, size factor and degree of rotation can be specified.

External labels can be aligned to the tree, in both circular and normal display mode. This will ignore any other rotation parameters.

Labels are normally rotated to match the current tree rotation. Straight labels option will make all labels appear straight ( or rotated by their individual rotation angles), regardless of the current tree rotation.

Text labels displayed on the outside and aligned to the tree

This dataset type allows the customization of display styles for tree branches and leaf labels. It copies the functionality of TREE_COLORS template file, but acts as a dataset. Therefore, multiple separate styles datasets can be present on a tree, and you can switch between various branch/label styles interactively. If multiple styles datasets are turned on simultaneously, only the last one will be applied.

Style definitions can be applied to single nodes/labels, or to whole clades. Check the template file for details.

Example branch and label styles dataset

In colored strip datasets, each node is associated to a color box/strip and can have an optional label. Similar to all other color definitions in iTOL, color can be specified in hexadecimal, RGB or RGBA notation (if transparency is required).

Each colored strip can have a border of varying width and color.

By using the COLOR_BRANCHES option, the colors of tree branches will match the colored strips above them. Ancestral branches whose children have identical colors will be colored as well, propagating the branch coloring towards the root of the tree.

Two color strip datasets with different widths and black borders

In colored gradient datasets, each node is associated to a single numeric value, which is mapped to a colored box. Dataset values are mapped to a color gradient defined in the annotation file (fields COLOR_MIN, COLOR_MAX and optionally COLOR_MID), and can be later changed through the dataset options tab of the controls box.

Each colored gradient can have a border of varying width and color.

Colored gradient dataset

Connections datasets allow the drawing of straight or curved lines between any two nodes in the tree. Width, color, style (normal or dashed) and opacity can be set for each line. Optionally, arrow heads can be displayed on the lines.

Connection lines will be straight by default, and the curvature angle can be adjusted through CURVE_ANGLE option.

Example connections dataset with arrow heads displayed

In heatmap datasets, each node is associated to multiple numeric values, which are displayed as a set of colored boxes. Dataset values are mapped to a color gradient defined in the annotation file (fields COLOR_MIN, COLOR_MAX and optionally COLOR_MID), and can be later changed.

Individual fields are defined in FIELD_LABELS, which will be displayed above the color matrix. Optionally, an additional Newick formatted tree can be specified using FIELD_TREE. If present, this tree will be displayed above the dataset labels, and will be used to define the order of the fields in the matrix.

Empty data fields can be specified using the letter 'X' instead of the numeric value. These will be colored using a separate color, defined using the option COLOR_NAN.

Heatmap dataset with an additional tree

Box plots (box and whisker diagrams) display the distribution of data based on the five number summary: minimum, first quartile, median, third quartile, and maximum. In addition to a box plot, each node can have an unlimited number of extremes defined, which will be displayed as crosses.

Boxplot dataset with a custom scale

In shape plots, each node has multiple numeric values associated with it. Values will be displayed as geometric shapes of different sizes in consecutive columns outside the tree. Highest value in the dataset will have the largest size, and all others will be scaled down proportionally.

Labels and colors for each column are defined in FIELD_LABELS and FIELD_COLORS. Optionally, a grid can be rendered behind the columns and the actual values can be displayed above the shapes. The shapes can be either filled with the defined colors, or displayed as outlines.

Shape is defined in SHAPE_TYPE, with a number between 1 and 5, but it can also be changed through the dataset options control tab.

1	square
2	circle
3	star
4	right triangle
5	left triangle

Dot plot with full grid and dataset values displayed

Symbol datasets allow the display of various shapes directly on the branches of the tree. For each node, one or more symbols can be defined. Each symbol's color, size and position along the branch can be specified. Symbols can be filled with color, or drawn as outlines.

Symbols are defined as numbers between 1 and 5:

1	square
2	circle
3	star
4	right triangle
5	left triangle
6	checkmark

Example symbols dataset, with one or more symbols per branch

iTOL supports the visualization of .jplace files created by pplacer and RAxML. Simply upload a .jplace file as a any other tree. Note that the file extension must be .jplace, otherwise the file will not be correctly recognised. iTOL will visualize the Newick tree contained in the file, and the phylogenetic placement information will be extracted as a separate dataset. Summary of placements will be automatically created, and can be visualized in various ways by changing the Summary type in the Datasets tab of the main control box.

When summaries are displayed as symbols, click any symbol to display a full list of sequences mapped to it. Clicking on a sequence name will highlight all other branches where it was placed.

Individual sequences can be searched and highlighted through the Query placements form. In the search results list, simply click any sequence to highlight its placement positions. Highlight symbols will be positioned according to distal_length and sized according to like_weight_ratio. Multiple sequences can be highlighted at the same time, using different symbols and colors. Use the Clear highlights button to remove all highlights from the tree.

Example summary of phylogenetic placement data, with full list of matching sequences in a branch.

This dataset type allows the visualization of multiple sequence alignments directly next to the tree. The alignment should be in FASTA format, and must be placed below the DATA keyword in the template file. Consensus sequence (at 50% conservation) and residue conservation will be calculated automatically.

In addition to the most common alignment coloring schemes, it is possible to define custom schemes through the 'CUSTOM_COLOR_SCHEME' option in the dataset template. Multiple custom color schemes can be defined, and they will all be listed in the color scheme selection box in the dataset control tab.

Displaying large alignments (sequences with more than 1000 - 2000 residues) will severely impact performance, please be patient when manipulating the tree display. Due to internal browser limits, alignments blocks that can be displayed are limited to approximately 4000 residues.

Example multiple sequence alignment visualized on a tree

Use this dataset template to visualize line charts. Each node in the tree is associated with a series of points, defined with their X and Y coordinates. Line charts can be displayed horizontally or vertically next to the nodes. To increase the spacing between the tree leaves (and make more space available for the charts), use the tree Scaling factors on the Advanced controls tab.

Custom axes grids can be defined through fields AXIS_X and AXIS_Y. Each line's color and width can be separately defined. AXIS_X will draw horizontal lines (i.e. values correspond to Y values), while AXIS_X will draw vertical lines (i.e. values correspond to X values)

Each line chart can be displayed using dots, lines or both. Default colors for dots and lines can be defined separately.

In addition, a series of color ranges can be defined using the field LINE_COLORS (see below). Each range consists of a Y value and the color, separated using a vertical line. For each point in the dataset, the first LINE_COLORS color whose value is above the point's Y value will be used to color the dot and line extending from it

In the example below, Y value of -10 would correspond to red (#ff0000), Y value of 2 would be black (#000000) and a value of 10 would be green (#00ff00)

LINE_COLORS -4|#ff0000 4|#000000 100|#00ff00

Horizontally displayed line chart with custom axes grid and 3 color ranges for Y values

Circular tree with two copies of a line chart, one displayed vertically, and the other horizontally