Skip to main content
`Ctrl`+`K`

# skbio.tree.TreeNode.insert

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

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

  Added in version 0.6.2.

  Parameters:
    node TreeNode

      Node to insert.

    distance float, 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_attrs iterable 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.

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