LRpower {forrel}

Power simulation for kinship LR

Description

This function uses simulations to estimate the likelihood ratio (LR) distribution in a given kinship testing scenario. In the most general setting, three pedigrees are involved: the two pedigrees being compared, and the true relationship (which may differ from the other two). A subset of individuals are available for genotyping. Some individuals may already be genotyped; all simulations are then conditional on these.

Usage

LRpower(
  numeratorPed,
  denominatorPed,
  truePed = numeratorPed,
  ids,
  markers = NULL,
  source = "true",
  nsim = 1,
  threshold = NULL,
  disableMutations = NA,
  alleles = NULL,
  afreq = NULL,
  Xchrom = FALSE,
  knownGenotypes = NULL,
  plot = FALSE,
  plotMarkers = NULL,
  seed = NULL,
  verbose = TRUE
)

Arguments

numeratorPed, denominatorPed

ped objects (or lists of such), describing the two relationships under comparison.

truePed

A ped object (or a list of such), describing the true relationship. By default equal to numeratorPed.

ids

Individuals available for genotyping.

markers

A vector indicating the names or indices of markers attached to the source pedigree. If NULL (default), then all markers attached to the source pedigree are used. If alleles or afreq is non-NULL, then this parameter is ignored.

source

Either "true" (default), "numerator" or "denominator", indicating which pedigree is used as source for marker data.

nsim

A positive integer: the number of simulations.

threshold

A numeric vector with one or more positive numbers used as LR thresholds.

disableMutations

Not implemented yet.

alleles, afreq, Xchrom

If these are given, they are used (together with knownGenotypes) to create a marker object on the fly.

knownGenotypes

A list of triplets ⁠(a, b, c)⁠, indicating that individual a has genotype b/c. Ignored unless alleles or afreq is non-NULL.

plot

Either a logical or the character "plotOnly". If the latter, a plot is drawn, but no further computations are done.

plotMarkers

A vector of marker names or indices whose genotypes are to be included in the plot.

seed

An integer seed for the random number generator (optional).

verbose

A logical.

Value

A LRpowerResult object, which is essentially a list with the following entries:

• LRperSim: A numeric vector of length nsim containing the total LR for each simulation.

• meanLRperMarker: The mean LR per marker, over all simulations.

• meanLR: The mean total LR over all simulations.

• meanLogLR: The mean total log10(LR) over all simulations.

• IP: A named numeric of the same length as threshold. For each element of threshold, the fraction of simulations resulting in a LR exceeding the given number.

• time: The total computation time.

• params: A list containing the input parameters missing, markers, nsim, threshold and disableMutations

Examples

# Paternity LR of siblings
claim = nuclearPed(fa = "A", mo = "NN", children = "B")
unrel = list(singleton("A"), singleton("B"))
truth = nuclearPed(children = c("A", "B"))

# Simulation parameters
nsim = 10   # increase!
thresh = 1
ids = c("A", "B")

# Simulation 1:
als = 1:5
afr = runif(5)
afr = afr/sum(afr)

pow1 = LRpower(claim, unrel, truth, ids = ids, nsim = nsim,
               threshold = thresh, alleles = als, afreq = afr,
               seed = 123)
pow1

# Simulation 2: Same, but using an attached marker
truth = addMarker(truth, alleles = als, afreq = afr)

pow2 = LRpower(claim, unrel, truth, ids = ids, nsim = nsim,
               threshold = thresh, markers = 1, seed = 123)

stopifnot(identical(pow1$LRperSim, pow2$LRperSim))


# Founder inbreeding in true pedigree
founderInbreeding(truth, founders(truth)) = 0.5
truth
pow3 = LRpower(claim, unrel, truth, ids = ids, nsim = nsim,
               threshold = thresh, markers = 1, seed = 123) # plot = TRUE
pow3