Learn R Programming

nprcgenekeepr (version 3.0.0)

reportAncestryViolations: Report ancestry-rule violations within formed groups

Description

Issue #168 Slice 2: the script-callable flag/inspection half of the ancestry guardrails. Given any list of formed groups (for example the group element returned by groupAddAssign, excluding its final unused-animals element), a pedigree carrying an ancestry column, and a rules table in checkAncestryRules's shape, it reports every within-group pair matching a rule -- block and flag severities alike -- plus a rule-coverage summary so permissive silence is visible (a level no rule names participates in no conflict; the summary says how many animals sit at each level and whether any rule covers it).

Usage

reportAncestryViolations(groups, ped, rules, overriddenRules = NULL)

Value

A list with two data.frames:

violations

One row per violating within-group pair: group (integer index into groups), id1, id2, ancestry1, ancestry2 (the two animals' own levels), rule (the matched rule's unordered pair as a sorted "LEVEL-LEVEL" string), severity ("block" or "flag"), and status ("violation" or "overridden"). Zero rows, same columns, when nothing violates.

coverage

One row per standardized ancestry level (CHINESE, INDIAN, HYBRID, JAPANESE, OTHER, UNKNOWN): ancestry, n (animals in groups at that level), and covered (TRUE when at least one rule names the level).

Arguments

groups

list of character vectors of animal IDs, one vector per formed group. NA entries (the empty unused-animals marker groupAddAssign can produce) are ignored.

ped

data frame with at least id and ancestry columns. Ancestry values are coerced with toupper(trimws()), so a post-qcStudbook pedigree and a hand-built frame both work.

rules

data frame of ancestry compatibility rules; validated here via checkAncestryRules.

overriddenRules

optional data frame with ancestry1 and ancestry2 columns naming the rules overridden for this run (unordered match, case-insensitive). Default NULL: no overrides.

Details

A rule listed in overriddenRules still reports its violating pairs -- with status "overridden" rather than "violation", never silently absent. An overriddenRules row that matches no rule in rules is an error, so a typo cannot silently disable nothing. Any id in groups that is absent from ped$id stops the function with an error.

Examples

Run this code
library(nprcgenekeepr)
ped <- qcStudbook(
  read.csv(
    system.file("extdata", "examples", "example_ancestry_pedigree.csv",
      package = "nprcgenekeepr"
    ),
    stringsAsFactors = FALSE, na.strings = c("", "NA")
  ),
  minSireAge = 2, minDamAge = 2, reportChanges = FALSE, reportErrors = FALSE
)
rules <- checkAncestryRules(readAncestryRules(
  system.file("extdata", "examples", "example_ancestry_rules.csv",
    package = "nprcgenekeepr"
  )
))
reportAncestryViolations(list(c("I1", "C1"), c("I2", "U1")), ped, rules)

Run the code above in your browser using DataLab