Contents
compute$relatedness$kinship
Estimate KING-robust kinship between a study's samples
Runs PLINK 2's KING-robust estimator within each genotype fileset of a PolyGeniusStudy
and returns the related pairs as a sparse sample-by-sample matrix, ready to store in
data$sample.pairs. Only pairs related at the requested degree or closer are filled in.
See compute-relatedness for how the estimate is made and what it can resolve.
Usage
compute$relatedness$kinship(
data,
degree = 2L,
threshold = NULL,
variants = NULL,
cross.filesets = FALSE
)Arguments
| Argument | Description |
|---|---|
data | A PolyGeniusStudy. |
degree | Integer scalar, default 2L: the most distant relationship to report. One of 0 (duplicates), 1 (adds parent-offspring and full siblings), 2 (adds half siblings, grandparent-grandchild and avuncular pairs) or 3 (adds first cousins), with cut points 0.354, 0.177, 0.0884 and 0.0442. Ignored when threshold is given. |
threshold | Numeric scalar above 0 and at most 0.5, or NULL (default). A kinship cut point used in place of degree's. |
variants | A file path, a data.frame, or NULL (default). The markers kinship is estimated over: a BED1-style file or table of chr/start/end intervals. NULL resolves the common20k variant space through workspace$catalogs$variantSpaces, and aborts if it cannot be reached. |
cross.filesets | Logical scalar, default FALSE, the only value accepted. Kinship is estimated within one fileset at a time, so a participant genotyped in two filesets is never matched. TRUE aborts rather than return a within-fileset answer. |
Value
A sparse symmetric dsCMatrix of n.samples by n.samples, with data$sample.names on
both dimensions, values in the lower triangle only and an empty diagonal. A pair PLINK
reports at or above the cut point holds its kinship; every other cell is zero. It carries
artifacts() — pairs: every pair PLINK reported, with its genotype, iid1,
iid2, n.snp, hethet, ibs0 and kinship. A pair without an estimate is kept
here with NaN kinship.
diagnostics() — n.pairs (pairs in the matrix), n.pairs.unestimable,
n.pairs.by.degree (the matrix's pairs per degree band, down to more.distant
below 0.0442), n.samples.related, n.filesets, and cross.fileset, always
"not.evaluated".
provenance() — in misc, the settings as resolved: degree (NA when
threshold was given), the threshold applied, and variants.
compute$relatedness$prune() reads threshold back.
Warns when a pair has no estimate, because its two samples share no called marker.
Aborts when PLINK reports a sample the study does not hold.
Examples
data$sample.pairs$kinship <- compute$relatedness$kinship(data, degree = 2)
# A cut point that is not one of the conventional degrees
close <- compute$relatedness$kinship(data, threshold = 0.2)
# The pairs, with the columns the matrix cannot hold
artifacts(data$sample.pairs$kinship)$pairsSee Also
compute-relatedness, compute$relatedness$prune
Other compute-relatedness:
compute-relatedness,
compute-relatedness-prune