skbio.tree.TreeNode.root_at#

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

Reroot the tree at the provided node.

This is useful for positioning a tree with an orientation that reflects knowledge of the true root location.

Parameters:
nodeTreeNode or str, optional

The node to root at. Can either be a node object or the name of the node. If not provided, will root at self. If a root node provided, will return the original tree.

Changed in version 0.6.2: Becomes optional.

abovebool, float, or int, optional

Whether and where to insert a new root node. If False (default), the target node will serve as the root node. If True, a new root node will be created and inserted at the midpoint of the branch connecting the target node and its parent. If a number, the new root will be inserted at this distance from the target node. The number ranges between 0 and branch length.

Added in version 0.6.2.

resetbool, optional

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

Added in version 0.6.2.

Changed in version 0.7.0: Set the default value to 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.

Added in version 0.6.2.

Changed in version 0.7.0: Removed name from the default values.

root_namestr or None, optional

Name for the root node, if it doesn’t already have one.

Added in version 0.6.2.

Changed in version 0.7.0: Set the default value to None.

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 at the give node.

See also

unrooted_copy
unrooted_move
unroot

Notes

The specified node will be come the root of the new tree.

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,h)i;"])
>>> print(tree.ascii_art())
                              /-a
                    /c-------|
                   |          \-b
          /g-------|
         |         |          /-d
-i-------|          \f-------|
         |                    \-e
         |
          \-h

Use the given node as the root node. This will typically create an unrooted tree (i.e., root node has three children).

>>> t1 = tree.root_at("c")
>>> print(t1)
(a,b,((d,e)f,h)g)c;

>>> print(t1.ascii_art())
          /-a
         |
         |--b
-c-------|
         |                    /-d
         |          /f-------|
          \g-------|          \-e
                   |
                    \-h

Insert a new root node into the branch above the given node. This will create a rooted tree (i.e., root node has two children).

>>> t2 = tree.root_at("c", above=True)
>>> print(t2)
((a,b)c,((d,e)f,h)g);

>>> print(t2.ascii_art())
                    /-a
          /c-------|
         |          \-b
---------|
         |                    /-d
         |          /f-------|
          \g-------|          \-e
                   |
                    \-h
On this page