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

• 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", "Upload list" or "All available". "Upload list" has no upload control and currently behaves exactly like "All available"

• 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

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()