% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pedanalysis.R
\name{pediv}
\alias{pediv}
\title{Calculate Genetic Diversity Indicators}
\usage{
pediv(
  ped,
  reference = NULL,
  top = 20,
  nsamples = 1000,
  ncores = 1,
  seed = NULL
)
}
\arguments{
\item{ped}{A \code{tidyped} object.}

\item{reference}{Character vector. Optional subset of individual IDs defining the reference population.
If NULL, uses all individuals in the most recent generation.}

\item{top}{Integer. Number of top contributors to return in founder/ancestor tables. Default is 20.}

\item{nsamples}{Integer. Number of individuals sampled per cohort for the coancestry
Ne method and for \eqn{f_g} estimation. Very large cohorts are sampled down to this
size to control memory usage (default: 1000).}

\item{ncores}{Integer. Number of cores for parallel processing in the coancestry method. Default is 1.}

\item{seed}{Integer or NULL. Random seed passed to \code{set.seed()} before sampling
in the coancestry method, ensuring reproducible \eqn{f_g} and \eqn{N_e} estimates.
Default is \code{NULL} (no fixed seed).}
}
\value{
A list with class \code{pediv} containing:
\itemize{
  \item \code{summary}: A single-row \code{data.table} with columns
    \code{NRef}, \code{NFounder}, \code{feH}, \code{fe}, \code{NAncestor},
    \code{faH}, \code{fa}, \code{fafe}, \code{fg}, \code{MeanCoan},
    \code{GeneDiv}, \code{NSampledCoan}, \code{NeCoancestry}, \code{NeInbreeding},
    \code{NeDemographic}.
    Here \code{feH} and \code{faH} are the Shannon-entropy (\eqn{q=1})
    effective numbers of founders and ancestors, respectively.
    \code{GeneDiv} is the pedigree-based retained genetic diversity,
    computed as \eqn{1 - \bar{C}}, where \eqn{\bar{C}} is the
    diagonal-corrected population mean coancestry (\code{MeanCoan}).
  \item \code{founders}: A \code{data.table} of top founder contributions.
  \item \code{ancestors}: A \code{data.table} of top ancestor contributions.
}
}
\description{
Combines founder/ancestor contributions ($f_e$, $f_a$) and effective population
size estimates (Ne) from three methods into a single summary object.
}
\details{
Internally calls \code{\link{pedcontrib}} for \eqn{f_e} and \eqn{f_a}.
The coancestry method is called via the internal \code{calc_ne_coancestry()}
function directly so that \eqn{f_g} and the Ne estimate can be obtained from
the same traced pedigree and the same batched matrix-free relationship
products without duplication.
The inbreeding and demographic Ne methods are obtained via \code{\link{pedne}}.
All calculations use the same \code{reference} population.
If any method fails (e.g., insufficient pedigree depth), its value is \code{NA}
rather than stopping execution.

\eqn{f_g} (founder genome equivalents, Caballero & Toro 2000) is estimated from
the diagonal-corrected mean coancestry of the reference population:
\deqn{\hat{\bar{C}} = \frac{N-1}{N} \cdot \frac{\bar{a}_{off}}{2} + \frac{1 + \bar{F}_s}{2N}}
\deqn{f_g = \frac{1}{2 \hat{\bar{C}}}}
where \eqn{N} is the full reference cohort size, \eqn{\bar{a}_{off}} is the
off-diagonal mean relationship among sampled individuals, and \eqn{\bar{F}_s}
is their mean inbreeding coefficient.
}
\examples{
\donttest{
tp <- tidyped(small_ped)
div <- pediv(tp, reference = c("Z1", "Z2", "X", "Y"), seed = 42L)
print(div)

# Access Shannon effective numbers from summary
div$summary$feH   # Shannon effective founders (q=1)
div$summary$faH   # Shannon effective ancestors (q=1)

# Founder diversity profile: NFounder >= feH >= fe
with(div$summary, c(NFounder = NFounder, feH = feH, fe = fe))
}

}
\seealso{
\code{\link{pedcontrib}}, \code{\link{pedne}}, \code{\link{pedstats}}
}
