Help and FAQs

Binary data

Leaves 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.

Example:

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

Graphical representation:

Simple bar charts

Leaves 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.

Example:

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

Graphical representation:

Multi-value bar charts

Leaves have multiple values (up to a 100) associated with them. Leaf 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. 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 the standard hexadecimal RGB notation).

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 the standard data points for each node, first field after the node ID can be 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). Defining the radius is optional, but data for leaves without a defined radius will be displayed as a multi-value bar, using the rules defined above (in the example below, Gallus gallus and Pan troglodytes have radii defined, so their data is displayed as a pie chart).

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,20,20,20,20 Mus_musculus,10,20,30,40 Rattus_norvegicus,20,10,40,40 Gallus_gallus,R50,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 the 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 the 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.

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 leaf 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 leaf 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

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.

Example dataset:

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 or the width specified. 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.

Example:

Dataset file: LABELS,mylabel_1,mylabel_2,mylabel_3,mylabel_4 Gallus_gallus,-10,-5,0,5 Rattus_norvegicus,-5,0,5,10 Mus_musculus,-20,0,20,30 Homo_sapiens,-10,5,15,25 Pan_troglodytes,-5,0,10,30

Graphical representation:

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.

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:

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 for each HGT. Use the standard RGB hexadecimal notation (for example, 0xff0000 for red) and put the color after the destination node ID, separated with a | symbol (vertical line).

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.
separators | | | | | | ((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+INT1|0x0000ff: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 are separated from destinations with a | (vertical line) sign.