Browser requirements

iTOL uses Javascript and HTML5 Canvas element to draw the trees. Any modern, standards-supporting browser should work fine. Display of very large trees (more than 10'000 leaves) or trees with very many datasets will be greatly influenced by the speed of your computer and available memory. In our tests, Webkit based browsers offer the best performance (Chromium/Google Chrome, Opera and Safari).

iTOL's user account login and several other features require browser cookies, so make sure your browser or firewall are not filtering them.

If you encounter problems with tree or dataset display, please contact the developer.

User interface

Check our user interface video tutorial.

  1. Main tree display shows the current tree. To move/pan the tree, simply click and drag with your mouse.
  2. Zoom controls: In addition to mouse wheel, zoom icons can be used to change the display zoom level. Clicking the 'zoom fit' icon will return the tree to the initial zoom/position.
  3. Other functions: Hover over the info icon to display basic information about the current tree. Search icon can be used to quickly find a specific leaf or internal node.
  4. Main control panel: Most iTOL's functions are available here, split over 4 tabs.
  5. Colored ranges/datasets box: If colored ranges or datasets are present in the tree, they will be listed here.

The main control box and all other dialogs/legends can be freely moved by clicking on their title bars and dragging them.

iTOL tree viewer user interface

iTOL tree viewer user interface

Functions

Check our iTOL functions video tutorial.

Display modes

iTOL can display phylogenetic trees in 3 different modes:

  1. normal (rectangular)
  2. slanted (triangular)
  3. circular
  4. unrooted (radial)

To switch the display mode, click the corresponding button in the Display mode section of the Basic controls tab.

Trees which contain branch length information will be displayed as phylograms by default. To display them as cladograms and ignore the branch length information, select the Ignore option in the Branch lengths section of the Basic controls tab.

Slanted mode is a special version of the normal display mode. To display a tree in slanted mode, switch the display mode to Normal first, and then set the Slanted option on the Basic controls tab to Yes.

Tree display can be further customized through several options in the Basic and Advanced control option tabs:

  • Rotation: is used to rotate whole tree clockwise by the specified angle (in degrees)
  • Arc: is used to define the total angle which the tree will cover in circular mode (default is 350°)
  • Inverted display: normal and circular displays can be inverted by using this option
  • Label font/style: change the font family, style, size and color of all tree labels
  • Branch lines: change the width and color of tree branches
  • Scaling factors: increase/decrease the horizontal or vertical scale, stretching/shrinking the tree in the selected dimension
  • Leaf sorting: by default, iTOL will put the branches with fewer leaves to the "top" (when looking at a tree in normal mode), resulting in a nicer, stair-like display. This option can be used to disable the sorting and use the original order as defined in the tree file.
iTOL tree display modes

iTOL tree display modes

Support and other metadata values

If a tree contains bootstrap information, or other numeric metadata (such as various MrBayes metadata fields), these can be visualized by selecting Display under Bootstraps / metadata section of the Advanced controls tab. Select the desired metadata source using the Data source selector, and set the Display range values to select the range which should be displayed. By default, all values are included.

The metadata can be visualized in 4 different ways:

  • Symbol: select the shape type, minimum and maximum size and the color. Minimum/maximum sizes selected will be used as the radii/sizes for the shapes corresponding to the minimum/maximum metadata value. Note that minimum size can be larger than maximum.
  • Text: values will be displayed as text labels on the branches
  • Color: tree branches will be colored according to their metadata values and the color gradient defined in the control box
  • Width: tree branch widths will be set according to their metadata values. Minimum/maximum widths selected will be used as the widths for the branches with minimum/maximum metadata value. Note that minimum width can be larger than maximum.
Bootstrap value display options

Bootstrap value display options

Branch lengths and internal tree scale

If a tree contains branch length information, these can be visualized by selecting Display under Branch lengths section of the Advanced controls tab. Values will be displayed as text labels directly on the branches.

In addition, an internal tree scale can be displayed by selecting Display under Internal tree scale section of the Advanced controls tab. You can set the repeat values and colors for 2 different sets of the scale lines.

Branch lengths and the internal tree scale

Branch lengths and the internal tree scale

Pruning the tree

Pruning is a process of selecting one or mode branches from the original tree and creating a new, smaller tree.

To start pruning, click on any node and select Add node to pruned tree. A small dialog will be displayed showing the total number of leaves selected. Nodes which are part of the selected clades can also be removed by clicking them and selecting the corresponding function.

When you have selected all nodes of interest, click the Prune tree button to display the new tree.

Pruning a tree in iTOL

Pruning a tree in iTOL

Collapsing clades

Template file: collapse.txt

To collapse a clade, click on any internal tree node and select Collapse node.

You can also use the template file collapse.txt to specify a list of nodes to collapse. Simply drop the file onto the tree, and all listed clades will be collapsed.

By default, collapsed clades will be displayed as triangles with two side lengths proportional to the distances to node's closest and furthest leaves. The shape used to display collapsed clades can be changed under Collapsed nodes section of the Advanced controls tab.

Collapsing clades in iTOL

Collapsing clades in iTOL

Working with tree views

Click the Save/restore view button in the corner of the main controls box to access the functions related to tree views.

All parameters currently selected can be saved as defaults for that tree by clicking Save as default view. Alternatively, you can save them as a named view, which will be available through the Restore view menu.

Working with tree views

Working with tree views

Uploading trees

To upload a tree, go to the 'Upload' page. If you are logged into your iTOL account, you can use the upload button at the bottom of each project box. You can also simply drag and drop one or multiple tree files onto the footer of each project box.

Your trees should be in plain text files, and in one of the supported formats (Newick, Nexus, PhyloXML or Jplace). When uploading .jplace files, make sure that the file extension is .jplace, or the format will not be recognised correctly.

Support for NHX and MrBayes metadata

iTOL can parse various metadata from MrBayes and NHX trees. All numeric metadata values will be extracted, and available for visualization through the 'Bootstrap/metadata' section in the advanced controls tab. In addition, NHX tag name can be used to specify internal node IDs (see examples below).

Example trees in Newick format:

  Tree with bootstraps and branch lengths:

   (A:0.1,(B:0.1,C:0.1)90:0.1)98:0.3);

    A, B, C  : leaf names
    0.1, 0.3 : branch lengths
    90,98    : bootstrap values


  Tree with internal node IDs:

   (A:0.1,(B:0.1,C:0.1)INT1:0.1[90])INT2:0.3[98]);

    A, B, C    : leaf names
    INT1, INT2 : internal node IDs
    0.1, 0.3   : branch lengths
    90,98      : bootstrap values


  Tree with NHX style metadata:

   (A:0.1,(B:0.2,(C:0.2,D:0.3):0.4[&&NHX:conf=0.01:name=NODE1]):0.5);

    A, B, C   : leaf names
    internal node will have the ID NODE1
    metadata value 'conf' will be available for visualization


  MrBayes tree with full metadata:

   (
        n1[&prob=1.00000000e+00,prob_stddev=0.00000000e+00,prob_range={1.00000000e+00,1.00000000e+00},
           prob(percent)="100",prob+-sd="100+-0"]:7.827820e-02[&length_mean=7.95052056e-02,
           length_median=7.82782000e-02,length_95%HPD={5.41722800e-02,1.09222000e-01}],
        n2[&prob=1.00000000e+00,prob_stddev=0.00000000e+00,prob_range={1.00000000e+00,1.00000000e+00},
           prob(percent)="100",prob+-sd="100+-0"]:1.029146e-01[&length_mean=1.03620749e-01,
           length_median=1.02914600e-01,length_95%HPD={7.64916100e-02,1.34490900e-01}]
   )[&prob=1.00000000e+00, prob_stddev=0.00000000e+00,prob_range={1.00000000e+00,1.00000000e+00},
        prob(percent)="100",prob+-sd="100+-0"]:1.905703e-01[&length_mean=1.91679099e-01,
        length_median=1.90570300e-01,length_95%HPD={1.37001000e-01,2.53530500e-01}];

     n1, n2: leaf names
     prob, prob_stddev, prob(percent) ... : various metadata fields which can be used in
                                           'Bootstraps/metadata' section


    

Annotating trees

Check our tree annotation video tutorial, then play with an example tree and annotations.

In iTOL v3, all annotation is done by simply drag-dropping a plain text data file onto the tree display. When iTOL detects that you are dragging a file over the tree, the display will change and show the message shown on the right. You can drop multiple files at once, and they will be processed sequentially.

Alternatively, you can use the + button in the bottom right corner of the tree display to upload annotation files using a standard file selection box.

Template files for all available annotation types are available in the corresponding sections below. You can also download a ZIP file with all available templates. All template files include comments and detailed instructions. If you have trouble understanding any of the template options, or encounter issues in annotating your trees, please contact the developer.

All annotation files start with an ID keyword (which identifies the annotation type), followed by the SEPARATOR keyword. The selected separator has to be used throughout the file. Most annotation files contain a few mandatory options (for example, LABEL and COLOR) and a set of optional settings. All optional settings can be later adjusted in the web interface through the 'Datasets' tab of the functions box. The actual data associated to each node follows after the DATA keyword.

We have prepared a ZIP archive (example_data.zip) which contains our Tree of Life (filename tree_of_life.tree.txt) and various example annotation files, filled mostly with random data. Try uploading the tree, and then dropping some of the annotation files onto it to get an idea how to prepare the annotations for your own trees.

Drag and drop annotation

Drag and drop annotation

Saving annotation changes

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

Internal node identifiers

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.

Internal node names

Defining internal nodes through last common ancestor method

Branch and label colors and styles

Template file: colors_styles_template.txt

Colors and styles for the branches and labels can be set using the TREE_COLORS annotation file, or interactively through the node popup menus. Simply click on any node or label, and select the desired function from the 'Editing' section of the popup menu.

By using the TREE_COLORS annotation file, you can define the colors, styles and widths/sizes for each individual node or label in the tree. To assign styles to internal tree nodes, check relevant section above.

Interactively setting colors and styles

Interactively setting colors and styles

Colored ranges

Template file: colors_styles_template.txt

Colored ranges provide simple highlighting of certain nodes, clades or sets of leaf labels. Use the buttons in the colored ranges legend box to switch between the range coverage modes (either Labels only or Full clades).

Colored ranges can be defined in the TREE_COLORS annotation file, or interactively through the node popup menus. Simply click on any node or label, and select the desired function from the 'Color' submenu. You can simply create new colored ranges or add nodes to existing ranges.

By using the TREE_COLORS annotation file, you can define a large number of colored ranges without the need to use the interactive mode. Check the template file for details and instructions. To assign ranges to internal tree nodes, check relevant section above.

If you need a colored ranges legend in the exported tree figures, you can create it using a toggle button on the 'Export' control tab. Note that the colored ranges legend is sortable. Simply click a range label in the Colored ranges box, and drag it to a new position.

Working with colored ranges

Working with colored ranges

Changing leaf labels text and internal node names

Template file: labels_template.txt

To quickly change the text assigned to leaf nodes, or to assign/change names for internal tree nodes, use the LABELS annotation file. Leaf labels text can also be changed interactively, by clicking on a label and selecting the Edit option from the Label submenu.

Note that this annotation file only changes the actual text of the labels. If you want to assign colors, font sizes or styles, please check the colors/styles section.

Datasets

iTOL v3 can annotate trees with several types of data, described in detail below. Simply customize a dataset template with your information and drop it onto the tree.

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.

Datasets legend and example controls tab

Datasets legend and example controls tab

Dataset legends

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.

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

1square
2circle
3star
4right triangle
5left triangle
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
Datasets legend

Example individual dataset legend

Dataset scales

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.

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 (Example 2 below and in the figure on the right). Label and color for a scale line are added after the value, separated with dashes (format: VALUE-LABEL-COLOR). Labels will be displayed in popup windows, when hovering over the scale lines.

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

Dataset scales

Datasets scales

Example 1:

DATASET_SCALE,100,200,300,400,500

Example 2:
DATASET_SCALE,100-line1-#ff0000,200-line2-#00ff00,300-line3-#ff0000,400-line4-#00ff00,500-line5-#ff0000
                    

Dataset types

Different dataset types are described below, with links to their corresponding template files. Templates are commented and contain one or more examples explaining various options. If you encounter any problems with using these templates, or do not understand some of the available options, please contact the developer.

Binary

Template file: dataset_binary_template.txt

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:

1square
2circle
3star
4right triangle
5left triangle
6checkmark
Binary dataset with multiple columns

Binary dataset with multiple columns

Simple bar charts

Template file: dataset_simplebar_template.txt

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

3 simple bar chart datasets with a custom scale

Multi value bar charts

Template file: dataset_multibar_template.txt

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

10 value bar chart dataset with aligned fields

Pie charts

Template file: dataset_piechart_template.txt

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

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

Text labels

Template file: dataset_text_template.txt

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.

Text labels displayed on the outside and aligned to the tree

Text labels displayed on the outside and aligned to the tree

Colored strips

Template file: dataset_color_strip_template.txt

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

Two color strip datasets with different widths and black borders

Colored gradients

Template file: dataset_gradient_template.txt

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

Colored gradient dataset

Connections

Template file: dataset_connections_template.txt

Connections datasets allow the drawing of straight or curved lines between any two nodes in the tree. Width, color 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

Example connections dataset with arrow heads displayed

Heatmaps

Template file: dataset_heatmap_template.txt

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

Heatmap dataset with an additional tree

Boxplots (box and whisker diagrams)

Template file: dataset_boxplot_template.txt

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

Boxplot dataset with a custom scale

Protein domains

Template file: dataset_protein_domains_template.txt

Protein domain datasets are visualized as schematic representations of proteins, with a protein backbone and various shapes depicting the locations of individual domains. Even though its primary use is for the display of protein domains, it can be used for various other purposes.

Each node can have one protein definition assigned, with total protein length defined in second field, followed by an unlimited number of domain definitions. Each domain definition consists of 5 parts, separated with vertical lines:

SHAPE|START|END|COLOR|LABEL

Domain shape codes are as follows:

CodeShapeExample
RErectangleRE
HHhorizontal hexagonRE
HVvertical hexagonRE
ELellipseRE
DIrhombus (diamond)RE
TRright pointing triangleRE
TLleft pointing triangleRE
PLleft pointing pentagramPL
PRright pointing pentagramPR
PUup pointing pentagramPU
PDdown pointing pentagramPD
OCoctagonOC
GPrectangle (gap)RE
Example protein domain architecture dataset

Example protein domain architecture dataset, exported from SMART.

'Shape' plots

Template file: dataset_external_shapes_template.txt

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.

1square
2circle
3star
4right triangle
5left triangle
Dot plot with full grid and dataset values displayed

Dot plot with full grid and dataset values displayed

Branch symbols

Template file: dataset_symbols_template.txt

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:

1square
2circle
3star
4right triangle
5left triangle
Example symbols dataset, with one or more symbols per branch

Example symbols dataset, with one or more symbols per branch

Phylogenetic placements

Template file: none, created automatically from .jplace files

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.

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

Multiple sequence alignments

Template file: dataset_alignment_template.txt

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.

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

Example multiple sequence alignment visualized on a tree

Line charts

Template file: dataset_linechart_template.txt

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

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

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

Images

Template file: dataset_image_template.txt

Use this dataset template to display various external images on the tree. Each node in the tree can be associated with an bitmap (any format supported by your browser) or vector image (SVG).

Images can be displayed internally on the tree branches, or outside the tree. In addition, each image's scale and position can be individually adjusted.

Image URL has to be specified in full (including the protocol, e.g. http://), and the images have to be accessible via that URL by your browser. They are not accessed by iTOL directly, unless you export the tree using batch mode.

Several bitmap images displayed directly on the tree

Several bitmap images displayed directly on the tree

Tree management and user account

Check our tree management video tutorial.

Creating an account in iTOL gives you the possibility to easily organize your trees and have an overview of their features, datasets and saved views. Trees are grouped into different projects, and these can be arranged into different workspaces.

Configuration and functions can be accessed by clicking the icons in the corner of project boxes, in the workspace tab bar and at the end of each tree table row.

Working with projects and workspaces:

  • Add/delete a workspace or a project through the functions menus ()
  • Click the workspace label and drag it to rearrange workspace order
  • Click the workspace or project descriptions to edit them
  • Double click project title bars to collapse/uncollapse projects
  • Click and drag the project title to rearrange projects
  • Click and drag the project title to a different workspace tab label to move the project there

To upload trees to a project, you can use the button in the project box, or simply drag and drop one or more tree files to the project footer.

iTOL account

Managing your trees in the iTOL account

Creating figures and tree export

Use the Export tab of the control box to export the current tree into vector or bitmap figures. Depending on the setting selected, it can take a few minutes until the figures are generated.

If you use the exported figures in a publication, please cite one of iTOL publications.

Batch access

iTOL supports batch tree upload and export through a simple CGI interface. We are providing it for advanced users who want to upload or export their trees directly from other scripts/programs. Please be considerate to other users if you're using this method to access iTOL. Make sure to wait at least a few seconds between requests, particularly if exporting to PNG.

Example uploader and downloader Perl scripts are available for download. You can use the example data archive for testing the uploader script.

Batch upload

http://itol.embl.de/batch_uploader.cgi

iTOL batch uploader is a standard CGI script, available at http://itol.embl.de/batch_uploader.cgi. Use a standard POST request to submit your data. Available parameters are described below. Script will produce plain text output (Content-type text/plain), as follows:

  • An error occurred during upload: first line will start with the keyword ERR, followed by a numeric error code and longer description
  • Upload was successful, without warnings: first line will start with the keyword SUCCESS:, followed by a space character and the iTOL tree ID
  • Upload was successful, warnings occurred: warnings will be printed one per line, and the last line will start with the keyword SUCCESS:, followed by a space character and the iTOL tree ID If your upload was successful, store the returned iTOL tree ID for further use.

Batch uploader options

Required parameters

zipFile

a ZIP archive containing the tree and all other dataset and annotation files. Your tree file must have the extension .tree or .tree.txt. All other files can be named as you wish. When the files are processed during upload , they will be sorted by name, allowing you to order the datasets (if required).

Optional parameters

uploadID
Your upload ID, which is generated when you enable batch uploading in your account (click your name in the top right corner of any page to access the option). If an uploadID is not provided, the tree will not be associated with any account, and will be deleted after 30 days.
projectName
Required if uploadID is specified. Project name is case sensitive, and should be unique in your account. We recommend creating a separate project for batch uploaded trees.
treeName
If treeName is not provided, the tree file name will be used instead.
treeDescription
Ignored if uploadID is not provided.

Batch download

http://itol.embl.de/batch_downloader.cgi

iTOL batch downloader is a standard CGI script, available at http://itol.embl.de/batch_downloader.cgi. Use a standard POST or GET request when submitting your download parameters. Available parameters are described below. The script will generate output as follows:

  • An error occurred during export: Output will in Content-type: text/html, and the error will be printed.
  • Export was successful: Output will be in the Content-type matching your selected format (image/svg+xml for SVG, image/png for PNG, application/postscript for PS and EPS and application/pdf for PDF). Make sure your downloader handles the incoming binary data properly.

Batch download parameters

These are the available options, and their supported values:

Required parameters

tree

iTOL tree ID which will be exported

format
Output file format. The following values are supported: svg, eps, pdf and png

Optional parameters

If you don't specify one of the optional parameters, values which are saved as defaults for the tree will be used (or standard defaults, if none were saved).

display_mode
Possible values: 1,2 or 3 (1=normal, 2=circular, 3=unrooted)
tree_x
Tree will be shifted horizontally by this value, positive or negative (value in pixels)
tree_y
Tree will be shifted vertically by this value, positive or negative (value in pixels)
vertical_shift_factor
Vertical tree scaling factor (positive number)
horizontal_scale_factor
Horizontal tree scaling factor (positive number)
current_font_size
Main label font size in pixels (integer >= 9)
current_font_name
Possible values: 'Arial', 'Courier', 'Courier New', 'Verdana', 'Impact', 'Georgia', 'Times New Roman' or 'Monotype Corsiva'
current_font_style
Possible values: 'normal', 'bold' or 'bold italic'
leaf_sorting
Possible values: 1 or 2 (1=normal sorting, 2=no sorting)
label_display
Possible values: 0 or 1 (0=hide labels, 1=show labels)
align_labels
Possible values: 0 or 1 (0=labels not aligned, 1=labels aligned)
label_shift
Amount to shift the leaf labels (positive or negative, in pixels)
dashed_lines
Display dashed lines connecting branches to leaf labels. Possible values: 0 or 1 (0=hide lines, 1=display lines)
ignore_branch_length
Possible values: 0 or 1
slanted_normal
Display tree in slanted (triangular) mode. Note that display_mode must be 1. Possible values: 0 or 1
arc
Angle of the display arc for the circular tree (in degrees, a number between 0 and 360)
rotation
Rotation angle for circular tree (in degrees, a number between 0 and 360)
normal_rotation
Rotation angle for normal tree (in degrees, a number between 0 and 360)
unrooted_rotation
Rotation angle for unrooted tree (in degrees, a number between 0 and 360)
line_width
Width of tree lines (in pixels)
default_branch_color
Default color of tree's branches (hex, RGB or RGBA notation)
default_label_color
Default color of tree's labels (hex, RGB or RGBA notation)
inverted
Inverted display (only for circular and normal mode). Possible values: 0 or 1
circle_size_inverted
For inverted circular display only. Internal radius will be increased by this amount (value in pixels)
range_mode
Colored ranges display style. Possible values: 0,1 or 2 (0=off, 1=cover labels only, 2=cover full clades)<
include_ranges_legend
Include colored ranges legend. Possible values: 0 or 1
ranges_legend_title
Title of the colored ranges legend.
internal_marks
Draw circles to mark the location of internal nodes. Possible values: 0, 1 or 2 (0=Do not display, 1=Display on nodes with one child, 2=Display always)
internal_scale
Draw internal tree scale. Possible values: 0 or 1
internalScale1
Repeat value for the first set of internal scale lines (branch length value)
internalScale2
Repeat value for the second set of internal scale lines (branch length value)
internalScale1Color
Color for the first set of internal scale lines (hex, RGB or RGBA)
internalScale2Color
Color for the second set of internal scale lines (hex, RGB or RGBA)
branchlength_display
Display branch length text labels on branches (possible values: 0 or 1)
branchlength_label_size
Font size for the branch length labels (in pixels, integer >= 9)
bootstrap_display
Display bootstrap values (possible values: 0 or 1)
bootstrap_type
Type of bootstrap display. Possible values: 1, 2, 3 or 4 (1=Symbol, 2=Text label, 3=Branch color and 4=Branch width
bootstrap_symbol
Symbol used to display bootstrap values. Possible values: 1, 2, 3 or 4 (1=Circle, 2=Triangle, 3=Square and 4=Star)
bootstrap_symbol_min
Minimum size for the bootstrap symbol (in pixels)
bootstrap_symbol_max
Maximum size for the bootstrap symbol (in pixels)
bootstrap_symbol_color
Bootstrap symbol color (hex, RGB or RGBA)
bootstrap_slider_min
Minimum bootstrap value to display
bootstrap_slider_max
Maximum bootstrap value to display
bootstrap_label_size
Font size for the bootstrap text labels (in pixels, integer >= 9)
bootstrap_width_min
Branch width for minimum bootstrap value (in pixels), when bootstrap_type=4
bootstrap_width_max
Branch width for maximum bootstrap value (in pixels), when bootstrap_type=4
bootstrap_min_color
Branch color for minimum bootstrap value (hex, RGB or RGBA), when bootstrap_type=3
bootstrap_use_mid_color
Use a three color gradient for bootstrap branch colors (possible values: 0 or 1)
bootstrap_mid_color
Branch color for midpoint bootstrap value (hex, RGB or RGBA), when bootstrap_type=3 and bootstrap_use_mid_color=1
bootstrap_max_color
Branch color for maximum bootstrap value (hex, RGB or RGBA), when bootstrap_type=3
datasets_visible
Comma delimited list of datasets to display (starting with 0, e.g. datasets_visible=0,2,5)

External tools

A selection of iTOL related external tools / helper scripts:

  • phyloT: a tree generator based on NCBI taxonomy which can visualize trees directly in iTOL
  • table2itol: an R script that makes it easy to generate iTOL annotations from spreadsheet files
  • itolAPI: phyton API for iTOL batch access. Note that it works only with iTOL version 2

Please contact the authors of these tools directly if you encounter any issues.