Skip to main content
`Ctrl`+`K`

# skbio.tree.TreeNode.total_length

TreeNode.total_length(nodes=None, include_stem=False, include_self=False)

  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:
    nodes iterable 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 but is deprecated.

      Changed in version 0.6.3: Can accept TreeNode instances in addition to names. Can accept internal nodes in addition to tips.

    include_stem bool, 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_self bool, 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