checkPairwise: Check pedigree data for relationship errors

In forrel: Forensic Pedigree Analysis and Relatedness Inference

Check pedigree data for relationship errors

Description

The checkPairwise() function provides a convenient way to check for pedigree errors, given the available marker data. The function calls ibdEstimate() to estimate IBD coefficients for all pairs of typed pedigree members, and uses the estimates to test for potential errors. By default, the results are shown in a colour-coded plot (based on ribd::ibdTriangle()) where unlikely relationships are easy to spot.

Usage

checkPairwise(
  x,
  ids = typedMembers(x),
  excludeInbred = TRUE,
  plotType = c("base", "ggplot2", "plotly", "none"),
  GLRthreshold = 1000,
  pvalThreshold = NULL,
  nsim = 0,
  seed = NULL,
  plot = TRUE,
  verbose = TRUE,
  ...
)

plotCP(
  cpRes,
  plotType = c("base", "ggplot2", "plotly"),
  labels = FALSE,
  errtxt = "Potential error",
  seed = NULL,
  ...
)

Arguments

x	A ped object or a list of such.
ids	A vector of ID labels; the individuals to include in the check. Default: All typed members of x.
excludeInbred	A logical, by default TRUE, indicating if inbred individuals should be excluded from the analysis.
plotType	Either "base" (default), "ggplot2", "plotly" or "none". Abbreviations are allowed.
GLRthreshold	A positive number, by default 1000. Threshold for the generalised likelihood ratio (see Details). Scores exceeding this are flagged as potential errors in the output table and encircled in the plot.
pvalThreshold	A positive number, or NULL (default). If given, this is used instead of GLRthreshold to identify potential errors. Ignored if nsim = 0.
nsim	A nonnegative number; the number of simulations used to estimate p-values. If 0 (default), this step is skipped.
seed	An integer seed for the random number generator (optional, and only relevant if nsim > 0).
plot	Deprecated. To suppress the triangle plot, use plotType = "none"
verbose	A logical.
...	Further parameters passed on to ribd::ibdTriangle().
cpRes	A data frame: the output from checkPairwise().
labels	A logical (default: FALSE). If TRUE, labels are included in the IBD triangle plot.
errtxt	A character string to use for the error legend.

Details

To identify potential pedigree errors, the function calculates the generalised likelihood ratio (GLR) of each pairwise relationship. This compares the likelihood of the estimated coefficients with that of the coefficients implied by the pedigree. By default, relationships whose GLR exceed 1000 are flagged as errors and shown with a circle in the plot. Alternatively, if arguments nsim and pvalThreshold are supplied, the p-value of each score is estimated by simulation, and used as threshold for calling errors.

By default, inbred individuals are excluded from the analysis, since pairwise relationships involving inbred individuals have undefined kappa coefficients (and therefore no position in the triangle). In some cases it may still be informative to include their estimates; set excludeInbred = FALSE to enforce this.

Value

If plotType is "none" or "base": A data frame containing both the estimated and pedigree-based IBD coefficients for each pair of typed individuals. The last columns (GLR, pval and err) contain test results using the GLR scores to identify potential pedigree errors.

If plotType is "ggplot2" or "plotly", the plot objects are returned.

See Also

ibdEstimate()

Examples

### Example with realistic data

x = avuncularPed() |>
  profileSim(markers = NorwegianFrequencies, seed = 1729)

checkPairwise(x)

### Create an error: sample swap 1 <-> 3
als = getAlleles(x)
als[c(1,3), ] = als[c(3,1), ]
y = setAlleles(x, alleles = als)

checkPairwise(y)

# Using p-values instead of GLR
nsim = 10 # increase!
checkPairwise(y, nsim = nsim, pvalThreshold = 0.05)

# Plot can be done separately
res = checkPairwise(y, nsim = nsim, pvalThreshold = 0.05, plotType = "none")
plotCP(res, plotType = "base", errtxt = "Not good!")


# Combined plot of pedigree and check results
dev.new(height = 5, width = 8, noRStudioGD = TRUE)
layout(rbind(1:2), widths = 2:3)
plot(y, margins = 2, title = "Swapped 1 - 3")
plotCP(res, labels = TRUE)

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