Breeding Groups Module - Server Function

Server logic for breeding group formation using the groupAddAssign algorithm. This module integrates with the kinship-based maximal independent set (MIS) algorithm to form optimal breeding groups that minimize relatedness within groups while maximizing group sizes.

Usage

modBreedingGroupsServer(
  id,
  pedigree,
  geneticValues = NULL,
  kinshipMatrix = NULL,
  kinshipOverrides = NULL,
  twinRelations = NULL
)

Arguments

id

character vector of length 1. Module namespace identifier.

pedigree

reactive returning pedigree data frame with columns: id, sire, dam, sex, and optionally birth, exit, gen.

geneticValues

optional reactive returning genetic value results from modGeneticValueServer. Used to source the topRanked animal-source candidate list and, with any animal source, for the "Genetic-value floor" inclusion criterion, which drops "Low Value" animals and IDs absent from the report. Group formation halts until it is available in either of those cases. Unrelated to kinship.

kinshipMatrix

optional reactive returning a kinship matrix, typically a full-pedigree matrix shared with modSummaryStatsServer (e.g. from appServer) rather than independently recomputed. If NULL, the module calculates kinship from the pedigree.

kinshipOverrides

optional reactive returning a validated outside-information kinship-override data frame (id1, id2, kinship); see applyKinshipOverrides. When the module recomputes kinship from the pedigree (the shared kinshipMatrix is unavailable), the overrides are applied to that matrix so group formation reflects them regardless of tab order. NULL (the default) is a no-op. A provided kinshipMatrix is expected to already carry overrides applied at its source.

twinRelations

optional reactive returning a validated twin/zygosity sidecar data.frame (id1, id2, code); see checkTwinRelations. When the module recomputes kinship from the pedigree (the shared kinshipMatrix is unavailable), it is passed straight through to kinship so group formation reflects a declared MZ-twin pair's corrected identity regardless of tab order (BL-N Slice 3). NULL (the default) is a no-op. A provided kinshipMatrix is expected to already reflect it at its source.

Value

List with reactive components:

• groups - List with one character vector of animal IDs per formed group; when candidates remain unplaced a final "Unused" element is appended

• nGroups - Number of elements of groups, counting the "Unused" element when present

• groupLabels - Character vector with one name per element of groups: "Group 1", "Group 2" and so on, and "Unused animals" for the final "Unused" element when there is one; groups itself is not named

• score - Optimization score from groupAddAssign (minimum group size)

• unassigned - Character vector of candidate IDs that appear in no element of groups; leftovers are collected in the trailing "Unused" element, so this is normally empty

• groupKinship - List of kinship matrices per group when the "Include kinship in display of groups" box is checked (default unchecked); NULL otherwise

• ancestryRules - The validated ancestry rules table loaded through the Ancestry Guardrails upload (see checkAncestryRules), or NULL when no usable file is loaded. It is the table as loaded, whether or not the pedigree has an ancestry column: each consumer (formation here, modMatePairServer) applies its own column check

Details

The module supports multiple configuration options:

• Animal source: "Top ranked", "All available" or "My own list" (animal IDs typed or pasted by the user)

• Living animals only: Every source draws only on animals that are alive: those with a status of ALIVE when the pedigree has a status column, otherwise those with no exit date, and every animal when it has neither column. The cut to the top N animals or the genetic-value floor comes after this, so "Top ranked" takes the best-ranked living animals. When no animal in the source is alive the tab shows an error notice and forms no groups. Animals typed into a seed group are not drawn from this pool and are accepted as typed

• Inclusion criterion: Include animals by "Top N ranked" (with the number of top animals) or "Genetic-value floor"

• Group counts and ages: The number of groups and the minimum breeding age

• Simulations and exhaustive mode: The number of simulations; "Exhaustive enumeration mode" is offered only when the number of groups is 1 and the sex ratio is "none"

• Seed groups: Optionally seed groups with specific animals

• Kinship threshold: Maximum allowed kinship within groups

• Harem mode: Form groups with exactly one male each

• Sex ratio: Target female-to-male ratio in groups

• Ancestry guardrails: Optional uploaded ancestry rules (see checkAncestryRules) enforced during group formation; inactive when the pedigree has no ancestry column. A block rule can be overridden for the session through a confirm gate requiring a stated reason; the "Ancestry" results tab reports each run's rule violations (overridden rules stay visible, marked overridden – see reportAncestryViolations) and offers the run's downloadable audit manifest

The formed groups stay in memory when a new file is read or the Pedigree Browser is trimmed. When a group then holds an animal the loaded pedigree no longer has, the Groups, Statistics and Group Detail pages say so in one sentence in place of their tables, and bringing the earlier pedigree back shows the groups again. The returned groups are not changed.

Up to maxCandidates (the "Candidates to retain" input; default 5, range 1-50) distinct candidate groupings are formed per run (issue #125); fewer are returned when the run finds fewer distinct ones. A "Candidate grouping" selector lets the user switch among them without re-running groupAddAssign. All reactive components below reflect the currently-selected candidate, defaulting to the best-scoring one – identical to the single-solution behavior prior to issue #125.

The results are shown on the Groups, Statistics, Group Detail and Ancestry tabs.

See also

modBreedingGroupsUI for the UI component

groupAddAssign for the underlying MIS algorithm

modGeneticValueServer for genetic value analysis

kinship for kinship matrix calculation

Other Shiny modules: modBreedingGroupsUI(), modCrossCenterIdentityServer(), modCrossCenterIdentityUI(), modDeidentifiedExportServer(), modDeidentifiedExportUI(), modGeneticDiversityServer(), modGeneticDiversityUI(), modGeneticValueServer(), modGeneticValueUI(), modGvAndBgDescServer(), modGvAndBgDescUI(), modInputServer(), modInputUI(), modMarkerGeneticsServer(), modMarkerGeneticsUI(), modMatePairServer(), modMatePairUI(), modORIPReportingServer(), modORIPReportingUI(), modPedigreeServer(), modPedigreeUI(), modPotentialParentsServer(), modPotentialParentsUI(), modPyramidServer(), modPyramidUI(), modSnapshotTrendsServer(), modSnapshotTrendsUI(), modSummaryStatsServer(), modSummaryStatsUI()