From 2b88d31bc6d4154744c42da7dd14fa154a2db69c Mon Sep 17 00:00:00 2001 From: Yan Wong Date: Tue, 24 Sep 2024 17:19:38 +0100 Subject: [PATCH 1/2] Clarity that path_length is a count, and that distance_between gives distance --- python/tskit/trees.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/python/tskit/trees.py b/python/tskit/trees.py index 3d4637829d..cd7a7af24b 100644 --- a/python/tskit/trees.py +++ b/python/tskit/trees.py @@ -2976,13 +2976,16 @@ def rf_distance(self, other): def path_length(self, u, v): """ - Returns the path length between two nodes - (i.e., the number of edges between two nodes in this tree). + Returns a count of the number of edges between two nodes in this tree. If the two nodes have a most recent common ancestor, then this is defined as ``tree.depth(u) + tree.depth(v) - 2 * tree.depth(tree.mrca(u, v))``. If the nodes do not have an MRCA (i.e., they are in disconnected subtrees) the path length is infinity. + .. note:: This counts the number of "hops" between two nodes. To find the branch + length distance between them, in units of time (i.e. the sum of edge lengths + that separate two nodes) use the :meth:`.distance_between` method instead. + .. seealso:: See also the :meth:`.depth` method :param int u: The first node for path length computation. From 63ad45d61fdfa82698376b3764aa31330de512f5 Mon Sep 17 00:00:00 2001 From: Yan Wong Date: Fri, 27 Sep 2024 08:02:28 +0100 Subject: [PATCH 2/2] Update python/tskit/trees.py Co-authored-by: Peter Ralph --- python/tskit/trees.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/tskit/trees.py b/python/tskit/trees.py index cd7a7af24b..efd452a351 100644 --- a/python/tskit/trees.py +++ b/python/tskit/trees.py @@ -2976,7 +2976,7 @@ def rf_distance(self, other): def path_length(self, u, v): """ - Returns a count of the number of edges between two nodes in this tree. + Returns the number of edges on the path in this tree between the two nodes. If the two nodes have a most recent common ancestor, then this is defined as ``tree.depth(u) + tree.depth(v) - 2 * tree.depth(tree.mrca(u, v))``. If the nodes do not have an MRCA (i.e., they are in disconnected subtrees) the path length