This page covers the usage of iTOL annotation editor for Microsoft Excel. If you are using Google Sheets, we have a separate page dedicated to the installation and usage of the Google Sheets version of the editor.

Prerequisites

  1. iTOL annotation editor XLSM file: Download the current version of the editor and save it to your computer
  2. Microsoft Excel: Recent version of Excel for Windows or MacOS.
  3. Macros enabled in Excel: check the beginning of the video tutorial below for an explanation on how to enable macros
  4. iTOL user account: if you don't have an iTOL account, please create it first. Upload the trees you want to annotate into your iTOL account. See iTOL's tree management help page for details.
  5. Once the trees are uploaded to your account, you are ready to start using the iTOL annotation editor

First steps

Open the iTOL annotation editor XLSM file in Excel. You will see a spreadsheet shown on the right. Feel free to create additional sheets in the file, but make sure that iTOL editor remains as the first sheet. Columns A - D are reserved for editor functions, while the main data input area starts with column E:

  1. Login button: click the button to login to your iTOL account. You will be prompted for your login and password. Alternatively, you can input the login into field C5, and your password into field D5. If these are present, clicking the Login button will not prompt for information. Be careful if you save the file, as any password entered into field D5 will be visible in plain text. If you use the prompts to input the login data, this information is not stored anywhere and you can safely save the file.
  2. 'Select a tree' button: once logged in, click this button to display the list of your iTOL workspaces, projects and trees. Select the tree you wish to annotate, and click the Load selected tree button. Once loaded, the tree name will appear in cell B7. You can click the tree name to open your web browser and load the tree in iTOL.
  3. 'Create or edit annotation': This is core functionality of the editor, and is explained in detail below.
  4. 'Save to iTOL': Once you are finished with your annotation editing, click this button to save all data back to iTOL. Once saved, you can refresh the tree view page in your browser to display the updated data.
  5. Various options dependent on the current annotation type will be displayed here.
  6. Main data editing area
ui

Annotation editor user interface

login

Selecting a tree from your iTOL account

Creating or editing tree annotations

After selecting a tree from your account, click the 'Create or edit annotation' button to display the dialog shown on the right. It consists of 4 tabs:

  1. New dataset: create a new dataset on the selected tree
  2. Existing datasets: if the selected tree has some existing datasets, you can load and edit them through this tab
  3. Colored ranges: edit or create new tree colored ranges
  4. Labels: load and edit the labels for tree leaves and internal nodes

There are two checkboxes available:

  1. Include all tree leaves: If checked, tree leaves will be pre-loaded into the sheet editing area, so you don't have to type them manually
  2. Sort nodes: When nodes are pre-loaded into the sheet (for example, when editing an existing dataset or tree labels), these will appear in the same order as they are shown in iTOL when the default sorting is applied

Select the desired function and click the button in the annotation selector to initialize the sheet editing area and the dataset options.

selector

Annotation selector

Entering and saving data

After selecting the annotation type to edit, the editing area will contain the header describing the columns. Column E will always contain the tree node IDs. Type the node ID you wish to annotate into column E, and fill other columns as required (depending on the dataset type, described below).

If you pre-loaded the tree leaf IDs from iTOL, or if you are editing an existing dataset, column F will contain the current node labels (which can differ from the ID). These are displayed for your information only, and do not need to be filled otherwise. If you wish to edit the actual labels, use the 'Labels' tab in the Annotation selector.

When finished with editing, click the Save to iTOL button. If editing an existing dataset or tree labels, a warning message will be shown, to prevent you from accidentally overwriting the current data in iTOL.

warning

Data overwrite warning

Trial mode warning

If you don't have an active subscription or institutional access, iTOL annotation editor will function in trial mode. All functions are available for testing, with one important limitation: only the first 5 rows of your data will be processed and saved on the iTOL server. Existing data in iTOL will be overwritten with these 5 rows, and the rest will be deleted. For example, if you are editing the labels on a large tree, only the first five labels will be saved, and the rest will be gone.

In trial mode, please use separate trees and data uploaded specifically for evaluating the iTOL annotation editor, since data truncation could occur.

To get full unlimited access, visit your iTOL account page.

For unlimited institutional access, have your librarian or other responsible person get in touch with us.

trial

Trial usage warning

Editing tree labels

Select Labels tab in the Annotation selector and load the tree labels into Excel. Tree IDs will be in column E, and their corresponding label in column F. To assign labels to internal nodes, use iTOL's last common ancestor method, if your tree does not have internal node IDs present. Alternatively, you can click on any node in the iTOL web tree display, and click the node ID on the bottom of the popup to copy it to your clipboard. Paste it into the Tree node ID column, and assign the desired label.

editing

Editing tree labels

Editing colored ranges

Select Colored ranges tab in the Annotation selector and load the current ranges into Excel, or to initialize an empty color range input sheet. Tree IDs have to be entered into column E, and their corresponding range color into column G. You can also provide the label for the colored range in column H.

To assign colored ranges to internal nodes/clades , use iTOL's last common ancestor method, if your tree does not have internal node IDs present (row 4 in the example on the right). Alternatively, you can click on any node in the iTOL web tree display, and click the node ID on the bottom of the popup to copy it to your clipboard. Paste it into the Tree node ID column, and assign the desired colored range.

Using the color picker

Whenever you need to provide a color annotation, you can type it directly into the cell, using any iTOL supported format ( hexadecimal, RGB or RGBA). Alternatively, you can use the Color picker button in field C16. Select a cell where you need a color, and click the Color picker button. After selecting a color, its hex code will be entered into the active cell, and the cell background will reflect the selected color.

ranges

Editing colored ranges

Creating or editing datasets

To create a new blank dataset, go to the New dataset tab in the Annotation selector, choose the desired dataset type and options, and click Create a blank dataset.

If your tree already has some datasets present, you can load and edit them through the Existing datasets tab.

Tree IDs have to be entered into column E, and their corresponding data into columns G and onward, depending on the dataset type. To assign data to internal nodes/clades , use iTOL's last common ancestor method, if your tree does not have internal node IDs present. Alternatively, you can click on any node in the iTOL web tree display, and click the node ID on the bottom of the popup to copy it to your clipboard. Paste it into the Tree node ID column, and assign the data as required.

Dataset label and legend color must be set (or can be changed for existing datasets) in cells B15 and B16

dataset

Blank dataset template

Dataset types

Colored strips

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). You can type the colors directly into column G, or use the color picker.

dataset

Example colored strip

Color gradient

In color gradient datasets, each node is associated to a single numeric value, which is mapped to a colored box on the tree. Colors corresponding to the minimum and maximum values (plus optionally the midpoint value) are defined in the iTOL controls box when the dataset is displayed. In the example on the right minimum value is displayed in red, and the maximum in blue.

dataset

Example color gradient

Branch and label styles

This dataset type allows the customization of colors and display styles for tree branches and leaf labels. Tree IDs have to be entered into column E, and their corresponding data into columns G and onward. To assign styles to whole clades , use iTOL's last common ancestor method, if your tree does not have internal node IDs present. Alternatively, you can click on any node in the iTOL web tree display, and click the node ID on the bottom of the popup to copy it to your clipboard. Paste it into the Tree node ID column, and assign the style as desired.

Column descriptions:

  1. Type: can be either 'branch' or 'label'. 'branch' will apply customizations to the tree branches, while 'label' applies to the leaf text labels
  2. What: can be either 'node' or 'clade', and is only only relevant for internal tree nodes. 'Node' will apply the customization only to a single node, while 'clade' will apply to all child nodes as well.
  3. Color: color for the branch or label.
  4. Factor: for type 'branch', specifies the relative branch width, compared to the global branch width setting. # For type 'label', specifies the relative font size, compared to the global font size.
  5. Style: for type 'branch', can be either 'normal' or 'dashed' # for type 'label', can be one of 'normal', 'bold', 'italic' or 'bold-italic'
  6. Background color: optional, and only relevant for type 'label'. Specifies the color of the label background.

dataset

Example branch and label styles

Binary data

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 fields, which you have to define in the header starting with column G. For each field, provide the label in in row 1, color in row 2 and select the desired shape in row 3. After defining the fields, start filling the data in the row 5 and below. Possible values for each node are:

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

Example binary dataset

Simple bar charts

In simple bar charts, each node is associated to a single numeric value which is displayed as a bar outside the tree. Bars will use the same color as the dataset legend (setting in cell B16).

dataset

Example simple bar chart

Multi value bar charts

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. First, you have to define the fields in the header starting with column G. For each field, provide the label in row 1 and its color in row 2. After defining the fields, start filling the data in the row 4 and below.

dataset

Example multi value bar chart

Pie charts

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. First, you have to define the piechart fields in the header starting with column I. For each field, provide the label in row 1 and its color in row 2. After defining the fields, start filling the field data in rows 4 and below. In addition to the pie chart values, you have to fill two columns for each node:

  1. 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 (position 0 is exactly at the start of node branch, position 0.5 is in the middle, and position 1 is at the end).
  2. Radius: relative radius of the piechart, compared to all others. Actual size will depend on the maximum radius setting in the iTOL controls when the dataset is displayed. For external pie charts, radius will depend on the space available between the leaves, and can be changed by setting the vertical scaling factor on the 'Advanced' controls tab in iTOL.

dataset

Example pie charts

Heatmaps

In heatmaps, each node is associated to multiple numeric values, which are displayed as a set of colored boxes. Values are mapped to a color gradient defined in the dataset options when the dataset is visible in iTOL. Specify missing or null values using the letter 'X'. First, you have to define the fields in the header starting with column G. For each field, provide the label in row 1. After defining the fields, start filling the data in the row 3 and below.

dataset

Example heatmap

Text labels

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.

Column descriptions:

  1. Position: if this value is -1, label will be external (ie. displayed outside the tree). Otherwise, it should be a number between 0 and 1, and the label will be positioned at the specified value along the node branch (position 0 is exactly at the start of node branch, position 0.5 is in the middle, and position 1 is at the end)
  2. Color: color for the label
  3. Style: font style for the label, can be one of 'normal', 'bold', 'italic' or 'bold-italic'
  4. Factor: specifies the relative font size, compared to the global font size.
  5. Text label: actual text of the label
dataset

Example text labels

Connections

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

Column descriptions:

  1. Destination node ID: connection line will start in node specified in the column E, and finish in node specified in the column G. Standard iTOL node ID rules apply.
  2. Width: relative width of the connection line. All width values are compared, and drawn proportionally to the maximum width specified in the dataset settings.
  3. Color: color of the connection line
  4. Style: line style, can be either 'normal' or 'dashed'
  5. Label: connection label, which is show when hovering over the line in the web interface
dataset

Example connections

Shape plots

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.

First, you have to define the fields in the header starting with column G. For each field, provide the label in row 1 and its color in row 2. After defining the fields, start filling the data in the row 4 and below.

dataset

Example shape plot

Branch symbols

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.

Column descriptions:

  1. Symbol: specifies the symbol shape: rectangle, circle, star, triangle right, triangle left or checkmark
  2. Size: relative size of the symbol. Maximum size in the dataset will be displayed using pixel value specified in the dataset options, while all others will be proportionally smaller
  3. Color: symbol color
  4. Fill: if set to 'no', only the outline of the symbol will be drawn
  5. Position: is a number between 0 and 1 which defines the position of the symbol on the 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.
  6. Label: an optional label which is displayed when hovering over the symbol in iTOL's user interface
dataset

Example branch symbols

Error navigator

If any problems are detected in your data when saving to iTOL, you will get an error message and an Error navigator dialog will be displayed, shown on the right. In addition, up to 30 error cells in your sheet will be highlighted in red, and will display the actual error message when selected. Due to Excel limitations, only 30 errors can be highlighted at once.

You can use the Previous and Next buttons to quickly navigate among the cells which contain errors. After correcting all the problems, you can save the data to iTOL.

errors

Error navigator

Video tutorial

If you want to try the steps shown in the tutorial, you can download the phylogenetic tree and the example dataset and upload them to your iTOL account. Please check the iTOL help page if you need assistance with uploading, or contact me directly.