ibdsim2 (version 2.2.0)

estimateCoeffs: Estimation of one- and two-locus relatedness coefficients

Description

Estimate by simulation various relatedness coefficients, and two-locus versions of the same coefficients, for a given recombination rate. The current implementation covers inbreeding coefficients, kinship coefficients, IBD (kappa) coefficients between noninbred individuals, and condensed identity coefficients. These functions are primarily meant as tools for validating exact algorithms, e.g., as implemented in the ribd package.

Usage

estimateInbreeding(x, id, Nsim, Xchrom = FALSE, verbose = FALSE, ...)
estimateTwoLocusInbreeding(
  x,
  id,
  rho = NULL,
  cM = NULL,
  Nsim,
  Xchrom = FALSE,
  verbose = FALSE,
  ...
)
estimateKinship(x, ids, Nsim, Xchrom = FALSE, verbose = FALSE, ...)
estimateTwoLocusKinship(
  x,
  ids,
  rho = NULL,
  cM = NULL,
  Nsim,
  Xchrom = FALSE,
  verbose = FALSE,
  ...
)
estimateKappa(x, ids, Nsim, Xchrom = FALSE, verbose = FALSE, ...)
estimateTwoLocusKappa(
  x,
  ids,
  rho = NULL,
  cM = NULL,
  Nsim,
  Xchrom = FALSE,
  verbose = FALSE,
  ...
)
estimateIdentity(x, ids, Nsim, Xchrom = FALSE, verbose = FALSE, ...)
estimateTwoLocusIdentity(
  x,
  ids,
  rho = NULL,
  cM = NULL,
  Nsim,
  Xchrom = FALSE,
  verbose = FALSE,
  ...
)

Value

estimateInbreeding(): a single probability.

estimateTwoLocusInbreeding(): a single probability.

estimateKappa(): a numeric vector of length 3, with the estimated \(\kappa\) coefficients.

estimateTwoLocusKappa(): a symmetric, numerical 3*3 matrix, with the estimated values of \(\kappa_{ij}\), for \(i,j = 0,1,2\).

estimateIdentity(): a numeric vector of length 9, with the estimated identity coefficients.

estimateTwoLocusIdentity(): a symmetric, numerical 9*9 matrix, with the estimated values of \(\Delta_{ij}\), for \(i,j = 1,...,9\).

Arguments

x

A pedigree in the form of a pedtools::ped() object.

id, ids

A vector of one or two ID labels.

Nsim

The number of simulations.

Xchrom

A logical indicating if the loci are X-linked or autosomal.

verbose

A logical.

...

Further arguments passed on to ibdsim(), e.g. seed.

rho

A scalar in the interval [0, 0.5]: the recombination fraction between the two loci, converted to centiMorgans using Haldane's map function: cM = -50 * log(1 - 2 * rho). Either rho or cM (but not both) must be non-NULL.

cM

A non-negative number: the genetic distance between the two loci, given in centiMorgans. Either rho or cM (but not both) must be non-NULL.

Details

In the following, let L1 and L2 denote two arbitrary autosomal loci with recombination rate \(\rho\), and let A and B be members of the pedigree x.

The two-locus inbreeding coefficient \(f_2(\rho)\) of A is defined as the probability that A is autozygous at both L1 and L2 simultaneously.

The two-locus kinship coefficient \(\phi_2(\rho)\) of A and B is defined as the probability that a random gamete emitted from A, and a random gamete emitted from B, contain IBD alleles at both L1 and L2.

The two-locus kappa coefficient \(\kappa_{ij}(\rho)\), for \(i,j = 0,1,2\), of noninbred A and B, is the probability that A and B share exactly i alleles IBD at L1, and exactly j alleles IBD at L2.

The two-locus identity coefficient \(\Delta_{ij}\), \(i,j = 1,...,9\) is defined for any (possibly inbred) A and B, as the probability that A and B are in identity state i at L1, and state j at L2. This uses the conventional ordering of the nine condensed identity states. For details, see for instance the GitHub page of the ribd package.

Examples

############################
### Two-locus inbreeding ###
############################

x = cousinPed(0, child = TRUE)
rho = 0.25
Nsim = 10 # Increase!
estimateTwoLocusInbreeding(x, id = 5, rho = rho, Nsim = Nsim, seed = 123)

# Exact:
ribd::twoLocusInbreeding(x, id = 5, rho = rho)

########################################
### Two-locus kappa:                 ###
### Grandparent vs half sib vs uncle ###
########################################

# These are indistinguishable with unlinked loci, see e.g.
# pages 182-183 in Egeland, Kling and Mostad (2016).
# In the following, each simulation approximation is followed
# by its exact counterpart.

rho = 0.25; R = .5 * (rho^2 + (1-rho)^2)
Nsim = 10 # Should be increased to at least 10000

# Grandparent/grandchild
G = linearPed(2); G.ids = c(1,5); # plot(G, hatched = G.ids)
estimateTwoLocusKappa(G, G.ids, rho = rho, Nsim = Nsim, seed = 123)[2,2]
.5*(1-rho) # exact

# Half sibs
H = halfSibPed(); H.ids = c(4,5); # plot(H, hatched = H.ids)
estimateTwoLocusKappa(H, H.ids, rho = rho, Nsim = Nsim, seed = 123)[2,2]
R # exact

# Uncle
U = avuncularPed(); U.ids = c(3,6); # plot(U, hatched = U.ids)
estimateTwoLocusKappa(U, U.ids, rho = rho, Nsim = Nsim, seed = 123)[2,2]
(1-rho) * R + rho/4 # exact

# Exact calculations by ribd:
# ribd::twoLocusIBD(G, G.ids, rho = rho, coefs = "k11")
# ribd::twoLocusIBD(H, H.ids, rho = rho, coefs = "k11")
# ribd::twoLocusIBD(U, U.ids, rho = rho, coefs = "k11")

##########################
### Two-locus Jacquard ###
##########################

x = fullSibMating(1)
rho = 0.25
Nsim = 10 # (increase to at least 10000)

estimateTwoLocusIdentity(x, ids = 5:6, rho = rho, Nsim = Nsim, seed = 123)

# Exact by ribd:
# ribd::twoLocusIdentity(x, ids = 5:6, rho = rho)