Repository files navigation

The goal ofribd is to compute various coefficients of relatednessand identity-by-descent (IBD) between pedigree members. It is part ofthepedsuite collection of R packages for pedigree analysis; seehttps://magnusdv.github.io/pedsuite/ for details.

The main functions inribd are the following, all of which supportboth autosomal and X-chromosomal modes, and pedigrees with inbredfounders:

• kinship(): The kinship coefficient$\varphi$ between two pedigreemembers (or full matrix)
• inbreeding(): The inbreeding coefficient$f$ of all (or a subset of)pedigree members
• kappaIBD(): IBD coefficients$\kappa_0, \kappa_1, \kappa_2$ betweennoninbred individuals
• identityCoefs(): Jacquard’s condensed identity coefficients$\Delta_1, \dotsc, \Delta_9$

The package also computes a variety of lesser-known pedigreecoefficients:

• gKinship(): Generalised kinship coefficients of various kinds,including those defined by Karigl (1981), Weeks & Lange (1988), Lange& Sinsheimer (1992) and García-Cortés (2015).
• multiPersonIBD(): Multi-person IBD coefficients (noninbredindividuals only)
• twoLocusKinship(): Two-locus kinship coefficients, as defined byThompson (1988)
• twoLocusIBD(): Two-locus IBD coefficients (noninbred pair ofindividuals)
• twoLocusIdentity(): Two-locus condensed identity coefficients (anypair of individuals)
• twoLocusGeneralisedKinship(): Generalised two-locus kinshipcoefficients (not exported)

If you useribd in a publication, please cite the most appropriateof the following works.

Standard coefficients
Magnus D. Vigeland. Relatedness coefficients in pedigrees with inbredfounders.Journal of Mathematical Biology,2020.doi:10.1007/s00285-020-01505-x.

Two-locus coefficients
Magnus D. Vigeland. Two-locus identity coefficients in pedigrees.G3Genes|Genomes|Genetics,2023.doi:10.1093/g3journal/jkac326.

General reference
Magnus D. Vigeland. Pedigree analysis in R. Academic Press,2021.ISBN:9780128245606.

The easiest way to get started withribd is to install thepedsuite:

install.packages("pedsuite")

If you only wantribd, install from CRAN as follows:

install.packages("ribd")

Alternatively, the latest development version is available from GitHub:

# install.packages("devtools") # install devtools if neededdevtools::install_github("magnusdv/ribd")

In the following we illustrate the use ofribd by computing a fewwell-known examples. We start by loading the package.

library(ribd)#> Loading required package: pedtools

For a child of related parents, its inbreeding coefficient is defined asthe probability of autozygosity (i.e., homologous alleles being IBD) ina random autosomal locus.

For example, the child of first cousins shown above has inbreedingcoefficient 1/16. We can compute this withribd as follows:

# Create pedigreex= cousinPed(1,child=TRUE)plot(x,hatched=9)# Inbreeding coefficient of the childinbreeding(x,ids=9)#> [1] 0.0625

By definition, the inbreeding coefficient equals thekinshipcoefficient of the parents, individuals 7 and 8:

kinship(x,ids=7:8)#> [1] 0.0625

As expected, the result was again 1/16.

For a pair of noninbred individuals, the three kappa coefficients aredefined as the probability that they have exactly 0, 1 or 2 alleles IBD,respectively, at a random autosomal locus. For example, for a pair offull siblings, this works out to be 1/4, 1/2 and 1/4, respectively.

Since the three kappa’s always sum to 1, any two of them are sufficient,forming the coordinates of a point in the plane. This gives rise to theIBD triangle, which is a useful tools for visualising (noninbred)relationships. The implementation inribd useskappa0 on the firstaxis andkappa2 on the second. In the example below, we place allpairs of pedigree members in the triangle.

We validate this with thekappaIBD() function ofribd:

# Create and plot pedigreey= nuclearPed(2)plot(y,margin=4)# Compute kappa for all pairsk= kappaIBD(y)# IBD triangleshowInTriangle(k,labels=T,pos= c(3,2,3,4,4,3))

(If you haveggplot2 andggrepel installed, tryshowInTriangle(k, plotType = "gg") for automatic separation of thelabels. There is also an interactive version, available withshowInTriangle(k, plotType = "plotly").)

As shown byThompson(1976), allrelationships of noninbred individuals satisfy a certain quadraticinequality in the kappa’s, resulting in an unattainable region of thetriangle (shown in grey above).

Here is a relationship in theinterior of the attainable region of theIBD triangle:

z= halfSibStack(2)plot(z,hatched=7:8,margin= c(3,2,2,2))kap= kappaIBD(z,ids=7:8)showInTriangle(kap)

The following figure shows the 9condensed identity states of twoindividualsa andb. Each state shows a pattern of identity bydescent (IBD) between the four homologous alleles. The four alleles arerepresented as dots, with a connecting line segment indicating IBD. Thestates are shown in the ordering used by Jacquard and most subsequentauthors.

The following relationship is perhaps the simplest example where all 9coefficients are nonzero.

x= fullSibMating(1)plot(x,hatched=5:6)

The functionidentityCoefs() by default returns the nine coefficientsin the order given above.

identityCoefs(x,ids=5:6)#> [1] 0.06250 0.03125 0.12500 0.03125 0.12500 0.03125 0.21875 0.31250 0.06250

The X-chromosomal version of Jacquard’s identity coefficients can becomputed by addingXchrom = TRUE in the call toidentityCoefs().Here is the output for all pairs in the above pedigree:

identityCoefs(x,Xchrom=TRUE)#>    id1 id2    D1    D2   D3   D4   D5  D6   D7  D8 D9#> 1    1   2 0.000 0.000 0.00 1.00   NA  NA   NA  NA NA#> 2    1   3 0.000 1.000   NA   NA   NA  NA   NA  NA NA#> 3    1   4 0.000 0.000 1.00 0.00   NA  NA   NA  NA NA#> 4    1   5 0.500 0.500   NA   NA   NA  NA   NA  NA NA#> 5    1   6 0.000 0.250 0.50 0.25   NA  NA   NA  NA NA#> 6    2   3 0.000 0.000   NA   NA 1.00 0.0   NA  NA NA#> 7    2   4 0.000 0.000 0.00 0.00 0.00 0.0 0.00 1.0  0#> 8    2   5 0.000 0.000   NA   NA 0.50 0.5   NA  NA NA#> 9    2   6 0.000 0.000 0.00 0.00 0.25 0.0 0.25 0.5  0#> 10   3   4 0.000 0.000 0.50 0.50   NA  NA   NA  NA NA#> 11   3   5 0.250 0.750   NA   NA   NA  NA   NA  NA NA#> 12   3   6 0.250 0.000 0.75 0.00   NA  NA   NA  NA NA#> 13   4   5 0.000 0.000   NA   NA 1.00 0.0   NA  NA NA#> 14   4   6 0.000 0.000 0.00 0.00 0.25 0.0 0.25 0.5  0#> 15   5   6 0.125 0.125 0.50 0.25   NA  NA   NA  NA NA

A precise definition of these X-chromosomal coefficients requires someexplanation, which we give here.

As in the autosomal case, the identity coefficients on X are theexpected proportions of the possible IBD states involving the alleles ata random locus (on X). The challenge is that the set of states dependson the individual’s sex: F/F, F/M, M/F or M/M (were F = female and M =male). The easiest case is F/F: When both are female, the states arejust as in the autosomal case.

Males, being hemizygous, have only 1 allele of a locus on X. Hence whenmales are involved the total number of alleles is less than 4, renderingthe autosomal states pictured above meaningless. However, to avoiddrawing (and learning the ordering of) new states for each sexcombination, we can re-use the autosomal state pictograms by invokingthe following simple rule:Replace the single allele of any male, witha pair of autozygous alleles. This gives a one-to-one map from the Xstates to the autosomal states.

For simplicity the output always contains 9 coefficients, but with NA’sin the positions of undefined states (depending on the sex combination).Hopefully this should all be clear from the following table:

A unique feature ofribd (in fact, throughout thepedsuitepackages) is the support for inbred founders. This greatly expands theset of pedigrees we can analyse with a computer.

Here is a fun example using inbred founders:A relationship exactlymidway (at least arithmetically speaking) between parent-child and fullsiblings. To achieve this, we modify the pedigreez from above(half-sibs/half-cousins), giving two of the founders carefully choseninbreeding coefficients.

founderInbreeding(z,id=3)=3-2*sqrt(2)founderInbreeding(z,id=6)=0.5* sqrt(2)

Note that founder inbreeding is by default included in the pedigreeplot:

# Plot pedigreeplot(z,hatched=7:8,labs=7:8)# IBD triangleshowInTriangle(kappaIBD(z,7:8))

If you wonder how the weird-looking inbreeding coefficients above werechosen, you can check out my paperRelatedness coefficients inpedigrees with inbredfounders (J Math Biol,2020). In it I show thatany point in the white region (including itsboundary) of the IBD triangle can be constructed as a double half cousinrelationship with suitable founder inbreeding.

The construction described in the paper is implemented in the functionconstructPedigree() inribd. For example, the following commandproduces basically the pedigree in the previous figure:

w= constructPedigree(kappa= c(1/8,6/8,1/8))#> Result:#>   Paternal half cousins of degree 1; founder inbreeding 0.1716#>   Maternal half siblings; founder inbreeding 0.7071