Frequently Asked Questions (FAQs)¶
Contents
General¶
How do I use ETE?¶
From 2.1 version, ETE includes a basic standalone program that can be
used to quickly visualize your trees. Type ete3
in a terminal to
access the program. For instance:
# ete3 "((A,B),C);"
or
# ete3 mytreefile.nw
However, ETE is not a standalone program. The ete3
script is a
very simple implementation and does not allow for fancy
customization. The main goal of ETE is to provide a Python programming
library, so you can create your own scripts to manipulate and
visualize phylogenetic trees. Many examples are available here and
along with the ETE tutorial.
Tree Browsing¶
How do I find a leaf by its name?¶
You can use the TreeNode.search_nodes()
function:
matching_nodes = tree.search_nodes(name="Tip1")
Or use the following shortcut (not that it assumes no duplicated names)
node = tree&"Tip1"
How do I visit all nodes within a tree?¶
There are many ways, but this is the easiest one:
for node in t.traverse():
print node.name
Can I control the order in which nodes are visited?¶
Yes, currently 3 strategies are implemented: pre-order, post-order and level-over. You can check the differences at http://packages.python.org/ete3/tutorial/tutorial_trees.html#traversing-browsing-trees
What’s the difference between Tree.get_leaves()
and Tree.iter_leaves()
?¶
All methods starting with get_
(i.e. get_leaves,
get_descendants, etc.) return an independent list of items. This means
that tree traversing is fully performed before returning the result.
In contrast, iter_ methods return one item at a time, saving memory
and, increasing the performance of some operations.
Note also that tree topology cannot be modified while iterating methods are being executed. This limitation does not apply for get_ methods.
In addition, get_ methods can be used to cache tree browsing paths (the order in which nodes must be visited), so the same tree traversing operations don’t need to be repeated:
nodes_in_preorder = tree.get_descendants("preorder")
for n in nodes_in_preorder:
pass # Do something
#
# (...)
#
for n in nodes_in_preorder:
pass # Do something else
Reading and writing tree¶
How do I load a tree with internal node names?¶
Newick format can be slightly different across programs. ETE allows to read and write several newick subformats, including support for internal node labeling:
FORMAT | DESCRIPTION | SAMPLE |
---|---|---|
0 | flexible with support values | ((D:0.723274,F:0.567784)1.000000:0.067192,(B:0.279326,H:0.756049)1.000000:0.807788); |
1 | flexible with internal node names | ((D:0.723274,F:0.567784)E:0.067192,(B:0.279326,H:0.756049)B:0.807788); |
2 | all branches + leaf names + internal supports | ((D:0.723274,F:0.567784)1.000000:0.067192,(B:0.279326,H:0.756049)1.000000:0.807788); |
3 | all branches + all names | ((D:0.723274,F:0.567784)E:0.067192,(B:0.279326,H:0.756049)B:0.807788); |
4 | leaf branches + leaf names | ((D:0.723274,F:0.567784),(B:0.279326,H:0.756049)); |
5 | internal and leaf branches + leaf names | ((D:0.723274,F:0.567784):0.067192,(B:0.279326,H:0.756049):0.807788); |
6 | internal branches + leaf names | ((D,F):0.067192,(B,H):0.807788); |
7 | leaf branches + all names | ((D:0.723274,F:0.567784)E,(B:0.279326,H:0.756049)B); |
8 | all names | ((D,F)E,(B,H)B); |
9 | leaf names | ((D,F),(B,H)); |
100 | topology only | ((,),(,)); |
In order to load (or write) a tree with internal node names, you can specify format 1:
from ete3 import Tree
t = Tree("myTree.nw", format=1)
t.write(format=1)
How do I export tree node annotations using the Newick format?¶
You will need to use the extended newick format. To do so, you only need to specify the name of the node attributes that must be exported when calling tree.write() function. For instance:
tree.write(features=["name", "dist"])
If you want all node features to be exported in the newick string, use “features=[]”:
tree.write(features=[])
Tree visualization¶
Can ETE draw circular trees?¶
Yes, starting from version 2.1, ete can render trees in circular
mode. Install the latest version from
http://pypi.python.org/pypi/ete3 or by executing easy_install -U
ete3
.
What are all these dotted lines that appear in my circular trees?¶
Opposite to other popular visualization software, ETE’s drawing engine
will try by all means to avoid overlaps among lines and all other
graphical elements. When faces are added to nodes (specially to
internal nodes), the required space to allocate such elements requires
to expand the branches of the tree. Instead of breaking the relative
length of all branches, it will add dotted lines until reaching the
its minimal position. This effect could only be avoided by increasing
the branch scale. Alternatively, you can modify the aspect of the
dotted lines using TreeStyle
options, such as
extra_branch_line_type
.
As by Jun 2012, ETE 2.1 includes a patch that allows to automatically
detect the optimal scale value that would avoid dotted lines. Two
levels of optimization are available, see optimal_scale_level
option in TreeStyle
class. This feature is now
user-transparent and enabled by default, so, if no scale is provided,
the optimal one will be used.
Why some circular trees are too large?¶
In order to avoid overlaps among elements of the tree (i.e. node faces), ETE will expand branch lengths until the desired layout is fully satisfied.
How do I export tree images as SVG¶
Image format is automatically detected from the filename extension. The following code will automatically render the tree as a vector image.
tree.render("mytree.svg")
How do I visualize internal node names?¶
You will need to change the default tree layout. By creating your custom layout functions, you will be able to add, remove or modify almost any element of the tree image.
A basic example would read as follow:
from ete3 import Tree, faces, AttrFace, TreeStyle
def my_layout(node):
if node.is_leaf():
# If terminal node, draws its name
name_face = AttrFace("name")
else:
# If internal node, draws label with smaller font size
name_face = AttrFace("name", fsize=10)
# Adds the name face to the image at the preferred position
faces.add_face_to_node(name_face, node, column=0, position="branch-right")
ts = TreeStyle()
# Do not add leaf names automatically
ts.show_leaf_name = False
# Use my custom layout
ts.layout_fn = my_layout
t = Tree("((B,(E,(A,G)M1_t1)M_1_t2)M2_t3,(C,D)M2_t1)M2_t2;", format=8)
# Tell ETE to use your custom Tree Style
t.show(tree_style=ts)
Can the visualization of trees with very unbalanced tree branches be improved?¶
Yes, the experience of visualizing trees with extreme differences in branch lengths can be improved in several ways.
1) Convert your tree to ultrametric topology. This will modify all branches in your tree to make all nodes to end at the same length.
from ete3 import Tree, TreeStyle
t = Tree()
t.populate(50, random_branches=True)
t.convert_to_ultrametric()
t.show()
2) You can enable the force_topology
option in
TreeStyle
, so all branches will be seen as the same length by
the tree drawing engine (Note that in this case, actual tree branches
are not modified)
from ete3 import Tree, TreeStyle
t = Tree()
t.populate(50, random_branches=True)
ts = TreeStyle()
ts.force_topology = True
t.show(tree_style=ts)