skbio.tree.TreeNode.insert#

TreeNode.insert(node, distance=None, branch_attrs=[], uncache=True)[source]#

Insert a node into the branch connecting self and its parent.

Added in version 0.6.2.

Parameters:

nodeTreeNode: Node to insert.
distancefloat, int or None, optional: Distance between self and the insertion point. Must not exceed length of self. If None whereas length is not None, will insert at the midpoint of the branch.
branch_attrsiterable of str, optional: Attributes of self that should be transferred to the inserted node as they are considered as attributes of the branch. support will be automatically included as it is always a branch attribute.
uncachebool, optional: Whether to clear caches of the tree if present (default: True). See details.

Added in version 0.6.3.

Raises:

NoParentError: If self has no parent.
ValueError: If distance is specified but branch has no length.
ValueError: If distance exceeds branch length.

See also

append

Notes

This method will remove the existing parent of the node if any, set its parent as self’s parent, and set self’s parent as the incoming node. The node’s index position in the parent’s children is consistent with that of self prior to insertion.

The uncache parameter applies to both donor and recipient trees.

Examples

>>> from skbio import TreeNode
>>> tree = TreeNode.read(["((a:1,b:2)c:4,d:5)e;"])
>>> print(tree.ascii_art())
                    /-a
          /c-------|
-e-------|          \-b
         |
          \-d

>>> tree.find("c").insert(TreeNode("x"))
>>> print(tree.ascii_art())
                              /-a
          /x------- /c-------|
-e-------|                    \-b
         |
          \-d
>>> tree.find("c").length
2.0
>>> tree.find("x").length
2.0