skbio.tree.TreeNode.root_by_outgroup#

TreeNode.root_by_outgroup(outgroup, above=True, reset=True, branch_attrs=[], root_name=None, inplace=False)[source]#

Reroot the tree with a given set of taxa as outgroup.

Added in version 0.6.2.

Parameters:

outgroupiterable of str: Taxon set to serve as outgroup. Must be a proper subset of taxa in the tree. The tree will be rooted at the lowest common ancestor (LCA) of the outgroup.
abovebool, float, or int, optional: Whether and where to insert a new root node. If False, the LCA will serve as the root node. If True (default), a new root node will be created and inserted at the midpoint of the branch connecting the LCA and its parent (i.e., the midpoint between outgroup and ingroup). If a number between 0 and branch length, the new root will be inserted at this distance from the LCA.
resetbool, optional: Whether to remove the original root of a rooted tree before performing the rerooting operation. Default is True.
branch_attrsiterable of str, optional: Attributes of each node that should be considered as attributes of the branch connecting the node to its parent. This is important for the correct rerooting operation. “length” and “support” will be automatically included as they are always branch attributes.
root_namestr or None, optional: Name for the root node, if it doesn’t already have one.
inplacebool, optional: Whether to reroot the tree in place (True) or to create a rerooted copy of the tree (False, default).

Added in version 0.6.3.

Returns:

TreeNode: A tree rooted by the outgroup.

Raises:

TreeError: Outgroup is not a proper subset of taxa in the tree.
TreeError: Outgroup is not monophyletic in the tree.

Notes

An outgroup is a subset of taxa that are usually distantly related from the remaining taxa (ingroup). The outgroup helps with locating the root of the ingroup, which are of interest in the study.

This method reroots the tree at the lowest common ancestor (LCA) of the outgroup. By default, a new root will be placed at the midpoint between the LCA of outgroup and that of ingroup. But this behavior can be customized.

This method requires the outgroup to be monophyletic, i.e., it forms a single clade in the tree. If the outgroup spans across the root of the tree, the method will reroot the tree within the ingroup such that the outgroup can form a clade in the rerooted tree, prior to rooting by outgroup.

Tree caches (see details) will not be retained in the returned tree. In in-place mode, they will be cleared prior to rerooting. In copying mode, they will not be copied to the new tree.

Examples

>>> from skbio import TreeNode
>>> tree = TreeNode.read(['((((a,b),(c,d)),(e,f)),g);'])
>>> print(tree.ascii_art())
                                        /-a
                              /--------|
                             |          \-b
                    /--------|
                   |         |          /-c
                   |          \--------|
          /--------|                    \-d
         |         |
         |         |          /-e
---------|          \--------|
         |                    \-f
         |
          \-g

>>> rooted = tree.root_by_outgroup(['a', 'b'])
>>> print(rooted.ascii_art())
                    /-a
          /--------|
         |          \-b
         |
---------|                    /-c
         |          /--------|
         |         |          \-d
          \--------|
                   |                    /-e
                   |          /--------|
                    \--------|          \-f
                             |
                              \-g

>>> rooted = tree.root_by_outgroup(['e', 'f', 'g'])
>>> print(rooted.ascii_art())
                              /-e
                    /--------|
          /--------|          \-f
         |         |
         |          \-g
---------|
         |                    /-c
         |          /--------|
         |         |          \-d
          \--------|
                   |          /-b
                    \--------|
                              \-a