skbio.tree.TreeNode.descending_branch_length#

TreeNode.descending_branch_length(nodes=None, include_stem=False, include_self=False, **kwargs)[source]#

Calculate the total length of branches descending from self.

Changed in version 0.6.3: Renamed from descending_branch_length. The old name is kept as an alias.

Parameters:

nodesiterable of TreeNode or str, optional: Instances or names of a subset of descending nodes to refine the result. If provided, the total length of branches connecting these nodes will be returned. Otherwise, the total branch length of the tree will be returned.

Changed in version 0.6.3: Renamed from tip_subset. The old name is kept as an alias. Can accept TreeNode instances in addition to names. Can accept internal nodes in addition to tips.
include_stembool, optional: Whether to include the path from the lowest common ancestor (LCA) of the subset of nodes to self. Applicable when nodes is specified. Default is False.

Added in version 0.6.3.
include_selfbool, optional: Whether to include the length of self. When nodes is provided and include_stem is False, it is instead the LCA of the subset of nodes. Default is False.

Added in version 0.6.3.

Returns:

float: The total descending branch length.

Raises:

MissingNodeError: If some nodes are not found in the tree or are not descendants of self.

Notes

The metric can be considered as the total amount of evolutionary change across all lineages in the tree.

This metric is closely related to phylogenetic diversity (PD) in community ecology. When include_stem is True, it is equivalent to Faith’s PD (see faith_pd()). However, this method is optimized to handle a single set of nodes, whereas the referred function is optimized to simultaneously calculate for multiple taxon sets (i.e., communities).

Missing branch lengths will be replaced with 0.

Examples

>>> from skbio import TreeNode
>>> tree = TreeNode.read([
...     "(((A:.1,B:1.2)C:.6,(D:.9,E:.6)F:.9)G:2.4,(H:.4,I:.5)J:1.3)K;"])
>>> print(tree.ascii_art())
                              /-A
                    /C-------|
                   |          \-B
          /G-------|
         |         |          /-D
         |          \F-------|
-K-------|                    \-E
         |
         |          /-H
          \J-------|
                    \-I

Calculate the total branch length of the tree.

>>> L = tree.total_length()
>>> print(round(L, 1))
8.9

Calculate the total branch length connecting three taxa.

>>> L = tree.total_length(['A', 'E', 'H'])
>>> print(round(L, 1))
6.3