skbio.tree.BPTree.cophenet#

BPTree.cophenet(endpoints=None, use_length=True, engine=None)[source]#

Return a distance matrix between each pair of tips in the tree.

The balanced-parentheses counterpart of skbio.tree.TreeNode.cophenet.

Parameters:

endpointsiterable of str, optional: Names of the tips to be included in the calculation. The returned distance matrix will use this order. If not specified, all named tips will be included, in the order they appear in the tree.
use_lengthbool, optional: Whether to return the sum of branch lengths (True, default) or the number of branches (False) connecting each pair of tips.
engine{‘cython’, ‘numba’, ‘fast’}, optional: The compute engine. Defaults to the global compute_engine option. 'fast' is chosen per tree: see the Notes of BPTree.

Returns:

DistanceMatrix: The cophenetic distance matrix. Its data is in the array backend and on the device of the tree’s data.

Raises:

MissingNodeError: If any of the specified endpoints are not found in the tree.
DuplicateNodeError: If the specified endpoints have duplicates, or if the tree has duplicate tip names when endpoints is not specified.
ValueError: If any of the specified endpoints are not tips.

See also

lca_batch
skbio.tree.TreeNode.cophenet

Notes

The distance between tips \(a\) and \(b\) with lowest common ancestor \(c\) is \(d(a) + d(b) - 2d(c)\), where \(d\) is the sum of branch lengths (or the number of branches) from the root. The tip pairs are independent and are computed in parallel by the selected engine, on a GPU for a tree on one (see BPTree). Missing branch lengths are 0.

Examples

>>> from skbio.tree import BPTree
>>> tree = BPTree.read(["((a:1,b:2)c:3,(d:4,e:5)f:6)root;"])
>>> print(tree.cophenet())
4x4 distance matrix
IDs:
'a', 'b', 'd', 'e'
Data:
[[  0.   3.  14.  15.]
 [  3.   0.  15.  16.]
 [ 14.  15.   0.   9.]
 [ 15.  16.   9.   0.]]