The Programmable Tree Drawing Engine — ETE Toolkit - analysis and visualization of trees

ETE’s treeview extension provides a highly programmable drawing system to render any hierarchical tree structure as PDF, SVG or PNG images. Although several predefined visualization layouts are included with the default installation, custom styles can be easily created from scratch.
Image customization is performed through four elements: a) TreeStyle, setting general options about the image (shape, rotation, etc.), b) NodeStyle, which defines the specific aspect of each node (size, color, background, line type, etc.), c) node faces.Face which are small pieces of extra graphical information that can be added to nodes (text labels, images, graphs, etc.) d) a layout function, a normal python function that controls how node styles and faces are dynamically added to nodes.
Images can be rendered as PNG, PDF or SVG files using the TreeNode.render() method or interactively visualized using a built-in Graphical User Interface (GUI) invoked by the TreeNode.show() method.
ETE’s tree drawing engine is fully integrated with a built-in graphical user interface (GUI). Thus, ETE allows to visualize trees using an interactive interface that allows to explore and manipulate node’s properties and tree topology. To start the visualization of a node (tree or subtree), you can simply call the TreeNode.show() method.
One of the advantages of this on-line GUI visualization is that you can use it to interrupt a given program/analysis, explore the tree, manipulate them, and continuing with the execution thread. Note that changes made using the GUI will be kept after quiting the GUI. This feature is specially useful for using during python sessions, in which analyses are performed interactively.
The GUI allows many operations to be performed graphically, however it does not implement all the possibilities of the programming toolkit.
Tree images can be directly written as image files. SVG, PDF and PNG formats are supported. Note that, while PNG images are raster images, PDF and SVG pictures are rendered as vector graphics, thus allowing its later modification and scaling.
To generate an image, the TreeNode.render() method should be used instead of TreeNode.show(). The only required argument is the file name, whose extension will determine the image format (.PDF, .SVG or .PNG). Several parameters regarding the image size and resolution can be adjusted:
If h and w values are both provided, image size will be adjusted even if it requires to break the original aspect ratio of the image. If only one value (h or w) is provided, the other will be estimated to maintain aspect ratio. If no sizing values are provided, image will be adjusted to A4 dimensions.
Image customization is performed through four main elements:
The TreeStyle class can be used to create a custom set of options that control the general aspect of the tree image. Tree styles can be passed to the TreeNode.show() and TreeNode.render() methods. For instance, TreeStyle allows to modify the scale used to render tree branches or choose between circular or rectangular tree drawing modes.
A number of parameters can be controlled through custom tree style objects, check TreeStyle documentation for a complete list of accepted values.
Some common uses include:
Automatically adds node names and branch information to the tree image:
Increases the length of the tree by changing the scale:
Increases the separation between leaf branches:
Draws a rectangular tree from top to bottom:
Draws a circular tree using a semi-circumference:
Through the NodeStyle class the aspect of each single node can be controlled, including its size, color, background and branch type.
A node style can be defined statically and attached to several nodes:
Simple tree in which the same style is applied to all nodes:
If you want to draw nodes with different styles, an independent NodeStyle instance must be created for each node. Note that node styles can be modified at any moment by accessing the TreeNode.img_style attribute.
Simple tree in which the different styles are applied to each node:
Static node styles, set through the set_style() method, will be attached to the nodes and exported as part of their information. For instance, TreeNode.copy() will replicate all node styles in the replicate tree. Note that node styles can be also modified on the fly through a layout function (see layout functions)
Node faces are small pieces of graphical information that can be linked to nodes. For instance, text labels or external images could be linked to nodes and they will be plotted within the tree image.
Several types of node faces are provided by the main ete3 module, ranging from simple text (TextFace) and geometric shapes (CircleFace), to molecular sequence representations (SequenceFace), heatmaps and profile plots (ProfileFace). A complete list of available faces can be found at the ete3.treeview reference page..
Faces can be added to different areas around the node, namely branch-right, branch-top, branch-bottom or aligned. Each area represents a table in which faces can be added through the TreeNode.add_face() method. For instance, if two text labels want to be drawn bellow the branch line of a given node, a pair of TextFace faces can be created and added to the columns 0 and 1 of the branch-bottom area:
If you add more than one face to the same area and column, they will be piled up. See the following image as an example of face positions:
Source code used to generate the above image.
Once a face object is created, it can be linked to one or more nodes. For instance, the same text label can be recycled and added to several nodes.
Apart from the specific config values of each face type, all face instances contain same basic attributes that permit to modify general aspects such as margins, background colors, border, etc. A complete list of face attributes can be found in the general Face class documentation. Here is a very simple example:
Basic use of face general attributes
Layout functions act as