Mate Pair Analysis Module - Server Function — modMatePairServer • nprcgenekeepr

Reports eligible individual mate-pair candidates via reportMatePairs (issue #151 Slice 1), wrapped in a curator-facing configuration panel for the D4-ratified population scope (populationSource: "allAlive" – the animals that are alive: a status of ALIVE when the pedigree has a status column, otherwise no recorded exit date, and every id when it has neither column (the rule Breeding Groups uses); "topRanked" – the top nTopAnimals ids in geneticValues' own report order, mirroring modBreedingGroupsServer's own topRanked reading; "custom" – a pasted, delimiter-separated id list), the D2 minimum- age floor, and the D5-ratified exclude-list textarea. Kept structurally and file-wise separate from modBreedingGroupsServer (D1) – this module shares no code with it.

Usage

modMatePairServer(
  id,
  pedigree,
  kinshipMatrix = NULL,
  markerKinshipMatrix,
  geneticValues,
  ancestryRules = NULL,
  kinshipFor = NULL
)

Arguments

id: character vector of length 1. Module namespace identifier.
pedigree: reactive returning the current pedigree data frame (columns id, sire, dam, sex, age, optionally exit).
kinshipMatrix: optional reactive returning a pedigree-based kinship matrix (row/column names are animal IDs) covering the population. It is used before kinshipFor.
markerKinshipMatrix: reactive returning the genotype-only KING- robust kinship matrix from modMarkerGeneticsServer's own markerKinshipMatrix return element, or NULL before a genotype file has been uploaded.
geneticValues: reactive returning the current genetic-value report data.frame (shared$geneticValues, with id, indivMeanKin, gu columns), or NULL before the Genetic Value Analysis tab has been run.
ancestryRules: optional reactive returning the validated ancestry rules table (see checkAncestryRules) from modBreedingGroupsServer's ancestryRules return element, or NULL when no rules are loaded. NULL (the default, or a reactive that returns NULL) applies no rules, and the results are identical to a run before this argument existed.
kinshipFor: optional function of a character vector of animal IDs that returns those animals' kinship matrix. At each "Find Eligible Pairs" click the module asks it for the population. appServer passes one that computes kinship from those animals and their ancestors only. With neither kinshipMatrix nor kinshipFor the click does nothing.

Value

A list with three reactive elements: pairs, the eligible- pairs data.frame from the most recent reportMatePairs() run (see that function's own return documentation for columns); excluded, the corresponding excluded-pairs data.frame; and isReady, TRUE once a run has completed. Before the first run pairs() and excluded() halt (via req) rather than returning NULL.

Details

The geneticValues wiring detail. shared$geneticValues (as threaded from appServer.R, matching every other module's own convention) is the flat reportGV()$report data.frame, not the list(report = ...) shape reportMatePairs itself expects. This server wraps it (list(report = geneticValues())) immediately before calling reportMatePairs() – omitting the wrap would not error (a data.frame's $report accessor returns NULL, not a condition), it would silently leave every genetic- value column NA.

Population scoping is a hard dependency, not a fallback-recompute. Unlike modBreedingGroupsServer's optional kinshipMatrix (which recomputes from pedigree when absent), this module always receives its kinship from its caller – a kinshipMatrix, or the kinshipFor function appServer.R passes, asked for the population at each run – and simply depends on it (module-contract rule 5: upstream absence is req()), matching modMarkerGeneticsServer's own simpler precedent – there is no standalone use case for this module that would need an independent recompute path.

Ancestry guardrails (issue #169). ancestryRules carries the rules loaded on the Breeding Groups tab. When rules are loaded and the pedigree has an ancestry column, each run hands them to reportMatePairs: a pair matching a block rule moves to the Excluded tab (reason "ancestry rule") and a pair matching a flag rule stays in Eligible Pairs, annotated. The rules are read once, at the "Find Eligible Pairs" click, so loading or clearing rules afterwards never rewrites a finished run's tables. The module checks for the ancestry column before passing rules (the report function stops without it); a rules-loaded run on a pedigree with no such column runs exactly as it does with no rules, and the status line says the guardrails are inactive. An always-visible status line reports the loaded state.

Overriding a block rule. With active rules, the "Ancestry Guardrails" section lists the block rules not yet overridden. "Override rule..." opens a confirmation step that shows the warning text verbatim and requires a written reason (a blank reason is refused); confirming relaxes that one rule for this tab's runs, for the session, until the overrides are cleared or the rules change. An overridden rule's pairs stay in Eligible Pairs marked "overridden" (severity still "block"); they are never silently dropped. Each override is recorded per tab – Breeding Groups keeps its own – and the next run applies it; a finished run is never rewritten.

The Ancestry tab. Shows the displayed run's coverage summary (how many candidate animals carry each ancestry classification and which classifications no rule reaches) and a "Download Audit Manifest" button. The manifest is one row per rule: the rule as written, whether it was overridden and why, how many otherwise-eligible pairs it matched, the animal census by classification, and the confirmation warning verbatim. It describes the displayed run's own rules and overrides, and is unavailable for a run that had no rules in effect.

Mate Pair Analysis Module - Server Function

Usage

Arguments

Value

Details

See also