likelihood: Pedigree likelihood

View source: R/likelihood.R

likelihoodR 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")}

See Also

likelihoodMerlin(), for likelihoods involving more than 2 linked markers.

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.