Master Tree class — A Python Environment for (phylogenetic) Tree Exploration

### Navigation

- index
- modules |
- next |
- previous |
- ETE documentation »
- ETE’s Reference Guide »

# Master Tree class

class `TreeNode`(newick=None, format=0)

  TreeNode (Tree) class is used to store a tree structure. A tree consists of a collection of TreeNode instances connected in a hierarchical way. Trees can be loaded from the New Hampshire Newick format (newick).

  - Parameters: | newick – Path to the file containing the tree or, alternatively, the text string containing the same information. format (0) – subnewick format
    FORMAT | DESCRIPTION
    --- | ---
    0 | flexible with support values
    1 | flexible with internal node names
    2 | all branches + leaf names + internal supports
    3 | all branches + all names
    4 | leaf branches + leaf names
    5 | internal and leaf branches + leaf names
    6 | internal branches + leaf names
    7 | leaf branches + all names
    8 | all names
    9 | leaf names
    100 | topology only
  Returns: | a tree node object which represents the base of the tree.

  ** Examples: **

      t1 = Tree() # creates an empty tree
      t2 = Tree('(A:1,(B:1,(C:1,D:1):0.5):0.5);')
      t3 = Tree('/home/user/myNewickFile.txt')

  `add_child`(child=None, name=None, dist=None, support=None)

    Adds a new child to this node. If child node is not suplied as an argument, a new node instance will be created.

    Parameters: | child (None) – the node instance to be added as a child. name (None) – the name that will be given to the child. dist (None) – the distance from the node to the child. support’ (None) – the support value of child partition.
    Returns: | The child node instance

  `add_face`(face, column, position='branch-right')

    Add a fixed face to the node. This type of faces will be always attached to nodes, independently of the layout function.

    Parameters: | face – a Face or inherited instance column – An integer number starting from 0 position (“branch-right”) – Posible values are: “branch-right”, “branch-top”, “branch-bottom”, “float”, “aligned”

  `add_feature`(pr_name, pr_value)

    Add or update a node’s feature.

  `add_features`(**features)

    Add or update several features.

  `add_sister`(sister=None, name=None, dist=None)

    Adds a sister to this node. If sister node is not supplied as an argument, a new TreeNode instance will be created and returned.

  `children`

    A list of children nodes

  `convert_to_ultrametric`(tree_length, strategy='balanced')

    Converts a tree to ultrametric topology (all leaves must have the same distance to root). Note that, for visual inspection of ultrametric trees, node.img_style[“size”] should be set to 0.

  `copy`()

    Returns an exact and complete copy of current node.

  `del_feature`(pr_name)

    Permanently deletes a node’s feature.

  `delete`(prevent_nondicotomic=True)

    Deletes node from the tree structure. Notice that this method makes ‘disapear’ the node from the tree structure. This means that children from the deleted node are transferred to the next available parent.

    Example:

              / C
        root-|
             |        / B
              \--- H |
                      \ A

        > root.delete(H) will produce this structure:

              / C
             |
        root-|--B
             |
              \ A

  `describe`()

    Prints general information about this node and its connections.

  `detach`()

    Detachs this node (and all its descendants) from its parent and returns the referent to itself.

    Detached node conserves all its structure of descendants, and can be attached to another node through the ‘add_child’ function. This mechanism can be seen as a cut and paste.

  `dist`

    Branch length distance to parent node. Default = 0.0

  `get_ascii`(show_internal=True, compact=False)

    Returns a string containing an ascii drawing of the tree.

    Parameters: | show_internal – includes internal edge names. compact – use exactly one line per tip.

  `get_children`()

    Returns an independent list of node’s children.

  `get_closest_leaf`(topology_only=False)

    Returns node’s closest descendant leaf and the distance to it.

    Parameters: | topology_only (False) – If set to True, distance between nodes will be referred to the number of nodes between them. In other words, topological distance will be used instead of branch length distances.
    Returns: | A tuple containing the closest leaf referred to the current node and the distance to it.

  `get_common_ancestor`(*target_nodes, **kargs)

    Returns the first common ancestor between this node and a given list of ‘target_nodes’.

    Examples:

        t = tree.Tree("(((A:0.1, B:0.01):0.001, C:0.0001):1.0[&&NHX:name=common], (D:0.00001):0.000001):2.0[&&NHX:name=root];")
        A = t.get_descendants_by_name("A")[0]
        C = t.get_descendants_by_name("C")[0]
        common =  A.get_common_ancestor(C)
        print common.name

  `get_common_ancestor_OLD`(*target_nodes)

    Returns the first common ancestor between this node and a given list of ‘target_nodes’.

    Examples:

        t = tree.Tree("(((A:0.1, B:0.01):0.001, C:0.0001):1.0[&&NHX:name=common], (D:0.00001):0.000001):2.0[&&NHX:name=root];")
        A = t.get_descendants_by_name("A")[0]
        C = t.get_descendants_by_name("C")[0]
        common =  A.get_common_ancestor(C)
        print common.name

  `get_descendants`(strategy='levelorder', is_leaf_fn=None)

    Returns a list of all (leaves and internal) descendant nodes.

    Parameters: | is_leaf_fn (None) – See `TreeNode.traverse()` for documentation.

  `get_distance`(target, target2=None, topology_only=False)

    Returns the distance between two nodes. If only one target is specified, it returns the distance bewtween the target and the current node.

    Parameters: | target – a node within the same tree structure. target2 – a node within the same tree structure. If not specified, current node is used as target2. topology_only (False) – If set to True, distance will refer to the number of nodes between target and target2.
    Returns: | branch length distance between target and target2. If topology_only flag is True, returns the number of nodes between target and target2.

  `get_farthest_leaf`(topology_only=False)

    Returns node’s farthest descendant node (which is always a leaf), and the distance to it.

    Parameters: | topology_only (False) – If set to True, distance between nodes will be referred to the number of nodes between them. In other words, topological distance will be used instead of branch length distances.
    Returns: | A tuple containing the farthest leaf referred to the current node and the distance to it.

  `get_farthest_node`(topology_only=False)

    Returns the node’s farthest descendant or ancestor node, and the distance to it.

    Parameters: | topology_only (False) – If set to True, distance between nodes will be referred to the number of nodes between them. In other words, topological distance will be used instead of branch length distances.
    Returns: | A tuple containing the farthest node referred to the current node and the distance to it.

  `get_leaf_names`(is_leaf_fn=None)

    Returns the list of terminal node names under the current node.

    Parameters: | is_leaf_fn (None) – See `TreeNode.traverse()` for documentation.

  `get_leaves`(is_leaf_fn=None)

    Returns the list of terminal nodes (leaves) under this node.

    Parameters: | is_leaf_fn (None) – See `TreeNode.traverse()` for documentation.

  `get_leaves_by_name`(name)

    Returns a list of leaf nodes matching a given name.

  `get_midpoint_outgroup`()

    Returns the node that divides the current tree into two distance-balanced partitions.

  `get_partitions`()

    It returns the set of all possible partitions under a node. Note that current implementation is quite inefficient when used in very large trees.

    t = Tree(“((a, b), e);”) partitions = t.get_partitions()

    # Will return: # a,b,e # a,e # b,e # a,b # e # b # a

  `get_sisters`()

    Returns an indepent list of sister nodes.

  `get_tree_root`()

    Returns the absolute root node of current tree structure.

  `is_leaf`()

    Return True if current node is a leaf.

  `is_root`()

    Returns True if current node has no parent

  `iter_descendants`(strategy='levelorder', is_leaf_fn=None)

    Returns an iterator over all descendant nodes.

    Parameters: | is_leaf_fn (None) – See `TreeNode.traverse()` for documentation.

  `iter_leaf_names`(is_leaf_fn=None)

    Returns an iterator over the leaf names under this node.

    Parameters: | is_leaf_fn (None) – See `TreeNode.traverse()` for documentation.

  `iter_leaves`(is_leaf_fn=None)

    Returns an iterator over the leaves under this node.

    Parameters: | is_leaf_fn (None) – See `TreeNode.traverse()` for documentation.

  `iter_search_nodes`(**conditions)

    Search nodes in an interative way. Matches are being yield as they are being found. This avoids to scan the full tree topology before returning the first matches. Useful when dealing with huge trees.

  `ladderize`(direction=0)

    Sort the branches of a given tree (swapping children nodes) according to the size of each partition.

        t =  Tree("(f,((d, ((a,b),c)),e));")

        print t

        #
        #      /-f
        #     |
        #     |          /-d
        # ----|         |
        #     |     /---|          /-a
        #     |    |    |     /---|
        #     |    |     \---|     \-b
        #      \---|         |
        #          |          \-c
        #          |
        #           \-e

        t.ladderize()
        print t

        #      /-f
        # ----|
        #     |     /-e
        #      \---|
        #          |     /-d
        #           \---|
        #               |     /-c
        #                \---|
        #                    |     /-a
        #                     \---|
        #                          \-b

  `populate`(size, names_library=None, reuse_names=False, random_branches=False, branch_range=(0, 1), support_range=(0, 1))

    Generates a random topology by populating current node.

    Parameters: | names_library (None) – If provided, names library (list, set, dict, etc.) will be used to name nodes. reuse_names (False) – If True, node names will not be necessarily unique, which makes the process a bit more efficient. random_branches (False) – If True, branch distances and support values will be randomized. branch_range ((0,1)) – If random_branches is True, this

    range of values will be used to generate random distances.

    Parameters: | support_range ((0,1)) – If random_branches is True,

    this range of values will be used to generate random branch support values.

  `prune`(nodes)

    Prunes the topology of a node in order to conserve only a selected list of leaf or internal nodes. The minimum number of internal nodes (the deepest as possible) are kept to conserve the topological relationship among the provided list of nodes.

    Variables: | nodes – a list of node names or node objects that must be kept

    Examples:

        t = Tree("(((A:0.1, B:0.01):0.001, C:0.0001):1.0[&&NHX:name=I], (D:0.00001):0.000001[&&NHX:name=J]):2.0[&&NHX:name=root];")
        node_C = t.search_nodes(name="C")[0]
        t.prune(["A","D", node_C])
        print t

  `remove_child`(child)

    Removes a child from this node (parent and child nodes still exit but are no longer connected).

  `remove_sister`(sister=None)

    Removes a node’s sister node. It has the same effect as `TreeNode.up.remove_child(sister)`

    If a sister node is not supplied, the first sister will be deleted and returned.

    Parameters: | sister – A node instance
    Returns: | The node removed

  `render`(file_name, layout=None, w=None, h=None, tree_style=None, units='px', dpi=300)

    Renders the node structure as an image.

    Variables: | file_name – path to the output image file. valid extensions are .SVG, .PDF, .PNG layout – a layout function or a valid layout function name tree_style – a TreeStyle instance containing the image properties units (px) – “px”: pixels, “mm”: millimeters, “in”: inches h (None) – height of the image in `units` w (None) – weight of the image in `units` dpi (300) – dots per inches.

  `search_nodes`(**conditions)

    Returns the list of nodes matching a given set of conditions.

    Example:

        tree.search_nodes(dist=0.0, name="human")

  `set_outgroup`(outgroup)

    Sets a descendant node as the outgroup of a tree. This function can be used to root a tree or even an internal node.

    Parameters: | outgroup – a node instance within the same tree structure that will be used as a basal node.

  `set_style`(node_style)

    Set ‘node_style’ as the fixed style for the current node.

  `show`(layout=None, tree_style=None)

    Starts an interative session to visualize current node structure using provided layout and TreeStyle.

  `sort_descendants`()

    This function sort the branches of a given tree by considerening node names. After the tree is sorted, nodes are labeled using ascendent numbers. This can be used to ensure that nodes in a tree with the same node names are always labeled in the same way. Note that if duplicated names are present, extra criteria should be added to sort nodes. unique id is stored in _nid

  `support`

    Branch support for current node

  `swap_children`()

    Swaps current children order.

  `traverse`(strategy='levelorder', is_leaf_fn=None)

    Returns an iterator to traverse the tree structure under this node.

    Parameters: | strategy (“levelorder”) – set the way in which tree will be traversed. Possible values are: “preorder” (first parent and then children) ‘postorder’ (first children and the parent) and “levelorder” (nodes are visited in order from root to leaves) is_leaf_fn (None) – If supplied, `is_leaf_fn` function will be used to interrogate nodes about if they are terminal or internal. `is_leaf_fn` function should receive a node instance as first argument and return True or False. Use this argument to traverse a tree dynamically collapsing internal nodes.

  `unroot`()

    Unroots current node. This function is expected to be used on the absolute tree root node, but it can be also be applied to any other internal node. It will convert a split into a multifurcation.

  `up`

    Pointer to parent node

  `write`(features=None, outfile=None, format=0)

    Returns the newick representation of current node. Several arguments control the way in which extra data is shown for every node:

    Parameters: | features – a list of feature names to be exported using the Extended Newick Format (i.e. features=[“name”, “dist”]). Use an empty list to export all available features in each node (features=[]) outfile – writes the output to a given file format – defines the newick standard used to encode the tree. See tutorial for details.

    Example:

        t.get_newick(features=["species","name"], format=1)

`Tree`

  alias of `TreeNode`

### Navigation

- index
- modules |
- next |
- previous |
- ETE documentation »
- ETE’s Reference Guide »