Fixes #262

Author: hyanwong

c/tests/test_tables.c

@@ -1986,7 +1986,7 @@ test_provenance_table(void)
 }
 
 static void
-test_map_ancestors_input_errors(void)
+test_link_ancestors_input_errors(void)
 {
     int ret;
     tsk_treeseq_t ts;
@@ -2002,30 +2002,30 @@ test_map_ancestors_input_errors(void)
     ret = tsk_edge_table_init(&result, 0);
     CU_ASSERT_EQUAL_FATAL(ret, 0);
 
-    ret = tsk_table_collection_map_ancestors(&tables, NULL, 2, ancestors, 2, 0, &result);
+    ret = tsk_table_collection_link_ancestors(&tables, NULL, 2, ancestors, 2, 0, &result);
     CU_ASSERT_EQUAL_FATAL(ret, TSK_ERR_BAD_PARAM_VALUE);
 
     /* Bad sample IDs */
     samples[0] = -1;
-    ret = tsk_table_collection_map_ancestors(&tables, samples, 2, ancestors, 2, 0, &result);
+    ret = tsk_table_collection_link_ancestors(&tables, samples, 2, ancestors, 2, 0, &result);
     CU_ASSERT_EQUAL_FATAL(ret, TSK_ERR_NODE_OUT_OF_BOUNDS);
 
     /* Bad ancestor IDs */
     samples[0] = 0;
     ancestors[0] = -1;
-    ret = tsk_table_collection_map_ancestors(&tables, samples, 2, ancestors, 2, 0, &result);
+    ret = tsk_table_collection_link_ancestors(&tables, samples, 2, ancestors, 2, 0, &result);
     CU_ASSERT_EQUAL_FATAL(ret, TSK_ERR_NODE_OUT_OF_BOUNDS);
 
     /* Duplicate sample IDs */
     ancestors[0] = 4;
     samples[0] = 1;
-    ret = tsk_table_collection_map_ancestors(&tables, samples, 2, ancestors, 2, 0, &result);
+    ret = tsk_table_collection_link_ancestors(&tables, samples, 2, ancestors, 2, 0, &result);
     CU_ASSERT_EQUAL_FATAL(ret, TSK_ERR_DUPLICATE_SAMPLE);
 
     /* Duplicate sample IDs */
     ancestors[0] = 6;
     samples[0] = 0;
-    ret = tsk_table_collection_map_ancestors(&tables, samples, 2, ancestors, 2, 0, &result);
+    ret = tsk_table_collection_link_ancestors(&tables, samples, 2, ancestors, 2, 0, &result);
     CU_ASSERT_EQUAL_FATAL(ret, TSK_ERR_DUPLICATE_SAMPLE);
 
     /* TODO more tests! */
@@ -2036,7 +2036,7 @@ test_map_ancestors_input_errors(void)
 }
 
 static void
-test_map_ancestors_single_tree(void)
+test_link_ancestors_single_tree(void)
 {
     int ret;
     tsk_treeseq_t ts;
@@ -2055,7 +2055,7 @@ test_map_ancestors_single_tree(void)
     ret = tsk_edge_table_init(&result, 0);
     CU_ASSERT_EQUAL_FATAL(ret, 0);
 
-    ret = tsk_table_collection_map_ancestors(&tables, samples, 2, ancestors, 2, 0, &result);
+    ret = tsk_table_collection_link_ancestors(&tables, samples, 2, ancestors, 2, 0, &result);
     CU_ASSERT_EQUAL_FATAL(ret, 0);
 
     // Check we get the right result.
@@ -2076,7 +2076,7 @@ test_map_ancestors_single_tree(void)
 }
 
 static void
-test_map_ancestors_no_edges(void)
+test_link_ancestors_no_edges(void)
 {
     int ret;
     tsk_treeseq_t ts;
@@ -2092,7 +2092,7 @@ test_map_ancestors_no_edges(void)
     ret = tsk_edge_table_init(&result, 0);
     CU_ASSERT_EQUAL_FATAL(ret, 0);
 
-    ret = tsk_table_collection_map_ancestors(&tables, samples, 1, ancestors, 1, 0, &result);
+    ret = tsk_table_collection_link_ancestors(&tables, samples, 1, ancestors, 1, 0, &result);
     CU_ASSERT_EQUAL_FATAL(ret, 0);
 
     tsk_table_collection_free(&tables);
@@ -2102,7 +2102,7 @@ test_map_ancestors_no_edges(void)
 }
 
 static void
-test_map_ancestors_samples_and_ancestors_overlap(void)
+test_link_ancestors_samples_and_ancestors_overlap(void)
 {
     int ret;
     tsk_treeseq_t ts;
@@ -2118,7 +2118,7 @@ test_map_ancestors_samples_and_ancestors_overlap(void)
     ret = tsk_edge_table_init(&result, 0);
     CU_ASSERT_EQUAL_FATAL(ret, 0);
 
-    ret = tsk_table_collection_map_ancestors(&tables, samples, 4, ancestors, 1, 0, &result);
+    ret = tsk_table_collection_link_ancestors(&tables, samples, 4, ancestors, 1, 0, &result);
 
     // tsk_edge_table_print_state(&result, stdout);
 
@@ -2143,7 +2143,7 @@ test_map_ancestors_samples_and_ancestors_overlap(void)
 }
 
 static void
-test_map_ancestors_paper(void)
+test_link_ancestors_paper(void)
 {
     int ret;
     tsk_treeseq_t ts;
@@ -2159,7 +2159,7 @@ test_map_ancestors_paper(void)
     ret = tsk_edge_table_init(&result, 0);
     CU_ASSERT_EQUAL_FATAL(ret, 0);
 
-    ret = tsk_table_collection_map_ancestors(&tables, samples, 3, ancestors, 3, 0, &result);
+    ret = tsk_table_collection_link_ancestors(&tables, samples, 3, ancestors, 3, 0, &result);
 
     // tsk_edge_table_print_state(&result, stdout);
 
@@ -2183,7 +2183,7 @@ test_map_ancestors_paper(void)
 }
 
 static void
-test_map_ancestors_multiple_to_single_tree(void)
+test_link_ancestors_multiple_to_single_tree(void)
 {
     int ret;
     tsk_treeseq_t ts;
@@ -2199,7 +2199,7 @@ test_map_ancestors_multiple_to_single_tree(void)
     ret = tsk_edge_table_init(&result, 0);
     CU_ASSERT_EQUAL_FATAL(ret, 0);
 
-    ret = tsk_table_collection_map_ancestors(&tables, samples, 2, ancestors, 1, 0, &result);
+    ret = tsk_table_collection_link_ancestors(&tables, samples, 2, ancestors, 1, 0, &result);
 
     // tsk_edge_table_print_state(&result, stdout);
 
@@ -2651,14 +2651,14 @@ main(int argc, char **argv)
         {"test_load_tsk_node_table_errors", test_load_tsk_node_table_errors},
         {"test_simplify_tables_drops_indexes", test_simplify_tables_drops_indexes},
         {"test_simplify_empty_tables", test_simplify_empty_tables},
-        {"test_map_ancestors_no_edges", test_map_ancestors_no_edges},
-        {"test_map_ancestors_input_errors", test_map_ancestors_input_errors},
-        {"test_map_ancestors_single_tree", test_map_ancestors_single_tree},
-        {"test_map_ancestors_paper", test_map_ancestors_paper},
-        {"test_map_ancestors_samples_and_ancestors_overlap",
-            test_map_ancestors_samples_and_ancestors_overlap},
-        {"test_map_ancestors_multiple_to_single_tree",
-            test_map_ancestors_multiple_to_single_tree},
+        {"test_link_ancestors_no_edges", test_link_ancestors_no_edges},
+        {"test_link_ancestors_input_errors", test_link_ancestors_input_errors},
+        {"test_link_ancestors_single_tree", test_link_ancestors_single_tree},
+        {"test_link_ancestors_paper", test_link_ancestors_paper},
+        {"test_link_ancestors_samples_and_ancestors_overlap",
+            test_link_ancestors_samples_and_ancestors_overlap},
+        {"test_link_ancestors_multiple_to_single_tree",
+            test_link_ancestors_multiple_to_single_tree},
         {"test_sort_tables_drops_indexes", test_sort_tables_drops_indexes},
         {"test_copy_table_collection", test_copy_table_collection},
         {"test_sort_tables_errors", test_sort_tables_errors},

c/tskit/tables.c

@@ -6496,7 +6496,7 @@ tsk_table_collection_simplify(tsk_table_collection_t *self,
 }
 
 int TSK_WARN_UNUSED
-tsk_table_collection_map_ancestors(tsk_table_collection_t *self, tsk_id_t *samples,
+tsk_table_collection_link_ancestors(tsk_table_collection_t *self, tsk_id_t *samples,
         tsk_size_t num_samples, tsk_id_t *ancestors, tsk_size_t num_ancestors,
         tsk_flags_t TSK_UNUSED(options), tsk_edge_table_t *result)
 {

c/tskit/tables.h

@@ -2211,7 +2211,7 @@ int tsk_table_collection_build_index(tsk_table_collection_t *self, tsk_flags_t o
 
 /* Undocumented methods */
 
-int tsk_table_collection_map_ancestors(tsk_table_collection_t *self,
+int tsk_table_collection_link_ancestors(tsk_table_collection_t *self,
     tsk_id_t *samples, tsk_size_t num_samples,
     tsk_id_t *ancestors, tsk_size_t num_ancestors, tsk_flags_t options,
     tsk_edge_table_t *result);

python/_tskitmodule.c

@@ -5468,7 +5468,7 @@ TableCollection_simplify(TableCollection *self, PyObject *args, PyObject *kwds)
 
 
 static PyObject *
-TableCollection_map_ancestors(TableCollection *self, PyObject *args, PyObject *kwds)
+TableCollection_link_ancestors(TableCollection *self, PyObject *args, PyObject *kwds)
 {
     int err;
     PyObject *ret = NULL;
@@ -5510,7 +5510,7 @@ TableCollection_map_ancestors(TableCollection *self, PyObject *args, PyObject *k
     if (result == NULL) {
         goto out;
     }
-    err = tsk_table_collection_map_ancestors(self->tables,
+    err = tsk_table_collection_link_ancestors(self->tables,
             PyArray_DATA(samples_array), num_samples,
             PyArray_DATA(ancestors_array), num_ancestors, 0,
             result->table);
@@ -5660,7 +5660,7 @@ static PyGetSetDef TableCollection_getsetters[] = {
 static PyMethodDef TableCollection_methods[] = {
     {"simplify", (PyCFunction) TableCollection_simplify, METH_VARARGS|METH_KEYWORDS,
         "Simplifies for a given sample subset." },
-    {"map_ancestors", (PyCFunction) TableCollection_map_ancestors,
+    {"link_ancestors", (PyCFunction) TableCollection_link_ancestors,
         METH_VARARGS|METH_KEYWORDS,
         "Returns an edge table linking samples to a set of specified ancestors." },
     {"sort", (PyCFunction) TableCollection_sort, METH_VARARGS|METH_KEYWORDS,

python/tests/simplify.py

@@ -469,7 +469,7 @@ def __init__(self, ts, sample, ancestors):
             self.add_ancestry(0, self.sequence_length, sample_id, sample_id)
         self.edge_buffer = {}
 
-    def map_ancestors(self):
+    def link_ancestors(self):
         if self.ts.num_edges > 0:
             all_edges = list(self.ts.edges())
             edges = all_edges[:1]
@@ -659,7 +659,7 @@ def print_state(self):
         ancestors = list(map(int, ancestors))
 
         s = AncestorMap(ts, samples, ancestors)
-        tss = s.map_ancestors()
+        tss = s.link_ancestors()
         # tables = tss.dump_tables()
         # print(tables.nodes)
         print(tss)

python/tests/test_lowlevel.py

@@ -182,26 +182,26 @@ def test_simplify_bad_args(self):
         with self.assertRaises(_tskit.LibraryError):
             tc.simplify([0, -1])
 
-    def test_map_ancestors_bad_args(self):
+    def test_link_ancestors_bad_args(self):
         ts = msprime.simulate(10, random_seed=1)
         tc = ts.tables.ll_tables
         with self.assertRaises(TypeError):
-            tc.map_ancestors()
+            tc.link_ancestors()
         with self.assertRaises(TypeError):
-            tc.map_ancestors([0, 1])
+            tc.link_ancestors([0, 1])
         with self.assertRaises(ValueError):
-            tc.map_ancestors(samples=[0, 1], ancestors="sdf")
+            tc.link_ancestors(samples=[0, 1], ancestors="sdf")
         with self.assertRaises(ValueError):
-            tc.map_ancestors(samples="sdf", ancestors=[0, 1])
+            tc.link_ancestors(samples="sdf", ancestors=[0, 1])
         with self.assertRaises(_tskit.LibraryError):
-            tc.map_ancestors(samples=[0, 1], ancestors=[11, -1])
+            tc.link_ancestors(samples=[0, 1], ancestors=[11, -1])
         with self.assertRaises(_tskit.LibraryError):
-            tc.map_ancestors(samples=[0, -1], ancestors=[11])
+            tc.link_ancestors(samples=[0, -1], ancestors=[11])
 
-    def test_map_ancestors(self):
+    def test_link_ancestors(self):
         ts = msprime.simulate(2, random_seed=1)
         tc = ts.tables.ll_tables
-        edges = tc.map_ancestors([0, 1], [3])
+        edges = tc.link_ancestors([0, 1], [3])
         self.assertIsInstance(edges, _tskit.EdgeTable)
         del edges
         self.assertEqual(tc.edges.num_rows, 2)

python/tests/test_topology.py

@@ -3551,17 +3551,33 @@ class TestMapToAncestors(unittest.TestCase):
 
     def do_map(self, ts, ancestors, samples=None, compare_lib=True):
         """
-        Runs the Python test implementation of map_ancestors.
+        Runs the Python test implementation of link_ancestors.
         """
         if samples is None:
             samples = ts.samples()
         s = tests.AncestorMap(ts, samples, ancestors)
-        ancestor_table = s.map_ancestors()
+        ancestor_table = s.link_ancestors()
         if compare_lib:
-            lib_result = ts.tables.map_ancestors(samples, ancestors)
+            lib_result = ts.tables.link_ancestors(samples, ancestors)
             self.assertEqual(ancestor_table, lib_result)
         return ancestor_table
 
+    def test_deprecated_name(self):
+        # copied from test_single_tree_one_ancestor below
+        nodes = io.StringIO(self.nodes)
+        edges = io.StringIO(self.edges)
+        ts = tskit.load_text(nodes=nodes, edges=edges, strict=False)
+        samples = ts.samples()
+        ancestors = [8]
+        s = tests.AncestorMap(ts, samples, ancestors)
+        tss = s.link_ancestors()
+        lib_result = ts.tables.map_ancestors(samples, ancestors)
+        self.assertEqual(tss, lib_result)
+        self.assertEqual(list(tss.parent), [8, 8, 8, 8, 8])
+        self.assertEqual(list(tss.child), [0, 1, 2, 3, 4])
+        self.assertEqual(all(tss.left), 0)
+        self.assertEqual(all(tss.right), 1)
+
     def test_single_tree_one_ancestor(self):
         nodes = io.StringIO(self.nodes)
         edges = io.StringIO(self.edges)

python/tskit/tables.py

@@ -1609,7 +1609,7 @@ def simplify(
             reduce_to_site_topology=reduce_to_site_topology,
             keep_unary=keep_unary)
 
-    def map_ancestors(self, samples, ancestors):
+    def link_ancestors(self, samples, ancestors):
         """
         Returns an :class:`EdgeTable` instance describing a subset of the genealogical
         relationships between the nodes in``samples`` and ``ancestors``.
@@ -1627,12 +1627,12 @@ def map_ancestors(self, samples, ancestors):
         ``ancestors``.
 
         The following table shows which ``parent->child`` pairs will be shown in the
-        output of ``map_ancestors``.
+        output of ``link_ancestors``.
         A node is a relevant descendant on a given interval if it also appears somewhere
         in the ``parent`` column of the outputted table.
 
         ========================  ===============================================
-        Type of relationship      Shown in output of ``map_ancestors``
+        Type of relationship      Shown in output of ``link_ancestors``
         ------------------------  -----------------------------------------------
         ``ancestor->sample``      Always
         ``ancestor1->ancestor2``  Only if ``ancestor2`` has a relevant descendant
@@ -1664,9 +1664,13 @@ def map_ancestors(self, samples, ancestors):
         """
         samples = util.safe_np_int_cast(samples, np.int32)
         ancestors = util.safe_np_int_cast(ancestors, np.int32)
-        ll_edge_table = self.ll_tables.map_ancestors(samples, ancestors)
+        ll_edge_table = self.ll_tables.link_ancestors(samples, ancestors)
         return EdgeTable(ll_table=ll_edge_table)
 
+    def map_ancestors(self, *args, **kwargs):
+        # A deprecated alias for link_ancestors()
+        return self.link_ancestors(*args, **kwargs)
+
     def sort(self, edge_start=0):
         """
         Sorts the tables in place. This ensures that all tree sequence ordering