Skip to main content
`Ctrl`+`K`

# skbio.tree.TreeNode.biparts

TreeNode.biparts(within=None, include_tips=False, map_to_length=False, full=None)

  Return all bipartitions within the tree under self.

  Added in version 0.6.3.

  Parameters:
    within iterable of str, optional

      A custom set of taxa to refine the result. Only taxa within it will be considered. If None (default), all taxa in the tree will be considered.

    include_tips bool, optional

      Whether to include bipartitions with only one taxon at either side. Default is False, as such bipartitions provide no topological information.

    map_to_length bool, optional

      If True, return a mapping of subsets to their branch lengths. Missing branch lengths will be replaced with 0. Default is False.

    full frozenset of str, optional

      Pre-computed full set of taxa of the current tree. Providing this parameter can save one tree traversal from computing.

  Returns:
    frozenset of frozenset of str, or

      All sets of names at the tips on the smaller side of each branch. Returned if map_to_length is False.

    dict of {frozenset of str: float}

      Mapping of All sets of smaller-side tip names to branch lengths. Returned if map_to_length is True.

  See also

  `bipart`
  `subsets`

  Notes

  The returned value represents the tree as a set of nested sets, each of which representing the position of a branch in the tree. It is useful for assessing topological patterns of a tree.

  The returned value itself and each of its components (frozensets) are unordered and hashable, making it efficient for lookup and comparison. For example, one can check whether the topologies of two trees are consistent, regardless of their root positions.

  This method can be applied to both rooted and unrooted trees. However, a rooted tree implies the direction of descendance, which may violate the purpose of bipartitioning a tree on arbitrary branches. If this is a concern, one should consider using `subsets` instead.

  This method operates on the subtree below the current node.

  Examples

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

  Return all bipartitions of an unrooted tree.

      >>> biparts = tree.biparts()
      >>> for s in sorted(biparts, key=sorted):
      ...     print(sorted(s))
      ['a', 'b', 'c']
      ['b', 'c']
      ['d', 'e']

  A second tree with the same topology but different root position.

      >>> tree2 = TreeNode.read(["(a,((b,c),((d,e),f)));"])
      >>> print(tree2.ascii_art())
                /-a
               |
      ---------|                    /-b
               |          /--------|
               |         |          \-c
                \--------|
                         |                    /-d
                         |          /--------|
                          \--------|          \-e
                                   |
                                    \-f

  Although the tree has been re-positioned, the bipartitions remain the same.

      >>> biparts == tree2.biparts()
      True