Skip to main content
`Ctrl`+`K`

# skbio.tree.TreeNode.root_at

TreeNode.root_at(node=None, above=False, reset=False, branch_attrs=['name'], root_name='root', inplace=False)

  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:
    node TreeNode 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.

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

    reset bool, 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_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.

      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_name str 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.

    inplace bool, 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