skbio.tree.TreeNode.root_at#

TreeNode.root_at(node=None, above=False, reset=False, branch_attrs=['name'], root_name='root', 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 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.

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.

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

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", 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