ibdEstimate: Pairwise relatedness estimation

In forrel: Forensic Pedigree Analysis and Relatedness Inference

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. Estimates of \kappa may be visualised with showInTriangle().

Usage

ibdEstimate(
  x,
  ids = typedMembers(x),
  param = c("kappa", "delta"),
  acrossComps = TRUE,
  markers = NULL,
  start = NULL,
  tol = sqrt(.Machine$double.eps),
  beta = 0.5,
  sigma = 0.5,
  contourPlot = FALSE,
  levels = NULL,
  maxval = FALSE,
  verbose = TRUE
)

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, each row indicating a pair of individuals. The entries are coerced to characters, and must match uniquely against the ID labels of x. By default, all pairs of genotyped members of x are included.
param	Either "kappa" (default) or "delta"; indicating which set of coefficients should be estimated.
acrossComps	A logical indicating if pairs of individuals in different components should be included. Default: TRUE.
markers	A vector with names or indices of markers attached to x, indicating which markers to include. By default, all markers are used.
start	A probability vector (i.e., with nonnegative entries and sum 1) of length 3 (if param = "kappa") or 9 (if param = "delta"), indicating the initial value of for the optimisation. By default, start is set to ⁠(1/3, 1/3, 1/3)⁠ if param = "kappa" and ⁠(1/9, ..., 1/9)⁠ if param = "delta".
tol, beta, sigma	Control parameters for the optimisation routine; can usually be left untouched.
contourPlot	A logical. If TRUE, contours of the log-likelihood function are plotted overlaying the IBD triangle.
levels	(Only relevant if contourPlot = TRUE.) A numeric vector of levels at which to draw contour lines. If NULL (default), the levels are chosen automatically.
maxval	A logical. If TRUE, the maximum log-likelihood value is included in the output. Default: FALSE
verbose	A logical.

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 optimises the log-likelihood using a projected gradient descent algorithm, combined with a version of Armijo line search.

When param = "kappa", the output may be fed directly to showInTriangle() for visualisation.

Value

An object of class ibdEst, which is basically a data frame with either 6 columns (if param = "kappa") or 12 columns (if param = "delta"). The first three columns are id1 (label of first individual), id2 (label of second individual) and N (the number of markers with no missing alleles). The remaining columns contain the coefficient estimates. If maxval = T, a column named maxloglik is added at the end.

Author(s)

Magnus Dehli Vigeland

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

ibdBootstrap()

Examples

### Example 1: Siblings

# Create pedigree and simulate 100 markers
x = nuclearPed(2) |> markerSim(N = 100, alleles = 1:4, seed = 123)
x

# Estimate kappa (expectation: (0.25, 0.5, 0.25)
k = ibdEstimate(x, ids = 3:4)
k

# Visualise estimate
showInTriangle(k, labels = TRUE)

# Contour plot of the log-likelihood function
ibdEstimate(x, ids = 3:4, contourPlot = TRUE)


### Example 2: Full sib mating
y = fullSibMating(1) |>
  markerSim(ids = 5:6, N = 1000, alleles = 1:10, seed = 123)

# Estimate the condensed identity coefficients
ibdEstimate(y, param = "delta")

# Exact coefficient by `ribd`:
ribd::condensedIdentity(y, 5:6, simplify = FALSE)

forrel documentation built on June 8, 2025, 10:15 a.m.