forrel (version 1.2.0)

ibdEstim: Pairwise relatedness estimation

Description

Estimate the IBD coefficients \(\kappa = (\kappa_0, \kappa_1, \kappa_2)\) or the condensed identity coefficients \(\Delta = (\Delta_1, ..., \Delta_9)\) between a pair (or several pairs) of pedigree members, using maximum likelihood methods.

Usage

ibdEstim(
  x,
  ids = typedMembers(x),
  param = c("kappa", "delta"),
  markers = NULL,
  start = NULL,
  reltol = 1e-12,
  returnArgs = FALSE,
  ...
)

Arguments

x

A ped object or a list of such.

ids

Either a vector with ID labels, or a data frame/matrix with two columns, where each row contains the ID labels of two individuals. The entries are coerced to characters, and must match uniquely against the ID labels of x. By default, all pairs of members of x are included.

param

Either "kappa" (default) or "delta"; indicating which set of coefficients should be estimated.

markers

A vector with names or indices of markers attached to x, indicating which markers to include. If NULL (default), all markers are used.

start

Numeric of length 3 (if param = "kappa") or 9 (if param = "delta"), indicating an initial value of for the optimisation.

reltol

Relative convergence tolerance; passed on to constrOptim(). Defaults to 1e-12,

returnArgs

A logical; for debugging purposes.

...

Further arguments.

Value

If param = "kappa": A data frame with 6 columns: id1, id2, N (the number of markers with no missing alleles), k0, k1 and k2.

If param = "delta": A data frame with 12 columns: id1, id2, N (the number of markers with no missing alleles), d1, d2, ... d9.

Details

It should be noted that this procedure estimates the realised identity coefficients of each pair, i.e., the actual fractions of the autosomes in each IBD state. These may deviate substantially from the theoretical pedigree coefficients.

Maximum likelihood estimation of relatedness coefficients originates with Thompson (1975). Optimisation of \(\kappa\) is done in the \((\kappa_0, \kappa_2)\)-plane and restricted to the triangle defined by $$\kappa_0 \ge 0, \kappa_2 \ge 0, \kappa_0 + \kappa_2 \le 1$$. Optimisation of \(\Delta\) is done in unit simplex of R^8, using the first 8 coefficients.

The implementation uses constrOptim(), with the "BFGS" method.

References

• E. A. Thompson (1975). The estimation of pairwise relationships. Annals of Human Genetics 39.

• E. A. Thompson (2000). Statistical Inference from Genetic Data on Pedigrees. NSF-CBMS Regional Conference Series in Probability and Statistics. Volume 6.

See Also

constrOptim()

Examples

# NOT RUN {
### Example 1: Siblings
x = nuclearPed(2)

# Simulate 100 markers
x = markerSim(x, N = 100, alleles = 1:4, seed = 123, verbose = FALSE)

# Estimate Delta (expectation = (0,0,0,0,0,0,1/4,1/2,1/4))
ibdEstim(x, ids = 3:4)


### Example 2: Full sib mating
y = fullSibMating(1)

# Simulate 200 SNP markers
y = markerSim(y, N = 1000, alleles = 1:10, seed = 123, verbose = FALSE)

# Estimate
ibdEstim(y, ids = 5:6, param = "delta")


# }