skbio.tree.TreeNode.shear#

TreeNode.shear(names, strict=True, prune=True, inplace=False, uncache=True)[source]#

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

Parameters:
namesiterable of str

The tip names on the tree to keep.

strictbool, 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.

prunebool, optional

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

Added in version 0.6.3.

inplacebool, 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.

uncachebool, 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
On this page