ibdTriangle: IBD triangle plot

In magnusdv/ribd: Pedigree-based Relatedness Coefficients

IBD triangle plot

Description

A relationship triangle used to used to visualize the kappa coefficients of between non-inbred individuals. Various annotations are available, including points marking the most common relationships, contour lines for the kinship coefficients, and shading of the unattainable region. The companion function showInTriangle() (which plots user-specified points onto the triangle) is probably the most useful for end users.

Usage

ibdTriangle(
  relationships = c("UN", "PO", "MZ", "S", "H,U,G", "FC"),
  plotType = c("base", "ggplot2", "plotly"),
  pch = 19,
  cexPoint = 1.2,
  cexText = 1.2,
  cexAxis = cexText,
  kinshipLines = numeric(),
  shortLines = FALSE,
  shading = "gray90",
  xlim = c(0, 1),
  ylim = c(0, 1),
  axes = FALSE,
  las = 1,
  xlab = expression(kappa[0]),
  ylab = expression(kappa[2]),
  title = NULL,
  mar = c(2.1, 2.1, 1, 1),
  xpd = TRUE,
  keep.par = TRUE,
  cexLab = NULL,
  ...
)

Arguments

relationships	A character vector indicating the fixed relationships points to be included in the plot. Valid entries are those in the label column of basicRelationships.
plotType	Either "base" (default), "ggplot2" or "plotly". Abbreviations are allowed.
pch	Symbol used for the relationship points (see par()).
cexPoint	A number controlling the symbol size for the relationship points.
cexText	A number controlling the font size for the relationship labels.
cexAxis	A number controlling the font size for the axis labels.
kinshipLines	A numeric vector (see Details).
shortLines	A logical indicating if the kinship lines (if present) should be restricted to the interior of the triangle.
shading	The shading colour for the unattainable region.
xlim, ylim, xpd, las	Graphical parameters; see par(). (Base plot only.)
axes	A logical: Draw surrounding axis box? Default: FALSE.
xlab, ylab	Axis labels.
title	Main title (absent by default).
mar	Graphical parameter; see par(). For ggplot2, this is ignored unless it is a ggplot2::margin() object.
keep.par	A logical. If TRUE, the graphical parameters are not reset after plotting, which may be useful for adding additional annotation. (Base plot only.)
cexLab	Deprecated; use cexAxis instead.
...	Further arguments; currently not used.

Details

For any pair of non-inbred individuals A and B, their genetic relationship can be summarized by the IBD coefficients (\kappa_0, \kappa_1, \kappa_2), where \kappa_i = P(A and B share i alleles IBD at random autosomal locus). Since \kappa_0 + \kappa_1 + \kappa_2 = 1, any relationship corresponds to a point in the triangle in the (\kappa_0, \kappa_2)-plane defined by \kappa_0 \ge 0, \kappa_2 \ge 0, \kappa_0 + \kappa_2 \le 1. The choice of \kappa_0 and \kappa_2 as the axis variables is done for reasons of symmetry and is not significant (other authors have used different views of the triangle).

As shown by Thompson (1976), points in the subset of the triangle defined by 4\kappa_0\kappa_2 > \kappa_1^2 are unattainable for pairwise relationships. By default this region in shaded in a light grey colour, but this can be modified with the shading argument.

The IBD coefficients are linearly related to the kinship coefficient \varphi by the formula \varphi = 0.25\kappa_1 + 0.5\kappa_2. By indicating values for \varphi in the kinshipLines argument, the corresponding contour lines are shown in the triangle plot. (Currently only when plotType = "base".)

Value

NULL if plotType = 'base'; otherwise the plot object.

References

• E. A. Thompson (1975). The estimation of pairwise relationships. Annals of Human Genetics 39.

• E. A. Thompson (1976). A restriction on the space of genetic relationships. Annals of Human Genetics 40.

See Also

showInTriangle(), kappaIBD()

Examples

opar = par(no.readonly = TRUE) # store graphical parameters

ibdTriangle()
ibdTriangle(kinshipLines = c(0.25, 0.125), shading = NULL, cexText = 0.7)
ibdTriangle(kinshipLines = c(0.25, 0.125), shortLines = TRUE, pch = 15)
ibdTriangle(relationships = c("UN", "PO", "MZ", "S"),
            xlab = "k0", ylab = "k2", las = 0, axes = TRUE, cexAxis =1.6)

par(opar) # reset graphical parameters

magnusdv/ribd documentation built on March 29, 2024, 5:20 a.m.