skbio.tree.TreeNode.tip_tip_distances#

TreeNode.tip_tip_distances(endpoints=None, use_length=True)[source]#

Return a distance matrix between pairs of tips.

Parameters:

endpointslist of TreeNode or str, optional: Tips or their names (i.e., taxa) to be included in the calculation. The returned distance matrix will use this order. If not specified, all tips will be included.
use_lengthbool, optional: Whether to return the sum of branch lengths (True, default) or the number of branches (False) connecting each pair of tips.

Added in version 0.6.3.

Returns:

DistanceMatrix: The distance matrix.

Raises:

MissingNodeError: If any of the specified endpoints are not found in the tree.
DuplicateNodeError: If the specified endpoints have duplicates.
ValueError: If any of the specified endpoints are not tips.

See also

distance
compare_tip_distances

Notes

This method calculates the sum of branch lengths connecting each pair of tips. It is also known as the patristic distance [1]. If a node does not have an associated branch length, 0 will be used.

If use_length is False, the method instead calculates the number of branches connecting each pair of tips.

This method operates on the subtree below the current node.

References

[1]

Fourment, M., & Gibbs, M. J. (2006). PATRISTIC: a program for calculating patristic distances and graphically comparing the components of genetic change. BMC evolutionary biology, 6, 1-5.

Examples

>>> from skbio import TreeNode
>>> tree = TreeNode.read(["((a:1,b:2)c:3,(d:4,e:5)f:6)root;"])

Calculate path length distances (patristic distances).

>>> mat = tree.tip_tip_distances()
>>> print(mat)
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.]]

Calculate path distances (branch counts).

>>> mat = tree.tip_tip_distances(use_length=False)
>>> print(mat)
4x4 distance matrix
IDs:
'a', 'b', 'd', 'e'
Data:
[[ 0.  2.  4.  4.]
 [ 2.  0.  4.  4.]
 [ 4.  4.  0.  2.]
 [ 4.  4.  2.  0.]]