Help and FAQs

    (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 lenghts
    90,98    : bootstrap values

   (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 lenghts
    90,98      : bootstrap values

Binary data

Nodes of the tree have either zeroes or ones associated with them. Each value will be represented with a square, white for zeroes and your selected color for ones. Values for internal nodes will only be displayed on collapsed clades.

If multiple binary datasets are added to a tree, they will be automatically prevented from overlapping, allowing simultaneous display of several datasets.

Example:

Dataset file: Gallus_gallus,1 Rattus_norvegicus,1 Mus_musculus,0 Homo_sapiens,1 Pan_troglodytes,0

Graphical representation:

Simple bar charts

Nodes have a single value associated with them. Highest value in the dataset is shown as a bar with the selected maximum pixel size, and others are adjusted proportionally to it. Bars will be filled with the color you selected during upload. Values for internal nodes will only be displayed on collapsed clades.

Simple bar charts support scales, as described in the 'Dataset scales' section below.

Example:

Dataset file: Gallus_gallus,50 Rattus_norvegicus,10 Mus_musculus,75 Homo_sapiens,100 Pan_troglodytes,90

Graphical representation:

Multi-value bar charts

Nodes have multiple values (up to a 100) associated with them. Node with the highest sum of values will be represented with a bar with the selected maximum pixel size, and all other values will be adjusted based on it. Values for internal nodes will only be displayed on collapsed clades. First line of the dataset file must contain the labels for individual fields (first field of the line should be LABELS, followed by the actual labels). Labels will be shown when hovering mouse cursor over the bars in the graphical display, and used to display a separate legend in the exported tree images. Second line can be used to define the colors for individual fields (optional; first field should be COLORS, followed by color definitions in standard hexadecimal RGB notation).

Multi value bar charts support scales, as described in the 'Dataset scales' section below.

Example:

Dataset file: LABELS,mylabel_1,mylabel_2,mylabel_3 COLORS,#ff0000,#00ff00,#0000ff Gallus_gallus,20,20,20 Rattus_norvegicus,50,10,75 Mus_musculus,100,50,20 Homo_sapiens,75,50,10 Pan_troglodytes,20,20,50	Graphical representation:
If 'Align individual fields' is selected during upload, each field's start will be aligned based on the maximum values of previous fields.	Graphical representation:

Pie charts

Input file is almost identical to the 'Multi-value bar charts' described above, and follows the same rules. The important difference is that you can associate data with internal tree nodes. Internal nodes can be defined in two ways:

1. If your tree has proper IDs associated with internal nodes (see the first section of 'Uploading and working with your own trees' section), you can use these directly.
2. Use two leaf IDs separated with a vertical line (|), whose last common ancestor will be used as the internal node (see the example below).

In addition to standard data points for each node, first field after the node ID is used to define the radius of the pie chart (in format R + numeric value, for example R50). Values for all the radii defined will be normalized according to the values selected during upload ('Min. radius' and 'Max. radius' pixel values). If radius is not defined, data will be displayed as a multi-value bar, using the rules defined above (always visible for leaves, and visible only on collapsed internal nodes; in the example below, Gallus gallus and Pan troglodytes have radii defined, so their data is displayed as a pie chart).

Actual position of the pie chart on the branch can also be specified as a percentage of the node's total branch length. This optional value can be added after the radius value, separated with a vertical line. Value of 0 translates into the start of the branch, while 1 translates into the end. The default value is 0.5 (ie. the middle of the branch). In the example below, Gallus_gallus has the pie chart position specified as 1.0 ('R50|1.0'), which puts it at the very end of the branch. On the other hand, position value for Pan_troglodytes is 0.2 ('R50|0.2'), and the pie chart is displayed at 20% of the branch length. Note that position values are not limited to range of zero to one (ie. they can be bigger than one, or negative).

Example:

Dataset file: LABELS,test0,test1,test2,test3 COLORS,#ff0000,#00ff00,#0000ff,#ff00ff Gallus_gallus|Homo_sapiens,R50,10,20,20,10 Rattus_norvegicus|Mus_musculus,R100,20,20,20,10 Homo_sapiens|Pan_troglodytes,R50,20,10,10,20 Homo_sapiens|Mus_musculus,R75,10,10,10,10 Homo_sapiens,20,20,20,20 Pan_troglodytes,R50|0.2,20,20,20,20 Mus_musculus,10,20,30,40 Rattus_norvegicus,20,10,40,40 Gallus_gallus,R50|1.0,20,20,20,20

Graphical representation:

Color gradients

Leaves have a single value associated with them. Each value is converted into a colored box, using the color selected during upload.In addition, you can specify the color in the dataset file, using a line starting with field 'COLOR' and using a color hex code after the separator (for example, "COLOR,#ff00ff"). Highest value in the dataset is displayed using the exact color specified, with lower values gradually fading towards white (for the lowest value in the dataset).

Example:

Dataset file: Gallus_gallus,50 Rattus_norvegicus,5 Mus_musculus,20 Homo_sapiens,10 Pan_troglodytes,40

Graphical representation:

Color strips

You can define your own colors for each leaf separately. Use standard hexadecimal color notation (for example, #ff0000 for red). Optionally, each leaf can have a text label associated with it. The label, if defined, will appear in a popup window when the mouse pointer is above the corresponding dataset point. Labels should be the 3rd field in the dataset file (in the example below, it would be "Homo_sapiens,#0000ff,MY_LABEL").

In addition, you can use this dataset type to automatically assign colors to tree branches. Ancestral branches whose children have identical colors will be colored as well. In the example below, upload option 'color branches and show boxes' was used (in the Branch coloring section).

Example:

Dataset file: Gallus_gallus,#ff0000 Rattus_norvegicus,#00ff00 Mus_musculus,#00ff00 Homo_sapiens,#0000ff Pan_troglodytes,#0000ff

Graphical representation:

Time series

This dataset will provide an animated view of multiple values associated with each leaf (ie. an animated simple bar chart). First line of the dataset file must contain the labels for individual values (first field of the line should be LABELS, followed by the actual labels). Labels will be shown in the animation control box, above the progress bar. Second line can be used to define the colors for individual fields (optional; first field should be COLORS, followed by color definitions in standard hexadecimal RGB notation).

When a time series is displayed in iTOL, you will see a 'Time series control' box, which is used to control the animation. Click the play/pause button to start or stop the animation. You can also drag the progress bar indicator to quickly find a specific field.

Time series datasets support scales, as described in the 'Dataset scales' section below.

Example:

Dataset file: LABELS,test0,test1,test2,test3,test4 COLORS,#ff0000,#00ff00,#0000ff,#ff00ff,#ffff00 Gallus_gallus,10,30,20,50,30 Rattus_norvegicus,30,20,40,5 Mus_musculus,20,50,10,30,50 Homo_sapiens,10,30,40,20,40 Pan_troglodytes,30,10,50,20

Graphical representation:

Protein domain architecture

Each node in the tree can have a protein domain architecture associated with it. Even though it's primary use is for the display of protein domains, it can be used for various other purposes. The format is as follows: Each line should have a node ID, total protein length, and the definitions of the domains. The domain definitions field contains one or more domains, separated using the same character which is used in the first two fields. Each domain definition consists of 5 parts, separated with vertical lines ("|"). For example:

RE|100|150|#ff0000|SH2

The fields are:

1. RE: 2 character code defining the domain shape (see below for supported shapes)
2. 100: domain start position
3. 150: domain end position
4. #ff0000: color definition (hexadecimal RGB notation)
5. SH2: domain label

Supported domain shapes:

Code	Shape	Example
RE	rectangle
HH	horizontal hexagon
HV	vertical hexagon
EL	ellipse
DI	rhombus (diamond)
TR	right pointing triangle
TL	left pointing triangle
PL	left pointing pentagram
PR	right pointing pentagram
PU	up pointing pentagram
PD	down pointing pentagram
OC	octagon
GP	rectangle (gap)

'GP' shape (for 'gap') will be displayed as a 1/3 height rectangle, and it's primary use is for the gaps in the multiple sequence alignments.

Exported trees with a protein domain architecture dataset will contain an additional legend listing all domains and their labels. The legend will not be shown in interactive mode, since you can hover your mouse cursor over any domain to show its label and other associated information. Domain architectures for internal nodes will only be displayed on collapsed clades.

Protein domain arcitectures support scales, as described in the 'Dataset scales' section below.

Example:

Dataset file: Gallus_gallus,300,EL|10|50|#ff0000|DUF17,DI|200|290|#aaff00|DUF22 Rattus_norvegicus,360,TR|50|170|#aa00cc|DUF2,TL|175|270|#f044ff|DUF4 Mus_musculus,320,DI|80|190|#f0c0c0|DUF7,EL|175|225|#3400ff|DUF10 Homo_sapiens,350,RE|100|150|#a0faa0|DUF4,HH|250|310|#ffff00|DUF7 Pan_troglodytes,350,HV|20|110|#0043ff|DUF1,EL|125|325|#0dfff0|DUF2

Graphical representation:

Heatmaps

Leaves have multiple values associated with them, which are converted into colors based on gradients selected during upload. You have to select 3 values and their correpsonding color: maximum,minium and midpoint. They don't need to correspond to the actual min and max values in the dataset, and midpoint does not need to be exactly in the middle. These values are used to construct 2 color gradients (from minimum to mindpoint and from midpoint to maximum). Dataset values are then mapped to these gradients to select their color. Each value will be represented with a colored box of the width specified during upload. The whole dataset cannot be wider than 5000 pixels, so pratically the limit is 5000 values per leaf (with 1px box width).

First line of the dataset file must contain the labels for individual fields (first field of the line should be LABELS, followed by the actual labels). Labels will be shown when hovering mouse cursor over the boxes in the graphical display, and used to display a separate legend in the exported tree images.

An optional Newick formated file can be uploaded with the heatmap dataset. Its leaf IDs must exactly match the dataset labels. The tree will be used to sort the dataset fields, and will be displayed above the dataset (in normal display mode only).

Example:

Dataset file: LABELS,mylabel_1,mylabel_2,mylabel_3,mylabel_4,mylabel_5,mylabel_6 Gallus_gallus,-10,-5,0,5,-10,15 Rattus_norvegicus,-5,0,5,10,-15,15 Mus_musculus,-20,0,20,30,-25,30 Homo_sapiens,-10,5,15,25,-30,25 Pan_troglodytes,-5,0,10,30,-10,20	Graphical representation:
Additional tree file: (((mylabel_1,mylabel_2),(mylabel_3,(mylabel_4,mylabel_6))),mylabel_5);

Boxplots

Boxplot datasets can be uploaded in 2 ways:

1. Direct upload of five-number summaries and extremes: each leaf has a least 5 values associated with it. Starting from left, the first 6 fields must be: leaf ID, minimum value, lower percentile, median, upper percentile and maximum value. An unlimited number of extra fields can be added, each representing an outlier value (either high or low).
2. Upload of raw data: each leaf has at least 4 values associated with it. iTOL will calculate all needed values to display a boxplot for each leaf. You can specify the lower and upper percentile during upload (by default, these will be 25% and 75%). You can also define the step constant, which will be multiplied with each leaf's box size to define the related whisker size. The constant can be any number above zero, and is normally set to 1.5. When uploading raw data, you can also optionally control the drawing of outliers, using the 'Calculate extremes' option in the upload form.

Boxplots support scales, as described in the 'Dataset scales' section below.

Example:

In this example, the dataset contains the five-number summary for each leaf, plus several outliers (for Gallus_gallus, Mus_musculus and Pan_troglodytes)

Dataset file: Gallus_gallus,10,15,20,25,30,0,5,60 Mus_musculus,5,20,40,50,60,70,80 Rattus_norvegicus,15,30,40,50,65 Homo_sapiens,10,20,35,50,55 Pan_troglodytes,10,20,40,55,65,80

Graphical representation:

Connections

This dataset type is only available in inverted circular display mode. Any two nodes in the tree (leaves or internal) can be connected with a line of specified width, color and transparency. Additionaly, each connection can have an associated label, which will be shown in the popup window when mouse pointer is hovering above the line. Each line in the dataset must contain the following fields:

NODE_ID_1  NODE_ID_2  LINE_WIDTH  LINE_ALPHA  LINE_COLOR  LABEL

If your tree doesn't have internal node IDs, you can use the last common ancestor method described below, in the 'Defining names for internal nodes' section. LINE_ALPHA defines the transparency of the line (from 0 for fully transparent to 255 for opaque). LINE_COLOR should be in standard hexadecimal color notation (for example #ff0000 is red), and LINE_WIDTH represents the width in pixels (valid range is 1-1000).

Example:

Dataset file: Homo_sapiens,Gallus_gallus,10,255,#ff0000,Example connection Anopheles_gambiae,Homo_sapiens|Mus_musculus,50,125,#00ff00,Connection to internal node Mus_musculus,Danio_rerio,5,255,#0000ff,Another leaf to leaf connection Gallus_gallus|Danio_rerio,Anopheles_gambiae|Caenorhabditis_elegans,100,100,#ffff00,Internal to internal Caenorhabditis_elegans,Eremothecium_gossypii,200,55,#00ffff,Connection 5 Schizosaccharomyces_pombe,Caenorhabditis_briggsae,50,100,#ff00ff,Connection 6

Graphical representation: Connections example (click to enlarge)

Circles

Nodes have multiple values (up to a 50) associated with them. Values will be shown as circles of different radii. Highest value in the dataset will have the largest radius (caluclated based on tree display, depending on available space between the leafs). Radius for the smallest value will be calculated based on the percentage selected in the upload form. Values for internal nodes will only be displayed on collapsed clades.

First line of the dataset file must contain the labels for individual fields (first field of the line should be LABELS, followed by the actual labels). Labels will be shown when hovering mouse cursor over the bars in the graphical display, and used to display a separate legend in the exported tree images. Second line can be used to define the colors for individual fields (optional; first field should be COLORS, followed by color definitions in standard hexadecimal RGB notation). If colors are not defined in the dataset file, all circles will be assigned the same color which was selected in the upload form.

Example:

Dataset file: LABELS,label_1,label_2,label_3,label_4,label_5 COLORS,#ff0000,#00ff00,#0000ff,#ff00ff,#ffff00 Gallus_gallus,20,20,30,80,50 Rattus_norvegicus,50,10,75,40,5 Mus_musculus,100,50,20,60,10 Homo_sapiens,75,50,10,70,30 Pan_troglodytes,20,20,50,90,10

Graphical representation:

DATASET_SCALE,VALUE1-LABEL1-COLOR1,VALUE2-LABEL2-COLOR2

LABELS,mylabel_1,mylabel_2,mylabel_3
DATASET_SCALE,10,20,30,40,50
Gallus_gallus,10,10,20
Rattus_norvegicus,5,10,30
Mus_musculus,15,25,30
Homo_sapiens,5,5,35
Pan_troglodytes,10,15,20
          

DATASET_SCALE,2000-2k line-#0000ff,10000-example 10k-#ff0000,20000
Gallus_gallus,17709
Rattus_norvegicus,22159
Mus_musculus,25307
Homo_sapiens,22287
Pan_troglodytes,21506
          

Annotating HGTs in the Newick tree

HGT information is included in the ID of the originating node. After the ID, first add the keyword #HT# followed with a list of one or mode destination nodes. Separate multiple destinations with a + sign. You can optionally define the color and label for each HGT. Use standard RGB hexadecimal notation (for example, 0xff0000 for red) and put the color after the destination node ID, separated with a | symbol (vertical line). Labels are added in the same way, after the color definition and they will be shown in the popup windows when hovering the mouse pointer over the HGT arrow.

Here are two examples:

Newick tree:	Graphical representation:
(A:0.1,(B:0.1,C:0.1)INT1#HT#A:0.1[90])INT2:0.3[98]); Internal node INT1 is the originating node and leaf A is the destination.
s e p a r a t o r s | | | | | | | | ((A#HT#C:0.1,(B:0.1,C:0.1)INT1:0.1[90])INT2:0.3[98],(D:0.1,E:0.2)INT3#HT#B|0xff0000|my_label1+INT1|0x0000ff|my_label2:0.3[95]); | | | | destination 1 destination 2 There are 3 HGTs annotated here. First is a simple one from leaf A to leaf C. Other two are originating from internal node INT3. HGT towards leaf B will be colored red (0xff0000), and the one towards node INT1 will be blue (0x0000ff). Destinations are separated with a + (plus) sign, and colors and labels are separated from destinations with a | (vertical line) sign.

Defining HTGs in a separate file

Alternatively, you can upload HGT definitions in a plain text file by using the advanced upload option 'Horizontal gene transfers'. The file should be tab separated plain text file with the following fields:

SOURCE_NODE_ID     DESTINATION_NODE_ID     COLOR     LABEL

Both SOURCE_NODE_ID and DESTINATION_NODE_ID can be either leaf IDs or internal node IDs. If your tree doesn't have internal node IDs, use the last common ancestor method described below, in the 'Defining names for internal nodes' section. For the COLOR field, use standard hexadecimal notation (ie. #ff0000 for red). LABEL is optional, and will be shown in the popup windows when hovering over the HGT arrow.

Example:

HGT definition file: Gallus_gallus Pan_troglodytes|Homo_sapiens #0000ff fake_transfer_1 Pan_troglodytes|Homo_sapiens Rattus_norvegicus #00ff00 fake_transfer_2 Mus_musculus Gallus_gallus #ff0000 fake_transfer_3

Tree:

NODE_ID     TYPE     COLOR     LABEL

Gallus_gallus|Homo_sapiens     clade   #0000ff   no_label
Pan_troglodytes|Homo_sapiens   clade   #00ff00   no_label      
Mus_musculus|Homo_sapiens      range   #aaffaa   Euarchontoglires
Homo_sapiens                   range   #00ff00   important1
Gallus_gallus                  range   #ff0000   important2
Homo_sapiens                   label   #ffff00   
Gallus_gallus                  label   #0000ff   
Pan_troglodytes                label   #ff0000   
          

Homo_sapiens           <B>Homo</B> <BI>sapiens</BI>
Pan_troglodytes        Pan <I>troglodytes</I>
Escherichia_coli_K12   <B>Escherichia coli</B> <I>K12</I>

Homo sapiens
Pan troglodytes
Escherichia coli K12

Gallus_gallus|Homo_sapiens     Gnathostomata
Mus_musculus|Homo_sapiens      Euarchontoglires    
Homo_sapiens|Pan_troglodytes   Hominidae
          

Mus_musculus|Homo_sapiens

NODE_ID     BRANCH_LABEL_TEXT    BRANCH_LABEL_COLOR

Gallus_gallus|Homo_sapiens     Gnathostomata
Mus_musculus|Homo_sapiens      Euarchontoglires    
Homo_sapiens|Pan_troglodytes   Hominidae
          

NODE_ID     POPUP_TITLE_TEXT    POPUP_HTML_CONTENT

<textformat tabstops="[IMAGE_WIDTH]">
<img src="http://IMAGE_URL" height="IMAGE_HEIGHTpx" width="IMAGE_WIDTHpx" />
\t&nbsp;
</textformat>