Change min_length to min_span in IBD APIs

Some minor doc updates also.

Author: jeromekelleher

c/tests/test_tables.c

@@ -6292,7 +6292,7 @@ test_ibd_segments_empty_result(void)
 }
 
 static void
-test_ibd_segments_min_length_max_time(void)
+test_ibd_segments_min_span_max_time(void)
 {
     int ret;
     tsk_treeseq_t ts;
@@ -9275,8 +9275,7 @@ main(int argc, char **argv)
             test_ibd_segments_single_tree_options },
         { "test_ibd_segments_multiple_trees", test_ibd_segments_multiple_trees },
         { "test_ibd_segments_empty_result", test_ibd_segments_empty_result },
-        { "test_ibd_segments_min_length_max_time",
-            test_ibd_segments_min_length_max_time },
+        { "test_ibd_segments_min_span_max_time", test_ibd_segments_min_span_max_time },
         { "test_ibd_segments_single_tree_between",
             test_ibd_segments_single_tree_between },
         { "test_ibd_segments_samples_are_descendants",

c/tskit/tables.c

@@ -7634,7 +7634,7 @@ tsk_identity_segments_get(const tsk_identity_segments_t *self, tsk_id_t sample_a
 
 typedef struct {
     tsk_identity_segments_t *result;
-    double min_length;
+    double min_span;
     double max_time;
     const tsk_table_collection_t *tables;
     /* Maps nodes to their sample set IDs. Input samples map to set 0
@@ -7755,14 +7755,14 @@ tsk_ibd_finder_add_sample_ancestry(tsk_ibd_finder_t *self)
 
 static int TSK_WARN_UNUSED
 tsk_ibd_finder_init(tsk_ibd_finder_t *self, const tsk_table_collection_t *tables,
-    tsk_identity_segments_t *result, double min_length, double max_time)
+    tsk_identity_segments_t *result, double min_span, double max_time)
 {
     int ret = 0;
     tsk_size_t num_nodes;
 
     tsk_memset(self, 0, sizeof(tsk_ibd_finder_t));
 
-    if (min_length < 0) {
+    if (min_span < 0) {
         ret = TSK_ERR_BAD_PARAM_VALUE;
         goto out;
     }
@@ -7774,7 +7774,7 @@ tsk_ibd_finder_init(tsk_ibd_finder_t *self, const tsk_table_collection_t *tables
     self->tables = tables;
     self->result = result;
     self->max_time = max_time;
-    self->min_length = min_length;
+    self->min_span = min_span;
 
     ret = tsk_blkalloc_init(&self->segment_heap, 8192);
     if (ret != 0) {
@@ -7807,7 +7807,7 @@ tsk_ibd_finder_enqueue_segment(
     tsk_segment_t *seg;
     void *p;
 
-    if ((right - left) > self->min_length) {
+    if ((right - left) > self->min_span) {
         /* Make sure we always have room for one more segment in the queue so we
          * can put a tail sentinel on it */
         if (self->segment_queue_size == self->max_segment_queue_size - 1) {
@@ -7837,7 +7837,7 @@ tsk_ibd_finder_passes_filters(
     if (a == b) {
         return false;
     }
-    if ((right - left) <= self->min_length) {
+    if ((right - left) <= self->min_span) {
         return false;
     }
     if (self->finding_between) {
@@ -7901,7 +7901,7 @@ tsk_ibd_finder_print_state(tsk_ibd_finder_t *self, FILE *out)
 
     fprintf(out, "--ibd-finder stats--\n");
     fprintf(out, "max_time = %f\n", self->max_time);
-    fprintf(out, "min_length = %f\n", self->min_length);
+    fprintf(out, "min_span = %f\n", self->min_span);
     fprintf(out, "finding_between = %d\n", self->finding_between);
     fprintf(out, "===\nEdges\n===\n");
     for (j = 0; j < self->tables->edges.num_rows; j++) {
@@ -10941,7 +10941,7 @@ tsk_table_collection_link_ancestors(tsk_table_collection_t *self, tsk_id_t *samp
 int TSK_WARN_UNUSED
 tsk_table_collection_ibd_within(const tsk_table_collection_t *self,
     tsk_identity_segments_t *result, const tsk_id_t *samples, tsk_size_t num_samples,
-    double min_length, double max_time, tsk_flags_t options)
+    double min_span, double max_time, tsk_flags_t options)
 {
     int ret = 0;
     tsk_ibd_finder_t ibd_finder;
@@ -10950,7 +10950,7 @@ tsk_table_collection_ibd_within(const tsk_table_collection_t *self,
     if (ret != 0) {
         goto out;
     }
-    ret = tsk_ibd_finder_init(&ibd_finder, self, result, min_length, max_time);
+    ret = tsk_ibd_finder_init(&ibd_finder, self, result, min_span, max_time);
     if (ret != 0) {
         goto out;
     }
@@ -10973,7 +10973,7 @@ tsk_table_collection_ibd_within(const tsk_table_collection_t *self,
 int TSK_WARN_UNUSED
 tsk_table_collection_ibd_between(const tsk_table_collection_t *self,
     tsk_identity_segments_t *result, tsk_size_t num_sample_sets,
-    const tsk_size_t *sample_set_sizes, const tsk_id_t *sample_sets, double min_length,
+    const tsk_size_t *sample_set_sizes, const tsk_id_t *sample_sets, double min_span,
     double max_time, tsk_flags_t options)
 {
     int ret = 0;
@@ -10983,7 +10983,7 @@ tsk_table_collection_ibd_between(const tsk_table_collection_t *self,
     if (ret != 0) {
         goto out;
     }
-    ret = tsk_ibd_finder_init(&ibd_finder, self, result, min_length, max_time);
+    ret = tsk_ibd_finder_init(&ibd_finder, self, result, min_span, max_time);
     if (ret != 0) {
         goto out;
     }

c/tskit/tables.h

@@ -4139,11 +4139,11 @@ tsk_id_t tsk_table_collection_check_integrity(
  * This should be done as part of documenting, I guess. */
 int tsk_table_collection_ibd_within(const tsk_table_collection_t *self,
     tsk_identity_segments_t *result, const tsk_id_t *samples, tsk_size_t num_samples,
-    double min_length, double max_time, tsk_flags_t options);
+    double min_span, double max_time, tsk_flags_t options);
 
 int tsk_table_collection_ibd_between(const tsk_table_collection_t *self,
     tsk_identity_segments_t *result, tsk_size_t num_sample_sets,
-    const tsk_size_t *sample_set_sizes, const tsk_id_t *sample_sets, double min_length,
+    const tsk_size_t *sample_set_sizes, const tsk_id_t *sample_sets, double min_span,
     double max_time, tsk_flags_t options);
 
 int tsk_table_collection_link_ancestors(tsk_table_collection_t *self, tsk_id_t *samples,

docs/ibd.md

@@ -19,13 +19,17 @@ kernelspec:
 
 # Identity by descent
 
-The {meth}`.TreeSequence.ibd_segments` allows us to compute
+The {meth}`.TreeSequence.ibd_segments` method allows us to compute
 segments of identity by descent.
 
 :::{note}
 This documentation page is preliminary
 :::
 
+:::{todo}
+Relate the concept of identity by descent to the MRCA spans in the tree sequence.
+:::
+
 ## Examples
 
 Let's take a simple tree sequence to illustrate the {meth}`.TreeSequence.ibd_segments`
@@ -78,8 +82,8 @@ segments returned are the longest possible ones.
 Consider the IBD segments that we get from our example tree sequence:
 
 ```{code-cell}
-segs = ts.ibd_segments(store_segments=True)
-for pair, segment_list in segs.items():
+segments = ts.ibd_segments(store_segments=True)
+for pair, segment_list in segments.items():
     print(pair, list(segment_list))
 ```
 
@@ -97,8 +101,8 @@ The result of calling {meth}`.TreeSequence.ibd_segments` is an
 {class}`.IdentitySegments` class:
 
 ```{code-cell}
-segs = ts.ibd_segments()
-print(segs)
+segments = ts.ibd_segments()
+print(segments)
 ```
 
 By default this class only stores the high-level summaries of the
@@ -121,27 +125,27 @@ needing to store the actual lists.
 
 
 ```{code-cell}
-segs = ts.ibd_segments(store_pairs=True)
-for pair, value in segs.items():
+segments = ts.ibd_segments(store_pairs=True)
+for pair, value in segments.items():
     print(pair, "::", value)
 ```
 
 Now we can see the more detailed breakdown of how the identity segments
 are distributed among the sample pairs. The {class}`.IdentitySegments`
-class behaves like a dictionary, such that ``segs[(a, b)]`` will return
+class behaves like a dictionary, such that ``segments[(a, b)]`` will return
 the {class}`.IdentitySegmentList` instance for that pair of samples:
 
 ```{code-cell}
-seglist = segs[(0, 1)]
+seglist = segments[(0, 1)]
 print(seglist)
 ```
 
 If we want to access the detailed information about the actual
 identity segments, we must use the ``store_segments`` argument:
 
 ```{code-cell}
-segs = ts.ibd_segments(store_pairs=True, store_segments=True)
-segs[(0, 1)]
+segments = ts.ibd_segments(store_pairs=True, store_segments=True)
+segments[(0, 1)]
 ```
 
 The {class}`.IdentitySegmentList` behaves like a Python list,
@@ -161,29 +165,29 @@ is arbitrary, and may change in future versions.
 ### Controlling the sample sets
 
 By default we get the IBD segments between all pairs of
-:ref:`sample<sec_data_model_definitions_samples>` nodes.
+{ref}`sample<sec_data_model_definitions_sample>` nodes.
 
 #### IBD within a sample set
 We can reduce this to pairs within a specific set using the
-``within`` argument::
+``within`` argument:
 
 
 ```{eval-rst}
 .. todo:: More detail and better examples here.
 ```
 
 ```{code-cell}
-segs = ts.ibd_segments(within=[0, 2], store_pairs=True)
-print(list(segs.keys()))
+segments = ts.ibd_segments(within=[0, 2], store_pairs=True)
+print(list(segments.keys()))
 ```
 
 #### IBD between sample sets
 
 We can also compute IBD **between** sample sets:
 
 ```{code-cell}
-segs = ts.ibd_segments(between=[[0,1], [2]], store_pairs=True)
-print(list(segs.keys()))
+segments = ts.ibd_segments(between=[[0,1], [2]], store_pairs=True)
+print(list(segments.keys()))
 ```
 
 :::{seealso}
@@ -193,7 +197,7 @@ more details.
 
 ### Constraints on the segments
 
-The ``max_time`` and ``min_length`` arguments allow us to constrain the
+The ``max_time`` and ``min_span`` arguments allow us to constrain the
 segments that we consider.
 
 ```{eval-rst}

python/_tskitmodule.c

@@ -6811,20 +6811,20 @@ TableCollection_ibd_segments_within(
     PyArrayObject *samples_array = NULL;
     int32_t *samples = NULL;
     tsk_size_t num_samples = 0;
-    double min_length = 0;
+    double min_span = 0;
     double max_time = DBL_MAX;
     int store_pairs = 0;
     int store_segments = 0;
     npy_intp *shape;
     static char *kwlist[]
-        = { "samples", "min_length", "max_time", "store_pairs", "store_segments", NULL };
+        = { "samples", "min_span", "max_time", "store_pairs", "store_segments", NULL };
     tsk_flags_t options = 0;
 
     if (TableCollection_check_state(self) != 0) {
         goto out;
     }
     if (!PyArg_ParseTupleAndKeywords(args, kwds, "|Oddii", kwlist, &py_samples,
-            &min_length, &max_time, &store_pairs, &store_segments)) {
+            &min_span, &max_time, &store_pairs, &store_segments)) {
         goto out;
     }
     if (py_samples != Py_None) {
@@ -6851,7 +6851,7 @@ TableCollection_ibd_segments_within(
     }
 
     err = tsk_table_collection_ibd_within(self->tables, result->identity_segments,
-        samples, num_samples, min_length, max_time, options);
+        samples, num_samples, min_span, max_time, options);
     if (err != 0) {
         handle_library_error(err);
         goto out;
@@ -6876,19 +6876,19 @@ TableCollection_ibd_segments_between(
     PyArrayObject *sample_set_sizes_array = NULL;
     IdentitySegments *result = NULL;
     tsk_size_t num_sample_sets;
-    double min_length = 0;
+    double min_span = 0;
     double max_time = DBL_MAX;
     int store_pairs = 0;
     int store_segments = 0;
-    static char *kwlist[] = { "sample_set_sizes", "sample_sets", "min_length",
-        "max_time", "store_pairs", "store_segments", NULL };
+    static char *kwlist[] = { "sample_set_sizes", "sample_sets", "min_span", "max_time",
+        "store_pairs", "store_segments", NULL };
     tsk_flags_t options = 0;
 
     if (TableCollection_check_state(self) != 0) {
         goto out;
     }
     if (!PyArg_ParseTupleAndKeywords(args, kwds, "OO|ddii", kwlist, &sample_set_sizes,
-            &sample_sets, &min_length, &max_time, &store_pairs, &store_segments)) {
+            &sample_sets, &min_span, &max_time, &store_pairs, &store_segments)) {
         goto out;
     }
     if (parse_sample_sets(sample_set_sizes, &sample_set_sizes_array, sample_sets,
@@ -6911,7 +6911,7 @@ TableCollection_ibd_segments_between(
 
     err = tsk_table_collection_ibd_between(self->tables, result->identity_segments,
         num_sample_sets, (tsk_size_t *) PyArray_DATA(sample_set_sizes_array),
-        (tsk_id_t *) PyArray_DATA(sample_sets_array), min_length, max_time, options);
+        (tsk_id_t *) PyArray_DATA(sample_sets_array), min_span, max_time, options);
     if (err != 0) {
         handle_library_error(err);
         goto out;

python/tests/ibd.py

@@ -144,7 +144,7 @@ class IbdFinder:
     Finds all IBD relationships between specified sample pairs in a tree sequence.
     """
 
-    def __init__(self, ts, *, within=None, between=None, min_length=0, max_time=None):
+    def __init__(self, ts, *, within=None, between=None, min_span=0, max_time=None):
         self.ts = ts
         self.result = IbdResult()
         if within is not None and between is not None:
@@ -160,7 +160,7 @@ def __init__(self, ts, *, within=None, between=None, min_length=0, max_time=None
             if within is None:
                 within = ts.samples()
             self.sample_set_id[within] = 0
-        self.min_length = min_length
+        self.min_span = min_span
         self.max_time = np.inf if max_time is None else max_time
         self.A = [SegmentList() for _ in range(ts.num_nodes)]  # Descendant segments
         for u in range(ts.num_nodes):
@@ -170,7 +170,7 @@ def __init__(self, ts, *, within=None, between=None, min_length=0, max_time=None
 
     def print_state(self):
         print("IBD Finder")
-        print("min_length = ", self.min_length)
+        print("min_span = ", self.min_span)
         print("max_time   = ", self.max_time)
         print("finding_between = ", self.finding_between)
         print("u\tset_id\tA = ")
@@ -192,7 +192,7 @@ def run(self):
                     max(e.left, s.left),
                     min(e.right, s.right),
                 )
-                if intvl[1] - intvl[0] > self.min_length:
+                if intvl[1] - intvl[0] > self.min_span:
                     child_segs.append(Segment(intvl[0], intvl[1], s.node))
                 s = s.next
             self.record_ibd(e.parent, child_segs)
@@ -227,7 +227,7 @@ def record_ibd(self, current_parent, child_segs):
     def passes_filters(self, a, b, left, right):
         if a == b:
             return False
-        if right - left <= self.min_length:
+        if right - left <= self.min_span:
             return False
         if self.finding_between:
             return self.sample_set_id[a] != self.sample_set_id[b]
@@ -258,7 +258,7 @@ def passes_filters(self, a, b, left, right):
     parser.add_argument(
         "--min-length",
         type=float,
-        dest="min_length",
+        dest="min_span",
         nargs=1,
         metavar="MIN_LENGTH",
         help="Only segments longer than this cutoff will be returned.",
@@ -284,16 +284,16 @@ def passes_filters(self, a, b, left, right):
 
     args = parser.parse_args()
     ts = tskit.load(args.infile[0])
-    if args.min_length is None:
-        min_length = 0
+    if args.min_span is None:
+        min_span = 0
     else:
-        min_length = args.min_length[0]
+        min_span = args.min_span[0]
     if args.max_time is None:
         max_time = None
     else:
         max_time = args.max_time[0]
 
-    s = IbdFinder(ts, samples=ts.samples(), min_length=min_length, max_time=max_time)
+    s = IbdFinder(ts, samples=ts.samples(), min_span=min_span, max_time=max_time)
     all_segs = s.find_ibd_segments()
 
     if args.samples is None: