skbio.tree.TreeNode.subset

TreeNode.subset(include_self=False)

Return a subset of taxa descending from self.

A subset can be considered as taxa (tip names) within a clade defined by the current node (branch), selected from all taxa within the tree.

Parameters:

include_selfbool, optional

Whether to include the current node if it is a tip (default: False).

Added in version 0.6.3.

Returns:

frozenset of str

The set of names at the tips of the clade that descends from self.

See also

tips

subsets

bipart

Notes

This is a convenient method to return all taxa (tip names) rather than the tip nodes themselves. Internal node names will not be included.

The returned value (a frozenset) is unordered and hashable, therefore can be used to define clades, lineages and taxon groups for efficient lookup. For example, one can check whether a taxon exists in the current tree or clade.

By default, if this method is applied to a tip, an empty set will be returned, because a tip does not have descendants. If include_self is True, a single- element set containing the name of the tip will be returned. This behavior can be considered as returning taxa descending from the branch connecting self and its parent.

Applying this method to the root node of a tree will return all taxa in the tree.

Examples

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

>>> sorted(tree.subset())
['a', 'b', 'c', 'f', 'g']

>>> subset = tree.find('e').subset()
>>> sorted(subset)
['a', 'b', 'c']

>>> 'a' in subset
True

>>> 'f' in subset
False