In magnusdv/ribd: Pedigree-based Relatedness Coefficients

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  fig.align = "center",
  dpi = 300
)

ribd

Overview

The goal of ribd is to compute various coefficients of relatedness and identity-by-descent (IBD) between pedigree members. It is part of the pedsuite collection of R packages for pedigree analysis; see https://magnusdv.github.io/pedsuite/ for details.

The main functions in ribd are the following, all of which support both autosomal and X-chromosomal modes, and pedigrees with inbred founders:

• kinship(): The kinship coefficient $\varphi$ between two pedigree members (or full matrix)
• inbreeding(): The inbreeding coefficient $f$ of all (or a subset of) pedigree members
• kappaIBD(): IBD coefficients $\kappa_0, \kappa_1, \kappa_2$ between noninbred individuals
• identityCoefs(): Jacquard's condensed identity coefficients $\Delta_1, \dotsc, \Delta_9$

The package also computes a variety of lesser-known pedigree coefficients:

• gKinship(): Generalised kinship coefficients of various kinds, including those defined by Karigl (1981), Weeks & Lange (1988), Lange & Sinsheimer (1992) and García-Cortés (2015).
• multiPersonIBD(): Multi-person IBD coefficients (noninbred individuals only)
• twoLocusKinship(): Two-locus kinship coefficients, as defined by Thompson (1988)
• twoLocusIBD(): Two-locus IBD coefficients (noninbred pair of individuals)
• twoLocusIdentity(): Two-locus condensed identity coefficients (any pair of individuals)
• twoLocusGeneralisedKinship(): Generalised two-locus kinship coefficients (not exported)

Citation

If you use ribd in a publication, please cite the most appropriate of the following works.

Standard coefficients
Magnus D. Vigeland. Relatedness coefficients in pedigrees with inbred founders. Journal of Mathematical Biology, 2020. doi:10.1007/s00285-020-01505-x.

Two-locus coefficients
Magnus D. Vigeland. Two-locus identity coefficients in pedigrees. G3 Genes|Genomes|Genetics, 2023. doi:10.1093/g3journal/jkac326.

General reference
Magnus D. Vigeland. Pedigree analysis in R. Academic Press, 2021. ISBN:9780128245606.

Installation

The easiest way to get started with ribd is to install the pedsuite:

install.packages("pedsuite")

If you only want ribd, install from CRAN as follows:

install.packages("ribd")

Alternatively, the latest development version is available from GitHub:

# install.packages("devtools") # install devtools if needed
devtools::install_github("magnusdv/ribd")

Getting started

In the following we illustrate the use of ribd by computing a few well-known examples. We start by loading the package.

library(ribd)

Inbreeding: A child of first cousins

For a child of related parents, its inbreeding coefficient is defined as the probability of autozygosity (i.e., homologous alleles being IBD) in a random autosomal locus.

plot(cousinPed(1, child = TRUE), hatched = 9, align = c(0,0))

For example, the child of first cousins shown above has inbreeding coefficient 1/16. We can compute this with ribd as follows:

# Create pedigree
x = cousinPed(1, child = TRUE)
plot(x, hatched = 9)

# Inbreeding coefficient of the child
inbreeding(x, ids = 9)

Kinship coefficient

By definition, the inbreeding coefficient equals the kinship coefficient of the parents, individuals 7 and 8:

kinship(x, ids = 7:8)

As expected, the result was again 1/16.

Kappa coefficients and the IBD triangle

For a pair of noninbred individuals, the three kappa coefficients are defined as the probability that they have exactly 0, 1 or 2 alleles IBD, respectively, at a random autosomal locus. For example, for a pair of full siblings, this works out to be 1/4, 1/2 and 1/4, respectively.

Since the three kappa's always sum to 1, any two of them are sufficient, forming the coordinates of a point in the plane. This gives rise to the IBD triangle, which is a useful tools for visualising (noninbred) relationships. The implementation in ribd uses kappa0 on the first axis and kappa2 on the second. In the example below, we place all pairs of pedigree members in the triangle.

We validate this with the kappaIBD() function of ribd:

layout(rbind(1:2), widths = 2:3)
# Create and plot pedigree
y = nuclearPed(2)
plot(y, margin = 4)

# Compute kappa for all pairs
k = kappaIBD(y)

# IBD triangle
showInTriangle(k, labels = T, pos = c(3,2,3,4,4,3))

(If you have ggplot2 and ggrepel installed, try showInTriangle(k, plotType = "gg") for automatic separation of the labels. There is also an interactive version, available with showInTriangle(k, plotType = "plotly").)

As shown by Thompson (1976), all relationships of noninbred individuals satisfy a certain quadratic inequality in the kappa's, resulting in an unattainable region of the triangle (shown in grey above).

A more complex example

Here is a relationship in the interior of the attainable region of the IBD triangle:

layout(rbind(1:2), widths = c(2:3))
z = halfSibStack(2)
plot(z, hatched = 7:8, margin = c(3,2,2,2))

kap = kappaIBD(z, ids = 7:8)
showInTriangle(kap)

The pairwise condensed identity states

The following figure shows the 9 condensed identity states of two individuals a and b. Each state shows a pattern of identity by descent (IBD) between the four homologous alleles. The four alleles are represented as dots, with a connecting line segment indicating IBD. The states are shown in the ordering used by Jacquard and most subsequent authors.

knitr::include_graphics("man/figures/jacquardStates.png")

Example: Full sib mating

The following relationship is perhaps the simplest example where all 9 coefficients are nonzero.

x = fullSibMating(1)
plot(x, hatched = 5:6)

The function identityCoefs() by default returns the nine coefficients in the order given above.

identityCoefs(x, ids = 5:6)

Identity states on X

The X-chromosomal version of Jacquard's identity coefficients can be computed by adding Xchrom = TRUE in the call to identityCoefs(). Here is the output for all pairs in the above pedigree:

identityCoefs(x, Xchrom = TRUE)

A precise definition of these X-chromosomal coefficients requires some explanation, which we give here.

As in the autosomal case, the identity coefficients on X are the expected proportions of the possible IBD states involving the alleles at a random locus (on X). The challenge is that the set of states depends on the individual's sex: F/F, F/M, M/F or M/M (were F = female and M = male). The easiest case is F/F: When both are female, the states are just as in the autosomal case.

Males, being hemizygous, have only 1 allele of a locus on X. Hence when males are involved the total number of alleles is less than 4, rendering the autosomal states pictured above meaningless. However, to avoid drawing (and learning the ordering of) new states for each sex combination, we can re-use the autosomal state pictograms by invoking the following simple rule: Replace the single allele of any male, with a pair of autozygous alleles. This gives a one-to-one map from the X states to the autosomal states.

For simplicity the output always contains 9 coefficients, but with NA's in the positions of undefined states (depending on the sex combination). Hopefully this should all be clear from the following table:

knitr::include_graphics("man/figures/jacquardStatesX.png")

Pedigrees with inbred founders

A unique feature of ribd (in fact, throughout the pedsuite packages) is the support for inbred founders. This greatly expands the set of pedigrees we can analyse with a computer.

Example

Here is a fun example using inbred founders: A relationship exactly midway (at least arithmetically speaking) between parent-child and full siblings. To achieve this, we modify the pedigree z from above (half-sibs/half-cousins), giving two of the founders carefully chosen inbreeding coefficients.

founderInbreeding(z, id = 3) = 3 - 2*sqrt(2)
founderInbreeding(z, id = 6) = 0.5 * sqrt(2)

Note that founder inbreeding is by default included in the pedigree plot:

# Plot pedigree
plot(z, hatched = 7:8, labs = 7:8)

# IBD triangle
showInTriangle(kappaIBD(z, 7:8))

layout(rbind(1:2), widths = c(2:3))
plot(z, hatched = leaves, margins = 2.5, labs = 7:8)
showInTriangle(kappaIBD(z, 7:8), label = " (1/8, 1/8)", 
               cexLab = 1.1, pos = 4, mar = c(2.5, 3.1, .5, 1))

If you wonder how the weird-looking inbreeding coefficients above were chosen, you can check out my paper Relatedness coefficients in pedigrees with inbred founders (J Math Biol, 2020). In it I show that any point in the white region (including its boundary) of the IBD triangle can be constructed as a double half cousin relationship with suitable founder inbreeding.

The construction described in the paper is implemented in the function constructPedigree() in ribd. For example, the following command produces basically the pedigree in the previous figure:

w = constructPedigree(kappa = c(1/8, 6/8, 1/8))

magnusdv/ribd documentation built on March 29, 2024, 5:20 a.m.