Extract Identity-by-Descent (IBD) segments (EXPERIMENTAL)

This function extracts IBD segments between pairs of individuals or nodes from a given tree sequence.

Usage

ts_ibd(
  ts,
  within = NULL,
  between = NULL,
  maximum_time = NULL,
  minimum_length = 0,
  sf = TRUE
)

Arguments

ts: Tree sequence object of the class slendr_ts
within: A character vector with individual names or an integer vector with node IDs indicating a set of nodes within which to look for IBD segments.
between: A list of lists of character vectors with individual names or integer vectors with node IDs, indicating a set of nodes between which to look for shared IBD segments.
maximum_time: Oldest MRCA of a node to be considered as an IBD ancestor to return that IBD segment in results. This is useful for reducing the total amount of IBD returned.
minimum_length: Minimum length of a ("squashed") IBD segment for it to be included in the results
sf: If IBD segments in a spatial tree sequence are being analyzed, should the returned table be a spatial sf object? Default is TRUE.

Value

A data frame with IBD coordinates of each IBD segment shared by any pair of nodes in the tree sequence

Details

The interface of this function is highly experimental. For full control over IBD segment detection in tree-sequence data, users can (and perhaps, for the time being, should) directly use the underlying tskit method ibd_segments (see https://tskit.dev/tskit/docs/stable/python-api.html#tskit.TreeSequence.ibd_segments).

Internally, this function leverages the tskit TreeSequence method ibd_segments. However, note that the ts_ibd function always returns a data frame of IBD tracts, it does not provide an option to iterate over individual IBD segments as shown in the official tskit documentation at https://tskit.dev/tskit/docs/stable/ibd.html. In general, R handles heavy iteration rather poorly and, as a result, this function does not attempt to serve as a full wrapper to ibd_segments.

Unfortunately, the distinction between "squashed IBD" (what many would consider to be the expected definition of IBD) and tskit’s IBD which is defined via distinct genealogical paths (see https://github.com/tskit-dev/tskit/issues/2459 for a discussion of the topic), makes the meaning of the filtering parameter of the ibd_segments() method of tskit minimum_length somewhat unintuitive. As of this moment, the minimum length argument filters on IBD segments on the "squashed" level, not the level of smaller individual IBD segments which the tskit machinery operates with. Again, for more details, refer to the resources linked above.

Examples