LRpower: Power simulation for kinship LR

In forrel: Forensic Pedigree Analysis and Relatedness Inference

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
ids = c("A", "B")
truth = nuclearPed(children = ids)
claim = nuclearPed(fa = "A", mo = "NN", children = "B")
unrel = singletons(ids)

# Simulation parameters
nsim = 10   # increase!
thresh = 1

# 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))


# True pedigree has inbred founders
truth2 = setFounderInbreeding(truth, value = 0.5)

pow3 = LRpower(claim, unrel, truth2, ids = ids, nsim = nsim,
               threshold = thresh, markers = 1, seed = 123) # plot = TRUE
pow3

forrel documentation built on Sept. 11, 2024, 9:15 p.m.