Frequently Asked Questions (FAQs) — A Python Environment for (phylogenetic) Tree Exploration

### Navigation

- index
- modules |
- next |
- previous |
- ETE documentation »

# Frequently Asked Questions (FAQs)

Contents

- Frequently Asked Questions (FAQs)
  - General
    - How do I use ETE?
  - Tree Browsing
    - How do I find a leaf by its name?
    - How do I visit all nodes within a tree?
    - Can I control the order in which nodes are visited?
    - What’s the difference between `Tree.get_leaves()` and `Tree.iter_leaves()`?
  - Reading and writing tree
    - How do I load a tree with internal node names?
    - How do I export tree node annotations using the Newick format?
  - Tree visualization
    - Can ETE draw circular trees?
    - What are all these dotted lines that appear in my circular trees?
    - Why some circular trees are too large?
    - How do I export tree images as SVG
    - How do I visualize internal node names?
    - Can the visualization of trees with very unbalanced tree branches be improved?

## 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 `ete2` in a terminal to access the program. For instance:

> `# ete2 "((A,B),C);"`

or

> `# ete2 mytreefile.nw`

However, ETE is not a standalone program. The `ete2` 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/ete2/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 ete2 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/ete2 or by executing `easy_install -U ete2`.

### 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 ete2 import Tree, faces, AttrFace, TreeStyle

    def my_layout(node):
        if node.is_leaf():
             # If terminal node, draws its name
             name_faces = AttrFace("name")
        else:
             # If internal node, draws label with smaller font size
             name_faces = 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 ete2 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 ete2 import Tree, TreeStyle

    t = Tree()
    t.populate(50, random_branches=True)
    ts = TreeStyle()
    ts.force_topology = True
    t.show(tree_style=ts)

### Navigation

- index
- modules |
- next |
- previous |
- ETE documentation »