skbio.tree.TreeNode.root_by_outgroup#

TreeNode.root_by_outgroup(outgroup, above=True, reset=True, branch_attrs=[], root_name=None)[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 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.

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.

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
On this page