Validate a kinship overrides table

Checks the structure and domain of an outside-information kinship override table. The table supplies pairwise kinship coefficients (id1, id2, kinship) that applyKinshipOverrides writes into a computed kinship matrix, replacing the pedigree-derived value for those pairs. It mirrors checkGenotypeFile: it stop()s on structural or domain errors and returns the (id-coerced) table when the input is acceptable.

Usage

checkKinshipOverrides(overrides)

Arguments

overrides

data.frame with id columns id1 and id2 and a numeric kinship column; each row is one off-diagonal pair. Any extra columns are ignored.

Value

The validated overrides data.frame with id1 and id2 coerced to character.

Details

kinship is the kinship coefficient f (the probability that an allele drawn at random from each of the two animals is identical by descent), not the coefficient of relatedness r (= 2f for non-inbred animals). Supplying r – e.g. 0.25 for half-sibs whose true f is 0.125 – silently corrupts the matrix, so an off-diagonal value above 0.5 (the maximum for a non-inbred pair) draws a warning here. The exact positive-semi-definiteness bound is enforced by applyKinshipOverrides once the matrix diagonal is known.

Examples

overrides <- data.frame(
  id1 = c("A1", "A3"), id2 = c("A2", "A4"),
  kinship = c(0.25, 0.125), stringsAsFactors = FALSE
)
checkKinshipOverrides(overrides)
#>   id1 id2 kinship
#> 1  A1  A2   0.250
#> 2  A3  A4   0.125