Choose a name under which to save the current style. (Choosing an existing name will cause that style to be overwritten.)

This is a browser-based phylogenetic tree viewer. It is intended for rapid visualisation of phylogenetic tree files such as those produced by BEAST, BEAST 2 and MrBayes. It can also render phylogenetic networks provided in extended Newick format.

IcyTree is compatible with current versions of Mozilla Firefox and Google Chrome. Your mileage may vary with other browsers.

IcyTree is written and maintained by Tim Vaughan and is licensed under version 3 of the GNU General Public License (GPL). Source is available on GitHub. Please feel free to open an issue on the project page if you find a bug or would like to request a feature.

If you use IcyTree to produce figures for an academic publication, please cite the following article:

Vaughan, T. G., IcyTree: Rapid browser-based visualization for phlogenetic trees and networks. Bioinformatics 2017. DOI: 10.1093/bioinformatics/btx155

Introduction

IcyTree is a browser-based phylogenetic tree viewer intended for rapid visualization of phylogenetic trees and networks. While originally intended for the visualization of rooted time trees such as those inferred by Bayesian inference packages such as BEAST and MrBayes, IcyTree can be used to visualize any rooted tree which is provided in a supported format.

In addition, IcyTree can be used to produce visualizations of phylogenetic networks represented using the Extended Newick format.

Warning: IcyTree does not produce visualizations of unrooted trees, but may still display such trees as rooted if a root is implied by the input file format. (For instance, Newick formatted tree files always implicitly specify a root.) It is important not to read significance into the placement of the root in such situations. Instead, one should use a specialised unrooted tree viewer to view such files.

IcyTree should work well on the latest desktop versions of Google Chrome or Mozilla Firefox. These are the only officially supported browsers. While some users report success with web browsers such as Apple’s Safari, we can’t guarantee that all features of IcyTree will work on other browsers.

Citation

If you use IcyTree as part of research that leads to a publication, please cite the following article:

Vaughan, T. G., IcyTree: Rapid browser-based visualization for phlogenetic trees and networks. Bioinformatics 2017. DOI: 10.1093/bioinformatics/btx155

Input/Output

This section describes the various ways of getting phylogenetic data into and out of IcyTree.

Supported input file formats

IcyTree supports the following input file formats:

1. Plain Newick

   These files contain one or more plain Newick tree format strings. In this format, each edge may have a length and each node may have a single label. Multiple Newick tree format strings are separated by newlines. Note that when multiple trees are specified, each Newick string must be terminated by a semicolon ‘;’.

2. NEXUS files with a trees block

   NEXUS files contain an optional trees block which may hold one or more trees specified in Newick format.

3. PhyloXML

   PhyloXML (read the paper or visit the web page) is a dedicated phylogenetic tree format and may contain one or more trees. IcyTree skips any unrooted trees when loading the file.

4. NeXML

   NeXML (read the paper or visit the web page) is another dedicated tree format. IcyTree will skip any unrooted trees when loading the file.

NEXUS Annotations

While the PhyloXML and NeXML formats allow for annotation of nodes and edges, Newick format only allows nodes to be given a single label (which may be interpreted as referring to the node itself or the edge above it). BEAST (all versions) and FigTree use the comment facility of NEXUS to embed annotations in Newick strings. (See here for a technical description.)

IcyTree parses these annotations and makes them available for styling the tree.

Extended Newick

The extended Newick format provides a standard way of representing phylogenetic networks using a simple extension of the Newick format. IcyTree can visualize rooted networks encoded using this format. The specific visualization approach is most suitable for timed networks (where all edge lengths represent lengths of time), but the network topology of all rooted networks is faithfully represented.

Loading trees from files

To load one or more trees from a file, simply open the File menu and select “Load from file”. This will bring up a file selection dialog box from which you can choose a file to load.

Alternatively, simply use a mouse to drag and drop a tree file directly onto the IcyTree window.

Entering trees directly

Trees can also be entered directly into IcyTree by selecting File->“Enter tree directly”. This will open a dialog containing a text box in which trees can be entered using their Newick representation. (In fact, it is possible to enter trees using any of the supported formats, although this feature is probably most useful for simple Newick descriptions.)

Loading trees from a URL

To load one or more trees from a file identified using a URL, open the File menu and select “Load from URL”. This will display a dialog box where you can enter a URL. Pressing the Load button will then attempt to load the file at this URL.

You can also load files from a URL by appending the URL pointing to the tree file to IcyTree’s URL, with a “?” separating the two. For instance, suppose a tree file is hosted at http://example.edu/tree.newick. Pointing your (IcyTree-compatible) web browser at the following address will load IcyTree and open the file:

http://icytree.org/?url=http://example.edu/tree.newick

This also means that it is possible to embed links in web pages which cause browsers to view trees in IcyTree. For instance, clicking on the this link opens an IcyTree visualisation of a primate tree.

Technical note: the URL loading facility requires the server on which the file is hosted allow cross-origin access. In the case that the request fails, IcyTree attempts to use a CORS proxy to access the file, but this may fail if the availability of the proxy changes.

Attaching Metadata

To load additional metadata corresponding to the tips of a tree, open the File menu and select “Attach metadata from CSV”. The following delimiters are supported: “,”, “;”, “\t”, and “|”. The imported metadata will appear as attribute of the tips and can, for example, be used to colour the nodes by selecting an attribute in the Style menu under “Colour nodes by”.

Saving images

IcyTree uses Scalable Vector Graphics (SVG) to draw trees in the browser. These graphics can be easily exported using File->“Export tree as”->“SVG image”. Once exported, the graphic can be loaded into vector graphics editing programs such as Inkscape or Adobe Illustrator for modification and conversion into other vector graphics formats such as PDF and EPS.

In addition, File->“Export tree as”->PNG/JPEG can be used to produce a bitmap image of the currently-displayed tree. Note that the resolution of the produced image is dependent on the current size of the browser window.

Saving tree files

In addition to exporting graphics, IcyTree can export trees as Newick, NEXUS, PhyloXML or NeXML using the remaining items in the File->“Export tree as” menu. Note that the Newick export conforms strictly to the (Extended) Newick format - additional node annotations will not be included in the generated file. All other formats support annoations. (NEXUS file export produces a file which includes BEAST-style node annotations).

Note that networks can only be exported using the Newick/NEXUS formats.

In the case that multiple trees are loaded, only the tree currently visible is exported.

Example tree files

The following list contains tree files of various formats that can be displayed using IcyTree. To display these examples you will need to download them first (for example by right-clicking on the link and selecting “Save link as”). Alternatively, choose the “open directly” link to open each link in a new IcyTree window.

• primates.newick [open directly]: Primate phylogeny in Newick format.
• SIRTrees.newick [open directly]: Collection of simulated SIR transmission trees in Newick format.
• SEISTree.nexus [open directly]: Simulated SEIS transmission tree in Nexus format (which permits annotations).
• h3n2.nexus [open directly]: Inferred Influenza tree in Nexus format including internal nodes and annotations representing ancestral spatial dynamics.
• ARG.newick [open directly]: Simulated ancestral recombination graph in Extended Newick format.
• ARG.nexus [open directly]: The same ARG as in the previous example but in Nexus format (to support additional node/edge annotations).
• PhyloXML_example [open directly]: Example PhyloXML time tree.
• NeXML_example [open directly]: Example NeXML time tree.

Exploring trees

Once a tree is loaded, it can be explored in a variety of ways.

Panning and Zooming

The principle method of exploration is via panning and zooming the view of the displayed tree. To zoom in or out, simply hover the mouse cursor over a position of interest and scroll “up” or “down” respectively on your mouse’s scroll wheel. To pan, simply click and drag.

Horizontal/Vertical Zooming

To zoom in or out in the horizontal or vertical directions only, hold down SHIFT or CTRL respectively while moving the scroll wheel.

Viewing Tree Edge Statistics

Hovering over a tree edge will cause a table to appear describing the edge. The table will vanish when your mouse leaves he edge, but not if you hover over the table itself.

Note that you cannot pan or zoom if your mouse cursor is hovering over the edge description table.

Outlining and Collapsing Clades

Hovering over a tree edge and clicking the left mouse button will cause the clade/sub-tree descending from that edge to be “outlined” - i.e., drawn as a triangle that occupies the same vertical space as the original clade but obscures the internal detail. This can be useful for large trees as a means to focus attention on the bulk structure of the tree.

Holding down the Alt key while clicking on an edge produces a similar effect, but causes the clade to be “collapsed” - i.e. replaced by a triangle that occupies the same vertical space as a single leaf node. Again, this is useful for exploring the structure of large trees.

Clicking on an outlined/collapsed clade will restore the original representation of that clade.

The clade collapse mechanism is also applicable to networks. However, the concept of clade is not so easily defined in this case. The present behaviour is to collapse only those descendants that do not descend from recombinant edges. (See the Recombinant Edges section of the manual for information on what is meant by “recombinant edge”.)

Re-rooting Trees

While for the most part IcyTree is only intended for viewing rather than editing trees, it does allow users to select a new root position for the tree. This is useful in situations where an inference procedure has produced an unrooted tree but where the presence of an outgroup allows the user to be certain of the true location of the root.

To re-root a tree, simply hover the mouse cursor over an edge, and click the left mouse button while holding down the SHIFT key. This produces a new root node exactly in the middle of the selected edge.

Be aware that re-rooting trees with node annotations that actually apply to immediately ancestral edges can produce meaningless annotations. See this article for more details.

The re-rooting can also be applied to networks. However, in the case of timed networks the lengths of the recombinant edges cannot in general be preserved and in some circumstances may produce negative edge lengths.

Changing the order of tree nodes

When node sorting is disabled (i.e. Style->“Node sorting” as discussed in the next section is set to “Unsorted”), the order of children below a given internal node can be manually rotated by hovering the mouse cursor over the edge immediately parental to this node and clicking the RIGHT mouse button.

Visualization style

IcyTree provides a number of options for adjusting the style of visualization presented. These are all accessible via the Style menu, which is available once a tree has been loaded. Each of the items in that menu are described in the subsections below.

Node sorting

The order in which child nodes appear under each parent node in the displayed tree can be modified using the Style->“Node Sorting” menu. The default behaviour is for child nodes to be sorted so that children possessing larger subtrees are always positioned below (in the vertical axis of the visualization) children with smaller subtrees. For serially-sampled time-trees, this gives rise to a tree that descends down the screen from left to right. We thus refer to this kind of sorting as descending.

Alternatively, child nodes can be sorted in so that those possessing larger subtrees are above those with smaller subtrees. This referred to in the sorting options list as ascending.

Finally, child nodes can be left unsorted. This leaves the ordering of the nodes completely up to the input format. Note that only the Newick, NEXUS and PhyloXML formats implicitly specify an ordering, while the NeXML format does not, so be aware that “unsorted” will always lead to an arbitrary ordering of child nodes for NeXML trees.

Tree layouts

IcyTree provides the following three tree layouts:

1. Standard Time Tree

   This is the layout used to draw traditional time trees and is used by default whenever all edge lengths are defined. Child nodes are evenly spaced on the vertical axis, and the vertical position of each parent is exactly mid-way between each child. The horizontal position of each node corresponds to the time that the corresponding event (e.g. coalescence, speciation, sampling) occurred.

2. Cladogram

   This layout uses the same vertical positioning of nodes as the time tree layout but positions nodes so that the distance from the left indicates the rank of each node. The rank of any internal node is simply one more than the maximum rank of any of its children, while the rank of a leaf node is always zero.

   The cladogram layout is the only layout available to trees that do not have lengths defined for every edge and is automatically selected in this case.

3. Transmission tree

   This layout yields exactly the same horizontal node positions as as the standard time tree layout, but sets the vertical position of each parent to be identical to that of the left-most child. This allows pathogen transmission trees in which distinct vertical positions correspond to distinct hosts to be drawn.

   Note that selection of this layout disables node sorting, as in this case the ordering of child nodes provided by the input file is assumed to be significant.

Text labels

IcyTree displays Newick labels or NEXUS taxon names for leaf nodes by default. This selection can be modified using the Style->“Tip text” menu, either by selecting “None” to turn off tip labels entirely or by selecting one of the other available node attributes to use in labelling the leaf nodes.

Labelling of internal nodes is off by default but can be turned on by selecting from the available attributes listed in the Style->“Internal node text” menu.

Particularly when labelled singleton nodes (i.e. internal nodes with a single child node) exist, internal node labels can be difficult to read. To improve visibility in such cases, select the Style->“Angle node label text” menu item, which causes all text labels to be drawn at a 45 degree angle.

Node and edge colouring

IcyTree allows tree nodes and edges to be coloured according to the value of any of the labels or attributes defined on the nodes. In the case of edges, attributes are understood to apply to the edge immediately ancestral to the node with which the attribute is associated in the input file.

To use edge colouring, choose the specific attribute using the Style->“Colour edges by” sub-menu. Similarly for nodes, choose the attribute using the Style->“Colour nodes by” sub-menu. In either case, when an item other than “None” is selected, objects are coloured automatically by applying a distinct colour to each set of objects having a distinct value for the chosen attribute. Edges/nodes for which the chosen attribute is undefined remain coloured black.

The specific colours used are selected by sorting the unique attribute values (numerically if all values are numeric, lexographically otherwise) and assigned unique colours with maximally-separated hues to make distinct attribute values as easy to discern as possible.

A legend showing the mapping from trait values to colours can be toggled on and off using Style->“Display legend”.

Relative edge width

IcyTree also allows the relative width of the lines used to draw tree edges to be influenced by any label or attribute that has numeric values that range between 0 and 1. Just as for edge colouring, node attributes determine the relative width of the edge immediately ancestral to each node.

The attribute used for relative edge width can be chosen via the Style->“Relative edge width” sub-menu. (Only compatible attributes are shown.)

Marking singleton nodes

IcyTree defines “singletons” as those nodes which have exactly one child. Such nodes may be used to represent a variety of events including ancestral migrations or sampled ancestors. Unless the adjacent edges are differently coloured due to a change in some attribute value, these nodes are by default invisible. IcyTree thus allows such nodes to be explicitly marked with solid black circles. This marking can be toggled using the Style->“Mark singleton nodes” option.

Collapsing zero-length edges

Some phylogenetic software packages produce time trees in which with a subset of the edges have a zero length. Such edges may be used to encode non-binary time tree elements (sampled ancestors, polytomies) within a binary tree. The option Style->“Collapse zero-length edges”, which is enabled by default, causes these “dummy” edges to be ommitted from the tree when it is drawn. (To make the resulting sampled ancestor nodes visible, use the Style->“Mark singleton nodes” option described above.)

Error bars

Some phylogenetics inference packages (including both BEAST and BEAST 2) produce phylogenetic trees that include information about node age uncertainty. In the case of BEAST and BEAST 2, this is indicated using vector-valued node attributes that contain the 95% highest posterior density interval for each node age. These intervals can be displayed by IcyTree as node age error bars by selecting the appropriate attribute from the Style->“Node height error bars” sub-menu.

Recombinant edges

IcyTree uses the term “recombinant edge” to refer to any additional edges immediately ancestral to a node. These existence of these edges mean that the displayed genealogy is a network rather than a simple tree.

The only format in which IcyTree accepts descriptions of phylogenetic networks is the Extended Newick format. In this format, there is a distinction made between the first parental edge and these additional edges. Whether or not this distinction is meaningful is up to the author of the extended Newick file.

In IcyTree, the additional “recombinant” edges are drawn using dashed lines. This is done simply as a strategy to make it easier for networks to be understood: drawing rooted networks often requires lines representing edges to cross, and using dashed lines for these “recombinant” edges makes it easier to distinguish between line joinings that represent lineage coalescences/bifurcations and those that are simply a result of a busy network.

In addition, the dashed/solid distinction can be used to encode useful information, as it is in the output of Bacter which uses the primary parental edge as the one representing the clonal ancestry of a bacterial sample and the recombinant edges to represent ancestry due to gene conversion.

The following style menu options apply specifically to “recombinant edges” and networks:

• Display recombinant edges

  This option is selected by default but can be turned off to completely hide recombinant edges. This is only useful if the distinction between the primary ancestral edge and the additional “recombinant” ancestral edges holds semantic value.

• Recombinant edge text

  This option can be used to apply additional text, if available, directly to recombinant edges. This text is taken from the Newick label (or NEXUS node annotation) on the “hybrid” leaf node in the extended Newick file. (See the paper describing the extended Newick format for details on hybrid nodes.)

• Recombinant edge width

  This option uses a numeric trait value (which must lie between 0 and 1) on each “hybrid” leaf node to determine the relative width of the dashed line representing the corresponding recombinant edge.

• Inline recombinant edges

  Enabling this option causes an alteration in the layout so that nodes representing coalescences between a recombinant edge and a non-recombinant edge are positioned directly in line with the non-recombinant descendent node of the coalescence node. This option is off by default.

• Recombinant edge length minimize

  This option toggles whether recombinant edges are positioned in such a way that they minimize the length of the dashed line used to represent the edge. This option is on by default.

Time Axis

When a tree layout other than “Cladogram” is selected (i.e. Standard Time Tree or Transmission Tree), the horizontal position of nodes corresponds to the time at which the corresponding event occurred. These times are visible in the edge statistics box that appears when the mouse cursor is moved over individual edges. IcyTree can additionally display a horizontal axis to make it easier to see at a glance when these events occurred.

To turn the axis on, select either “Age” or “Forwards Time” from the Style->Axis sub-menu. “Age” causes the numerical labels on the axis to increase from right to left (i.e. representing age before some chosen time) while “Forwards Time” causes the numbers to increase from left to right (i.e. representing time after some chosen time).

In either case, the age/time of the most recent leaf on the tree (i.e. the node furthest to the right) defaults to zero. This means that ages will by default represent ages before the most recent sample (which is often the present) but that selecting “Forward Time” will initially result in negative numbers increasing from the left and reaching zero at the most recent sample.

IcyTree allows users to select a different time/age for the most recent sample by choosing Style->“Set axis offset”. This brings up a dialog box through which users can modify this value.

Log Scale

It is often the case, particularly with gene trees that are drawn from something similar to a coalescent distribution, that the vast majority of the internal nodes of the tree are in the very recent past and only a handful of nodes are much older. In such cases, placing the tree on a linear time scale can make it difficult to simultaneously see the overall structure of the tree in a single window.

To address this problem, IcyTree can use something akin to a logarithmic scale to position nodes on time trees, with the horizontal distance between the node and the most recent sample being proportional to the logarithm of the sum of the time difference and some offset. That is,

δx ∝ log(δt + ω)

where δx is the horizontal distance between a point on the tree and the most recent sample (youngest leaf), δt is the corresponding time difference and \(\omega\) is a positive offset. The offset is included to allow the most recent sample to be included in the figure, and its magnitude determines how much the transformation affects the tree shape with smaller values of \(\omega\) resulting in a stronger magnifying effect on the recent portions of the tree.

To switch this mode on or off, select Style->“Log scale”. To adjust the offset value, hold down the Alt key while moving the mouse wheel. Moving the scroll wheel “up” reduces the offset and increases the strength of the transformation, while moving it “down” increases the offset and reduces the strength of the transformation.

The best way to get an understanding of these options is to try them out!

General Style Options

The final set of Style options apply more generally. It includes the following options:

• Edge Width

  This is a sub-menu containing options to uniformly increase or decrease the width of all lines used to represent tree and network edges.

• Font Size

  Likewise, this is a sub-menu containing options to increase or decrease the size of the font used to display all text in the visualization.

• Label precision limit

  This is a sub-menu which allows users to select the number of significant figures used when displaying numeric text labels. By default an arbitray number of significant figures is permitted.

• Angle node label text

  As described previously, toggling this option causes all node labels to be angled 45 degrees upward. This can make it easier to read internal node labels, particularly those corresponding to singleton nodes.

• Anti-alias

  By default, lines representing tree edges are drawn without anti-aliasing, as this yields a crisper image. However, when the number of leaves approaches or exceeds the number of pixels in the vertical portion of the display occupied by IcyTree, this can lead to artifacts. Enabling this option can make such images clearer.

Saving and Restoring Styles

IcyTree can save a particular set of style options for later use. Simply select Style->“Save current style”, enter a name in the displayed dialog box, and click Ok. The Style->“Apply saved style” menu should now contain an entry with the name you selected. Choosing this option will restore those saved style elements.

There are a couple of things to note about this feature.

1. Styles are saved using the WebStorage system implemented by modern browsers. Your saved styles will therefore persist between browser sessions. However, clearing this storage from the browser settings will cause your saved styles to be lost.

2. Not all style options are currently saved; the tree layout and node sorting in particular.

Searching taxa

IcyTree provides a simple mechanism for searching for leaf nodes with particular attribute values.

To perform a search, choose “Find nodes” from the “Search” menu. This will display a dialog box that allows you to enter a comma-delimited list of strings to search for. (Leaf nodes with an attribute value matching one or more of these strings are interpreted as matching the search criterion.) Then, select a specific attribute to search from the drop-down menu. Finally, choose whether the entire attribute value must match the search string and whether the search will be case-sensitive.

You can also choose how to represent the search results. The default is to highlight the edges immediately ancestral to matching nodes. You can also choose to highlight all ancestral edges or only those that form monophyletic clades.

Pressing the Search button will then perform the search and display the results. Note that results are encoded in the tree by adding an annotation to matching nodes and edges. The name of this annotation is HIGHLIGHT by default but can be changed using the corresponding text field in the search dialog.

The results of a search can be cleared by clicking the Clear button on the search dialog or by selecting “Clear search results” from the Search menu.

Simple statistical functions

IcyTree also provides a couple of very simple and very experimental statistical analysis features, including the ability to produce lineage-through-time plots and skyline plots from time trees.

1. The lineages-through-time plot (Statistics->Lineages-through-time plot) function produces a graph showing how the number of extant lineages depends on the age above the most recent leaf in the tree.

2. The Skyline plot (Statistics->Skyline plot, see Pybus et al., 2000 and Strimmer and Pybus, 2001) provides a maximum likelihood estimate of population history from a single time tree, assuming that the tree was produced by a coalescent process under a piecewise constant population function. With the minimum interval length set to 0, this is the classic skyline plot of Pybus et al. (2000), but extended to handle non-ultrametric trees. With non-zero values for the minimum interval length, the result is similar to the generalized skyline plot of Stimmer and Pybus (2001), but employs maximum likelihood rather than the method of moments to estimate the interval population sizes.

These features are highly experimental and should not yet be trusted for serious analyses.

Keyboard shortcuts

Almost all options and commands in IcyTree can be accessed directly via keyboard shortcuts. These shortcut keys (if available) are displayed to the right of each menu item.

There are two types of keyboard shortcut:

1. Those corresponding to menu items without a sub-menu.

   Pressing the shortcut key is in this case equivalent to selecting the corresponding item from the menu. For instance, the “g” key toggles the edge colour legend on or off just as selecting “Display legend” from the file menu does.

2. Those corresponding to menu items with a sub-menu.

   Pressing the shortcut key in this case causes IcyTree to cycle the selected element in the sub-menu. For instance, the “c” key causes the next attribute in the Style->“Colour edges by” menu to be used to colour tree edges.

   Additionally, holding down SHIFT while pressing the shortcut causes IcyTree to select the previous element in the sub-menu. So pressing SHIFT+c causes the previous attribute in the Style->“Colour edges by” menu to be selected.

A complete list of keyboard shortcuts can be seen by choosing Help->“Keyboard shortcuts”.