R/calcNeSexRatio.R

In nprcgenekeepr: Genetic Tools for Colony Management

## Copyright(c) 2017-2026 R. Mark Sharp
## This file is part of nprcgenekeepr

#' Calculate the demographic sex-ratio effective population size
#'
#' Part of the Genetic Value Analysis
#'
#' The sex-ratio effective size, \code{Ne = 4 * nMale * nFemale /
#' (nMale + nFemale)}, is the effective population size implied by an unequal
#' breeding sex ratio, where \code{nMale} and \code{nFemale} are the numbers of
#' current living breeders that are known male and known female. It quantifies
#' the diversity lost when many of one sex are bred to few of the other (as in a
#' harem colony): it equals the census count when the sexes are balanced and
#' falls toward four times the rarer sex as the ratio skews.
#'
#' The breeders are the current living breeders of \code{ped} (living animals
#' that appear as a sire or dam, excluding auto-generated unknown parents),
#' independent of which animals are selected as probands -- a different
#' population than the analysis-set founder statistics (\code{\link{calcFE}},
#' \code{\link{calcFG}}, \code{\link{calcGeneDiversity}}). Only animals with a
#' known sex (\code{"M"} or \code{"F"}) are counted; unknown and hermaphrodite
#' breeders are excluded. When either sex is absent among the living breeders
#' (\code{nMale == 0} or \code{nFemale == 0}, including no living breeders at
#' all), the result is \code{0}: a single breeding sex contributes no diversity
#' from sex balance.
#'
#' Like all effective-size estimators this idealizes a Wright-Fisher population
#' (constant size, discrete generations, random union of gametes within each
#' sex); a managed colony departs from those assumptions, so read the result as
#' a sex-ratio index rather than a literal head count.
#'
#' @param ped Pedigree data.frame with \code{id}, \code{sire}, \code{dam}, and
#' \code{sex}; \code{exit} is used to identify living animals when present.
#' @return The sex-ratio effective size, a single non-negative number; \code{0}
#' when either breeding sex is absent among the living breeders.
#' @references Crow, J. F. and Kimura, M. (1970) \emph{An Introduction to
#' Population Genetics Theory}. Harper and Row, New York.
#' @family genetic value analysis
#' @seealso \code{\link{calcGeneDiversity}}
#' @export
#' @examples
#' ped <- data.frame(
#'   id = c("s1", "d1", "d2", "k1", "k2"),
#'   sire = c(NA, NA, NA, "s1", "s1"),
#'   dam = c(NA, NA, NA, "d1", "d2"),
#'   sex = c("M", "F", "F", "M", "F"),
#'   exit = c(NA, NA, NA, NA, NA),
#'   stringsAsFactors = FALSE
#' )
#' calcNeSexRatio(ped) # 4 * 1 * 2 / (1 + 2) = 2.666667
calcNeSexRatio <- function(ped) {
  breeders <- getLivingBreeders(ped)
  sex <- ped$sex[match(breeders, ped$id)]
  nMale <- sum(sex == "M", na.rm = TRUE)
  nFemale <- sum(sex == "F", na.rm = TRUE)
  if (nMale == 0L || nFemale == 0L) {
    return(0.0)
  }
  4.0 * nMale * nFemale / (nMale + nFemale)
}