Skip to main content
`Ctrl`+`K`

# skbio.tree.TreeNode.shear

TreeNode.shear(names, strict=True, prune=True, inplace=False, uncache=True)

  Refine a tree such that it just has the desired tip names.

  Parameters:
    names iterable of str

      The tip names on the tree to keep.

    strict bool, optional

      In case some names are not found in the tree, whether to raise an error (True, default) or to refine the tree to the found names only (False).

      Added in version 0.6.3.

    prune bool, optional

      Whether to collapse single-child nodes after shearing by calling `prune` (default: True).

      Added in version 0.6.3.

    inplace bool, optional

      Whether to modify the tree in place (True) or to create a modified copy of the tree (False, default).

      Added in version 0.6.3.

    uncache bool, optional

      Whether to clear caches of the tree if present (default: True). See `details`. Only applicable when `inplace` is True.

      Added in version 0.6.3.

  Returns:
    TreeNode, optional

      The resulting tree (if `inplace` is False).

  Raises:
    ValueError

      If one or more names do not exist in the tree and `strict` is True.

  See also

  `prune`
  `remove`
  `remove_by_func`

  Notes

  This method is useful for reducing a large tree to a relevant subset of taxa.

  If called from an internal node of the tree, only the clade below the node will be refined, and the copy of the tree (when `inplace` is False) will only include the clade.

  Examples

      >>> from skbio import TreeNode
      >>> tree = TreeNode.read(["(((a,b)c,(d,e)f)g,(h,i)j)root;"])
      >>> print(tree.ascii_art())
                                    /-a
                          /c-------|
                         |          \-b
                /g-------|
               |         |          /-d
               |          \f-------|
      -root----|                    \-e
               |
               |          /-h
                \j-------|
                          \-i

      >>> sheared = tree.shear(['a', 'd', 'h'])
      >>> print(sheared.ascii_art())
                          /-a
                /g-------|
      -root----|          \-d
               |
                \-h