nprcgenekeepr (version 2.0.0)

applyKinshipOverrides: Apply outside-information kinship overrides to a kinship matrix

Description

Writes pairwise kinship coefficients from outside information into a computed kinship matrix, replacing the pedigree-derived value for the named pairs. Each (id1, id2, kinship) row sets both kmat[id1, id2] and its symmetric twin kmat[id2, id1]; all other cells are unchanged. This is a direct cell replacement -- it does not propagate to descendant rows.

Usage

applyKinshipOverrides(kmat, overrides)

Value

kmat with the override cells replaced (symmetric).

Arguments

kmat

a dense, symmetric, id-named numeric kinship matrix.

overrides

data.frame of overrides (id1, id2, kinship); NULL or a zero-row frame is a no-op returning kmat unchanged. Validated with checkKinshipOverrides.

Details

kmat must be a dense, symmetric, id-named base R matrix (the object kinship returns); a sparse Matrix object is out of contract. The function is strict: it stop()s on an id absent from the matrix and on a value above the exact positive-semi-definiteness bound sqrt(kmat[id1, id1] * kmat[id2, id2]). Soft, run-preserving handling of ids outside the analysis set is the caller's responsibility -- reportGV warn-drops non-member ids before calling this. kinship() itself is never modified (it has several callers, including two simulations that must not take current-kinship overrides).

Examples

ped <- nprcgenekeepr::qcPed
kmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen)
overrides <- data.frame(
  id1 = ped$id[1], id2 = ped$id[2], kinship = 0.25,
  stringsAsFactors = FALSE
)
kmat <- applyKinshipOverrides(kmat, overrides)