kappaIBD: IBD (kappa) coefficients

Description

Computes the three IBD coefficients summarising the relationship between two non-inbred individuals. Both autosomal and X chromosomal versions are implemented. The pedigree founders (other than the individuals in question) are allowed to be inbred; see pedtools::founderInbreeding() for how to set this up, and see Examples below.

Usage

kappaIBD(
  x,
  ids = labels(x),
  inbredAction = 1,
  simplify = TRUE,
  acrossComps = TRUE,
  Xchrom = FALSE
)

Value

If ids has length 2 and simplify = TRUE: A numeric vector of length 3: $(\kappa_0, \kappa_1, \kappa_2)$.

Otherwise: A data frame with one row for each pair of individuals, and 5 columns. The first two columns contain the ID labels, and columns 3-5 contain the IBD coefficients.

Kappa coefficients of inbred individuals (meaning X-inbred females if Xchrom = T) are reported as NA, unless inbredAction = 2.

The X-chromosomal $\kappa_2$ is NA whenever at least one of the two individuals is male.

Arguments

x: A pedigree in the form of a ped object (or a list of such).
ids: A character (or coercible to character) containing ID labels of two or more pedigree members.
inbredAction: An integer telling the program what to do if either of the ids individuals are inbred. Possible values are: 0 = do nothing; 1 = print a warning message (default); 2 = raise an error. In the first two cases the coefficients are reported as NA.
simplify: Simplify the output (to a numeric of length 3) if ids has length 2. Default: TRUE.
acrossComps: A logical indicating if pairs of individuals in different components should be included. Default: TRUE.
Xchrom: A logical, indicating if the autosomal (default) or X-chromosomal kappa coefficients should be computed.

Details

For non-inbred individuals a and b, their autosomal IBD coefficients $(\kappa_0, \kappa_1, \kappa_2)$ are defined as follows: $$\kappa_i = P(\text{a and b share exactly i alleles IBD at a random autosomal locus})$$

The autosomal kappa coefficients are computed from the kinship coefficients. When a and b are both nonfounders, the following formulas hold:

$\kappa_2 = \varphi_{MM} \cdot \varphi_{FF} + \varphi_{MF} \cdot\varphi_{FM}$
$\kappa_1 = 4 \varphi_{ab} - 2 \kappa_2$
$\kappa_0 = 1 - \kappa_1 - \kappa_2$

Here $\varphi_{MF}$ denotes the kinship coefficient between the mother of a and the father of b, etc. If either a or b is a founder, then $\kappa_2 = 0$, while the other two formulas remain as before.

The X-chromosomal IBD coefficients are defined similarly to the autosomal case. Here $\kappa_2$ is undefined when one or both individuals are male, which greatly simplifies the calculations when males are involved. The formulas are (with $\varphi_{ab}$ now referring to the X-chromosomal kinship coefficient):

Both male: $(\kappa_0, \kappa_1, \kappa_2) = (1-\varphi_{ab}, \varphi_{ab}, \text{NA})$
One male, one female: $(\kappa_0, \kappa_1, \kappa_2) = (1-2 \varphi_{ab}, 2 \varphi_{ab}, \text{NA})$
Two females: Similar formulas as in the autosomal case.

Examples

Run this code

### Siblings
x = nuclearPed(2)
kappaIBD(x)

k = kappaIBD(x, 3:4)
stopifnot(identical(k, c(.25, .5, .25)))

### Quad half first cousins
x = quadHalfFirstCousins()
k = kappaIBD(x, ids = leaves(x))
stopifnot(identical(k, c(17/32, 14/32, 1/32)))

### Paternal half brothers with 100% inbred father
# Genetically indistinguishable from an (outbred) father-son relationship
x = halfSibPed() |> setFounderInbreeding(ids = 2, value = 1)
plot(x, hatched = 4:5)

k = kappaIBD(x, 4:5)
stopifnot(identical(k, c(0, 1, 0)))

### X-chromosomal kappa
y = nuclearPed(2, sex = 2)
kappaIBD(y, Xchrom = TRUE)