diff --git a/python/tests/test_highlevel.py b/python/tests/test_highlevel.py index ce11e0d384..cbd40ca91f 100644 --- a/python/tests/test_highlevel.py +++ b/python/tests/test_highlevel.py @@ -2012,11 +2012,11 @@ def test_apis(self): self.assertEqual(t1.get_root(), t1.root) self.assertEqual(t1.get_index(), t1.index) self.assertEqual(t1.get_interval(), t1.interval) - self.assertEqual(t1.get_length(), t1.length) self.assertEqual(t1.get_sample_size(), t1.sample_size) self.assertEqual(t1.get_num_mutations(), t1.num_mutations) self.assertEqual(t1.get_parent_dict(), t1.parent_dict) self.assertEqual(t1.get_total_branch_length(), t1.total_branch_length) + self.assertEqual(t1.span, t1.interval[1] - t1.interval[0]) # node properties root = t1.get_root() for node in t1.nodes(): @@ -2036,6 +2036,11 @@ def test_apis(self): self.assertEqual(t1.get_mrca(*pair), t1.mrca(*pair)) self.assertEqual(t1.get_tmrca(*pair), t1.tmrca(*pair)) + def test_deprecated_apis(self): + t1 = self.get_tree() + self.assertEqual(t1.get_length(), t1.span) + self.assertEqual(t1.length, t1.span) + def test_seek_index(self): ts = msprime.simulate(10, recombination_rate=3, length=5, random_seed=42) N = ts.num_trees diff --git a/python/tskit/trees.py b/python/tskit/trees.py index ecb4fbf3ef..97e8be87e4 100644 --- a/python/tskit/trees.py +++ b/python/tskit/trees.py @@ -604,9 +604,8 @@ def branch_length(self, u): >>> tree.time(tree.parent(u)) - tree.time(u) - Note that this is not related to the value returned by - :attr:`.length`, which describes the length of the interval - covered by the tree in genomic coordinates. + (note that this is not related to the property :attr:`.length` which + is a deprecated alias for the genomic :attr:`.span` covered by a tree) :param int u: The node of interest. :return: The branch length from u to its parent. @@ -915,17 +914,22 @@ def interval(self): return self._ll_tree.get_left(), self._ll_tree.get_right() def get_length(self): - # Deprecated alias for self.length + # Deprecated alias for self.span return self.length @property def length(self): + # Deprecated alias for self.span + return self.span + + @property + def span(self): """ - Returns the length of the genomic interval that this tree represents. + Returns the genomic distance that this tree spans. This is defined as :math:`r - l`, where :math:`(l, r)` is the genomic interval returned by :attr:`.interval`. - :return: The length of the genomic interval covered by this tree. + :return: The genomic distance covered by this tree. :rtype: int """ left, right = self.get_interval() @@ -2631,9 +2635,9 @@ def mean_descendants(self, reference_sets): Computes for every node the mean number of samples in each of the `reference_sets` that descend from that node, averaged over the portions of the genome for which the node is ancestral to *any* sample. - The output is an array, `C[node, j]`, which reports the total length of + The output is an array, `C[node, j]`, which reports the total span of all genomes in `reference_sets[j]` that inherit from `node`, divided by - the total length of the genome on which `node` is an ancestor to any + the total span of the genome on which `node` is an ancestor to any sample in the tree sequence. .. note:: This interface *may change*, particularly the normalization by @@ -2689,7 +2693,7 @@ def genealogical_nearest_neighbours(self, focal, reference_sets, num_threads=0): # TODO this may not be a good name because there is another version of the # statistic which may be occasionally useful where we return the tree-by-tree # value. We could do this by adding an extra dimension to the returned array - # which would give the values tree-by-tree. The tree lengths can be computed + # which would give the values tree-by-tree. The tree spans can be computed # easily enough, *but* there may be occasions when the statistic isn't # defined over particular trees. #