Contents

compute$relatedness$prune

Choose which samples to keep so that no two are related

Decides which samples of a PolyGeniusStudy to keep so that no two kept samples are related above the requested degree, using the greedy algorithm of PLINK 2 --king-cutoff. Returns the decision only: the study is not changed, and dropping the samples is up to the caller. See compute-relatedness for the algorithm and its limits.

Usage

compute$relatedness$prune(
  data,
  degree = 2L,
  threshold = NULL,
  key = "kinship",
  variants = NULL
)

Arguments

Argument	Description
`data`	A PolyGeniusStudy. key is looked up in its $sample.pairs.
`degree`	Integer scalar, default 2L: prune relatives at this degree or closer. See [compute$relatedness$kinship](/reference/compute-relatedness-kinship/) for the cut points. 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. A pair is related when its kinship is strictly above the cut point, as in PLINK's --king-cutoff.
`key`	Character scalar, default "kinship", naming a matrix in data$sample.pairs to prune from; NULL always estimates kinship afresh. When no matrix is stored under key, kinship is estimated for this call and not stored.
`variants`	A file path, a data.frame, or NULL (default). Passed to [compute$relatedness$kinship](/reference/compute-relatedness-kinship/) when kinship is estimated, and unused otherwise.

Value

A logical vector with one element per sample, in study order and without names: TRUE for the samples to keep. It carries diagnostics() — n.relationships (related pairs considered), n.retained, n.dropped, and the n.filesets / cross.fileset note of the kinship matrix the decision was made from.

provenance() — in misc, the degree (NA when threshold was given) and threshold the decision was made at, and kinship: the sample.pairs member it was read from, or "recomputed".

Details

A stored matrix holds only the pairs at or above the cut point it was computed at. It can therefore answer only at that cut point or a coarser one. The call aborts when the stored matrix records no cut point, or a finer one is requested: the pairs in between were never computed, so pruning would leave relatives behind.

Examples

data$sample.pairs$kinship <- compute$relatedness$kinship(data, degree = 2)
data$samples$unrelated    <- compute$relatedness$prune(data, degree = 2)
data <- data[unrelated, ]

# Ignore the stored matrix and estimate kinship for this cut point
keep <- compute$relatedness$prune(data, degree = 1, key = NULL)