skbio.tree.TreeNode.root_at#

TreeNode.root_at(node=None, above=False, reset=False, branch_attrs=['name'], root_name='root')[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 remove the original root of a rooted tree before performing the rerooting operation. Default is False.

Added in version 0.6.2.

Note

The default value will be set as True in 0.7.0.

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.

Note

name will be removed from the default in 0.7.0, as it is usually considered as an attribute of the node instead of the branch.

root_namestr or None, optional

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

Added in version 0.6.2.

Note

The default value will be set as None in 0.7.0.

Returns:
TreeNode

A new copy of the tree rooted at the give node.

Warning

The default behavior of root_at is subject to change in 0.7.0. The new default behavior can be achieved by specifying reset=True, branch_attrs=[], root_name=None.

See also

root_at_midpoint
unrooted_copy
unroot

Notes

The specified node will be come the root of 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", branch_attrs=[])
>>> print(t1)
(a,b,((d,e)f,(h)i)g)c;

>>> print(t1.ascii_art())
          /-a
         |
         |--b
-c-------|
         |                    /-d
         |          /f-------|
          \g-------|          \-e
                   |
                    \i------- /-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, branch_attrs=[])
>>> print(t2)
((a,b)c,((d,e)f,(h)i)g)root;

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