Get potential parents for animals with unknown parents

Usage

getPotentialParents(
  ped,
  minSireAge = NULL,
  minDamAge = NULL,
  minParentAge = lifecycle::deprecated(),
  maxGestationalPeriod = NULL,
  gestationTable = NULL
)

Arguments

ped

the pedigree information in data.frame format. Pedigree (req. fields: id, sire, dam, sex, birth, exit, fromCenter; the species field is optional). The gen and population fields are not used. This requires complete pedigree information.

minSireAge

numeric minimum age in years for a male to be proposed as a potential sire. NULL (default) looks up the floor for each candidate's species via getSpeciesMinBreedingAge (falling back to 2 years when the species is missing or unknown); a supplied value overrides that floor for all male candidates. Candidates with missing birth dates are not considered.

minDamAge

numeric minimum age in years for a female to be proposed as a potential dam. NULL (default) looks up the floor for each candidate's species via getSpeciesMinBreedingAge (falling back to 2 years when the species is missing or unknown); a supplied value overrides that floor for all female candidates.

minParentAge

Deprecated scalar minimum parent age. Supplying it sets both minSireAge and minDamAge; use those sex-specific parameters instead. Supplying NULL disables the age check entirely.

maxGestationalPeriod

integer maximum number of days between conception and birth for the species being analyzed (a conservative upper bound, e.g. 210 for rhesus whose typical gestation is about 165 days). When NULL (the default) the window is looked up per animal from the species column of ped via getSpeciesGestation, falling back to 210 days for animals whose species is missing or unrecognized; supply an explicit integer to use one fixed window for every animal. It is used two ways: (1) a sire who exited the colony between conception (birth - maxGestationalPeriod) and birth is still retained as a candidate; and (2) a female who delivered another offspring within maxGestationalPeriod days of the focal birth is excluded as a candidate dam, because a female bears one offspring at a time. The sire check uses presence at conception while the dam check uses presence at birth; this asymmetry is intentional – a sire need only be present to conceive, whereas a dam must be present through the pregnancy to give birth.

gestationTable

optional data.frame (columns species, gestation) passed to getSpeciesGestation for the per-animal lookup when maxGestationalPeriod is NULL. Defaults to NULL, which uses the bundled speciesGestation table.

Value

a list of list with each internal list being made up of an animal id (id), a vector of possible sires (sires) and a vector of possible dams (dams). The id must be defined while the vectors sires and dams can be empty. A fourth element, damBasis, is a single string saying where dams came from: "provenBreeder" when the candidates are females who gave birth near the time of the focal birth, "eligibleFemale" when there were none and dams lists every female old enough and present at the birth instead, and NA when dams is empty. In both tiers, a female who delivered another offspring within maxGestationalPeriod days of the focal birth is never listed. Candidates are listed only for the parent that is missing: when an animal's dam is recorded its dams is empty, and when its sire is recorded its sires is empty. NULL (not a list) is returned when no animal has an unknown parent with a candidate and when ped has no fromCenter column.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::rhesusPedigree
## getPotentialParents needs a logical fromCenter column flagging
## colony-born animals; add one if your pedigree lacks it.
ped$fromCenter <- TRUE
potentialParents <- getPotentialParents(
  ped = ped, minSireAge = 2, minDamAge = 2, maxGestationalPeriod = 210L
)
## Each element pairs a focal id with candidate sires and dams.
potentialParents[[1L]]
#> $id
#> [1] "BRI2MW"
#> 
#> $sires
#>  [1] "HKTQ40" "MY1AEU" "QWUKUY" "1X40V5" "WDBGPF" "6MGJYG" "8LWCAD" "SLN0TF"
#>  [9] "Q7F87W" "IQLWH8" "M0YNUR" "RYP77M" "8LKBV9" "D0Z114" "1W4GNT" "D1WP48"
#> [17] "CAN12C" "KUENM8" "QP1WMJ" "WCPXHD" "DKMJ2Z" "1Y8P15" "4F3ASD" "DKDP5B"
#> [25] "XL7AVE" "YPHFHF" "A3UZAN" "7U5NJD" "ELGVC6" "L07M06" "4U7JTW" "270UK6"
#> [33] "LUPGF8" "S0ZHJP" "WWZRCW" "H16EC4" "81MJXH" "K9TMQP" "GA204Z" "V1X2X3"
#> [41] "P49ZD1" "KY4G8M" "9JC6RF" "M5DJVP" "HJLX2B" "SPHGC9" "62PLX3" "QQ24T8"
#> [49] "9LZVTE" "VTZFWZ"
#> 
#> $dams
#> [1] "HR70BU" "I2G9D6" "J8XZ81" "HV7LZ3" "IMF6BL"
#> 
#> $damBasis
#> [1] "provenBreeder"
#>