ibdPlot {GWASTools} | R Documentation

## Plot theoretical and observed identity by descent values and assign relationships

### Description

`ibdPlot` produces an IBD plot showing observed identity by descent values color coded by expected relationship. Theoretical boundaries for full-sibling, second-degree, and third-degree relatives are plotted in orange. `ibdAreasDraw` overlays relationship areas for IBD analysis on the plot. `ibdAssignRelatedness` identifies observed relatives. `ibdAssignRelatednessKing` identifies observed relatives using the kinship coefficients and IBS0 estimates from the KING model. `kingIBS0FSCI` returns a confidence interval for expected IBS0 for full siblings.

### Usage

    ibdPlot(k0, k1, alpha=0.05, relation=NULL, color=NULL,
            rel.lwd=2, rel.draw=c("FS", "Deg2", "Deg3"), ...)

    ibdAreasDraw(alpha=0.05, m=0.04, po.w=0.1, po.h=0.1,
                 dup.w=0.1, dup.h=0.1, un.w=0.25, un.h=0.25, rel.lwd=2,
    	     xcol=c("cyan","red","blue","lightgreen","magenta","black"))

    ibdAssignRelatedness(k0, k1, alpha=0.05, m=0.04, po.w=0.1, po.h=0.1,
                         dup.w=0.1, dup.h=0.1, un.w=0.25, un.h=0.25)

    ibdAssignRelatednessKing(ibs0, kc, cut.kc.dup=1/(2^(3/2)),
                             cut.kc.fs=1/(2^(5/2)), cut.kc.deg2=1/(2^(7/2)),
                             cut.kc.deg3=1/(2^(9/2)), cut.ibs0.err=0.003)

    kingIBS0FSCI(freq, alpha=0.01)

### Arguments

`k0` | A vector of k0 values.
`k1` | A vector of k1 values.
`kc` | A vector of kinship coefficient values (KING model).
`ibs0` | A vector of IBS0 values (KING model).
`alpha` | significance level - finds 100(1-alpha)% prediction intervals for second and third degree relatives and 100(1-alpha)% prediction ellipse for full siblings.
`relation` | A vector of relationships. Recognized values are "PO"=parent/offspring, "FS"=full siblings, "HS"=half siblings, "Av"=avuncular, "GpGc"=grandparent-grandchild, "Deg2"=any second-degree, "FC"=first cousins, "HAv"=half-avuncular, "Deg3"=any third degree, "U"=unrelated, and "Q"=unknown.
`color` | A vector of colors for (k0,k1) points.
`rel.lwd` | Line width for theoretical full-sib, Deg2, and Deg3 boundaries.
`rel.draw` | Which theoretical boundaries to plot: one or more of "FS" (full-sib), "Deg2" (second-degree), "Deg3" (third-degree). If `NULL`, no boundaries are drawn.
`...` | Other graphical parameters to pass to `plot` and `points`.
`m` | width of rectangle along diagonal line
`po.w` | width of parent-offspring rectangle
`po.h` | height of parent-offspring rectangle
`dup.w` | width of duplicate rectangle
`dup.h` | height of duplicate rectangle
`un.w` | width of unrelated rectangle
`un.h` | height of unrelated rectangle
`xcol` | colors for parent-offspring, full-sib, Deg2, Deg3, dup & unrelated areas
`cut.kc.dup` | Kinship coefficient threshold for dividing duplicates and first degree relatives.
`cut.kc.fs` | Kinship coefficient threshold for dividing full siblings and second degree relatives.
`cut.kc.deg2` | Kinship coefficient threshold for dividing second and third degree relatives.
`cut.kc.deg3` | Kinship coefficient threshold for dividing third degree relatives and unrelated.
`cut.ibs0.err` | IBS0 threshold for dividing parent-offsprings pairs from other relatives. Should be 0, but is usually slightly higher due to genotyping errors.
`freq` | vector of allele frequencies at the variants used in the KING analysis

### Details

`ibdPlot` produces an IBD plot showing observed identity by descent values color coded by expected relationship, typically as deduced from pedigree data. Points are plotted according to their corresponding value in the `color` vector, and the `relation` vector is used to make the plot legend. In addition to the relationships listed above, any relationships output from `pedigreePairwiseRelatedness` will be recognized.

Theoretical boundary for full-sibs is indicated by ellipse and boundaries for second and third degree intervals are indicated in orange. For full-sibs, 100(1-alpha)% prediction ellipse is based on assuming bivariate normal distribution with known mean and covariance matrix. For second degree (half siblings, avuncular, grandparent-grandchild) and third degree (first cousins), 100(1-alpha)% prediction intervals for k1 are based on assuming normal distribution with known mean and variance, computed as in Hill and Weir (2011).

`ibdAreasDraw` overlays relationship areas on the plot to help with analyzing observed relationships.

`ibdAssignRelatedness` identifies relatives based on their (k0, k1) coordinates.

`ibdAssignRelatednessKing` identifies relatives based on their (ibs0, kc) coordinates (KING model).

`kingIBS0FSCI` uses allele frequencies to find the confidence interval for expected IBS0 for full siblings. We condition on the three possible IBD states: IBD0, IBD1, or IBD2; but P(AA, aa | IBD1) = P(AA, aa | IBD2) = 0.

P(IBS0 | FS) = P(AA, aa | FS) + P(aa, AA | FS) = P(AA, aa | IBD0)P(IBD0) + P(aa, AA | IBD0)P(IBD0) = p^2*q^2*k0 + q^2*p^2*k0 = 2*p^2*q^2*k0

Knowing a pair's value of k0 and the allele frequencies at each variant, we can get an estimate of P(IBS0 | FS) by averaging across all the markers used in the analysis. Siblings have k0 = 0.25 on average.

### Value

`ibdAssignRelatedness` and `ibdAssignRelatednessKing` return a vector of relationships with values "Dup"=duplicate, "PO"=parent-offspring, "FS"=full sibling, "Deg2"=second degree, "Deg3"=third degree, "U"=unrelated, and "Q"=unknown.

`kingIBS0FSCI` returns a vector with 3 values: the point estimate, the lower bound of the CI, the upper bound of the CI

### Author(s)

Cathy Laurie, Cecelia Laurie, Adrienne Stilp, Matthew Conomos

### References

Hill, W.G. and B.S. Weir, Variation in actual relationship as a consequence of mendelian sampling and linkage, Genet. Res. Camb. (2011), 93, 47-64.

Manichaikul, A., Mychaleckyj J.C., Rich S.S., Daly K., Sale M., and Chen W.M., Robust relationship inference in genome-wide association studies, Bioinformatics (2010), 26(22), 2867-2873.

### See Also

`relationsMeanVar`, `pedigreePairwiseRelatedness`

### Examples

    k0 <- c(0, 0, 0.25, 0.5, 0.75, 1)
    k1 <- c(0, 1, 0.5, 0.5, 0.25, 0)
    exp.rel <- c("Dup", "PO", "FS", "HS", "FC", "U")
    ibdPlot(k0, k1, relation=exp.rel)
    ibdAreasDraw()
    obs.rel <- ibdAssignRelatedness(k0, k1)

    kc <- c(0.5, 0.25, 0.25, 0.125, 0.063, 0)
    ibs0 <- c(0, 0, 0.25, 0.5, 0.75, 1)
    obs.rel.king <- ibdAssignRelatednessKing(ibs0, kc)

    library(SNPRelate)
    library(GWASdata)
    gdsfile <- system.file("extdata", "illumina_geno.gds", package="GWASdata")
    gds <- snpgdsOpen(gdsfile)
    ibd <- snpgdsIBDKING(gds)
    ibd <- snpgdsIBDSelection(ibd, kinship.cutoff=1/32)
    snpgdsClose(gds)

    gds <- GdsGenotypeReader(gdsfile)
    data(illuminaScanADF)
    genoData <- GenotypeData(gds, scanAnnot=illuminaScanADF)
    freq <- alleleFrequency(genoData)
    close(genoData)

    fs <- kingIBS0FSCI(freq[,"MAF"])
    plot(ibd$IBS0, ibd$kinship)
    abline(v=fs)
    obs.rel.king <- ibdAssignRelatednessKing(ibd$IBS0, ibd$kinship,
                                             cut.ibs0.err=fs["LL"])

[Package GWASTools version 1.38.0 Index]