Skip to main content
`Ctrl`+`K`

# skbio.tree.TreeNode.root_by_outgroup

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

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

  Added in version 0.6.2.

  Parameters:
    outgroup iterable 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.

    above bool, 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.

    reset bool, optional

      Whether remove the original root of a rooted tree before performing the rerooting operation. Default is `True`.

    branch_attrs iterable 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_name str 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