skbio.tree.TreeNode.unroot

TreeNode.unroot(side=None, uncache=True)

Convert a rooted tree into unrooted.

Added in version 0.6.2.

Parameters:

sideint, optional

Which basal node (i.e., children of root) will be elevated to root. Must be 0 or 1. If not provided, will elevate the first basal node that is not a tip.

uncachebool, optional

Whether to clear caches of the tree if present (default: True). See details.

Added in version 0.6.3.

See also

root

root_at

Notes

In scikit-bio, every tree has a root node. A tree is considered as “rooted” if its root node has exactly two children. In contrast, an “unrooted” tree may have three (the most common case), one, or more than three children attached to its root node. This method will not modify the tree if it is already unrooted.

This method unroots a tree by trifucating its root. Specifically, it removes one of the two basal nodes of the tree (i.e., children of the root), transfers the name of the removed node to the root, and re-attaches the removed node’s children to the root. Additionally, the removed node’s branch length, if available, will be added to the other basal node’s branch. The outcome appears as if the root is removed and the two basal nodes are directly connected.

The choice of the basal node to be elevated affects the positioning of the resulting tree, but does not affect its topology from a phylogenetic perspective, as it is considered as unrooted.

This method manipulates the tree in place. There is no return value.

Note

In the case where the basal node has just one child, the resulting tree will still appear rooted as it has two basal nodes. To avoid this scenario, call prune() to remove all one-child internal nodes.

Examples

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

>>> tree.unroot()
>>> print(tree.ascii_art())
                    /-a
          /c-------|
         |          \-b
         |
         |          /-d
-g-------|-f-------|
         |          \-e
         |
         |          /-h
          \j-------|
                    \-i