likelihood: Pedigree likelihood
In pedprobr: Probability Computations on Pedigrees

View source: R/likelihood.R

likelihood

R Documentation

Pedigree likelihood

Description

The likelihood() and likelihood2() functions constitute the heart of pedprobr. The former computes the pedigree likelihood for each indicated marker. The latter computes the likelihood for a pair of linked markers separated by a given recombination rate.

Usage

likelihood(x, ...)

## S3 method for class 'ped'
likelihood(
  x,
  markers = NULL,
  peelOrder = NULL,
  lump = TRUE,
  special = FALSE,
  alleleLimit = Inf,
  logbase = NULL,
  loopBreakers = NULL,
  allX = NULL,
  verbose = FALSE,
  theta = 0,
  ...
)

## S3 method for class 'list'
likelihood(x, markers = NULL, logbase = NULL, ...)

likelihood2(x, ...)

## S3 method for class 'ped'
likelihood2(
  x,
  marker1,
  marker2,
  rho = NULL,
  peelOrder = NULL,
  lump = TRUE,
  special = TRUE,
  alleleLimit = Inf,
  logbase = NULL,
  loopBreakers = NULL,
  verbose = FALSE,
  ...
)

## S3 method for class 'list'
likelihood2(x, marker1, marker2, logbase = NULL, ...)

Arguments

`x`	A `ped` object, a `singleton` object, or a list of such objects.
`...`	Further arguments.
`markers`	One or several markers compatible with `x`. Several input forms are possible: A `marker` object compatible with `x`. A list of `marker` objects. A vector of names or indices of markers attached to `x`. If `x` is a list, this is the only valid input.
`peelOrder`	For internal use.
`lump`	Activate allele lumping, i.e., merging unobserved alleles. This is an important time saver, and should be applied in nearly all cases. (The parameter exists mainly for debugging purposes.) If any markers use a non-lumpable mutation model, the `special` argument may be used to apply more advanced methods.
`special`	A logical indicating if special lumping procedures should be attempted if the mutation model is not generally lumpable. By default FALSE in `likelihood()` and TRUE in `likelihood2()`.
`alleleLimit`	A positive number or `Inf` (default). If the mutation model is not generally lumpable, and the allele count exceeds this limit, switch to an `equal` model with the same rate and reapply lumping.
`logbase`	Either NULL (default) or a positive number indicating the basis for logarithmic output. Typical values are `exp(1)` and 10.
`loopBreakers`	A vector of ID labels indicating loop breakers. If NULL (default), automatic selection of loop breakers will be performed. See `pedtools::breakLoops()`.
`allX`	For internal use; set to TRUE if all markers are X-chromosomal.
`verbose`	A logical.
`theta`	Theta correction.
`marker1`, `marker2`	Single markers compatible with `x`.
`rho`	The recombination rate between `marker1` and `marker2`. To make biological sense `rho` should be between 0 and 0.5.

Details

The implementation is based on the peeling algorithm of Elston and Stewart (1971). A variety of situations are covered; see the Examples section for some demonstrations.

autosomal and X-linked markers
complex inbred pedigrees
markers with mutation models
pedigrees with inbred founders
single markers or two linked markers

For more than two linked markers, see likelihoodMerlin().

Allele lumping can significantly reduce computation time with highly polymorphic STR markers and many untyped pedigree members. This is particularly important in likelihood2() which is prone to run out of memory without lumping. If a non-lumpable mutation model is used, specialised lumping may still be possible in some situations. This is attempted if special = TRUE, which is the default in likelihood2() but not in likelihood().

Value

A numeric with the same length as the number of markers indicated by markers. If logbase is a positive number, the output is log(likelihood, logbase).

Author(s)

Magnus Dehli Vigeland

References

Elston and Stewart (1971). A General Model for the Genetic Analysis of Pedigree Data. \Sexpr[results=rd]{tools:::Rd_expr_doi("https://doi.org/10.1159/000152448")}

Examples


### Simple likelihoods ###
p = 0.1
q = 1 - p
afr = c("1" = p, "2" = q)

# Singleton
s = singleton() |> addMarker(geno = "1/2", afreq = afr)
stopifnot(all.equal(likelihood(s), 2*p*q))

# Trio
x = nuclearPed() |> addMarker(geno = c("1/1", "1/2", "1/1"), afreq = afr)
lik = likelihood(x, verbose = TRUE)
stopifnot(all.equal(lik, p^2 * 2*p*q * 0.5))


### Example with inbred founder ###

# Set 100% inbreeding for the father in the previous example
y = setFounderInbreeding(x, ids = 1, value = 1)

# Plot (notice the inbreeding coefficient)
plot(y, marker = 1)

stopifnot(all.equal(likelihood(y), p * 2*p*q * 0.5))


### Example with two linked markers

# Add a second marker, highly polymorphic
x = addMarker(x, geno = c(NA, NA, "1/1"), alleles = 1:10)

# Likelihood assuming complete linkage
likelihood2(x, 1, 2, rho = 0, verbose = TRUE)

pedprobr documentation built on June 8, 2025, 10:56 a.m.