pediv: Calculate Genetic Diversity Indicators

In visPedigree: Tidying, Analysis, and Fast Visualization of Animal and Plant Pedigrees

Calculate Genetic Diversity Indicators

Description

Combines founder/ancestor contributions ($f_e$, $f_a$) and effective population size estimates (Ne) from three methods into a single summary object.

Usage

pediv(
  ped,
  reference = NULL,
  top = 20,
  nsamples = 1000,
  ncores = 1,
  seed = NULL
)

Arguments

ped	A tidyped object.
reference	Character vector. Optional subset of individual IDs defining the reference population. If NULL, uses all individuals in the most recent generation.
top	Integer. Number of top contributors to return in founder/ancestor tables. Default is 20.
nsamples	Integer. Number of individuals sampled per cohort for the coancestry Ne method and for f_g estimation. Very large cohorts are sampled down to this size to control memory usage (default: 1000).
ncores	Integer. Number of cores for parallel processing in the coancestry method. Default is 1.
seed	Integer or NULL. Random seed passed to set.seed() before sampling in the coancestry method, ensuring reproducible f_g and N_e estimates. Default is NULL (no fixed seed).

Details

Internally calls pedcontrib for f_e and f_a. The coancestry method is called via the internal calc_ne_coancestry() function directly so that f_g and the Ne estimate can be obtained from the same traced pedigree without duplication. The inbreeding and demographic Ne methods are obtained via pedne. All calculations use the same reference population. If any method fails (e.g., insufficient pedigree depth), its value is NA rather than stopping execution.

f_g (founder genome equivalents, Caballero & Toro 2000) is estimated from the diagonal-corrected mean coancestry of the reference population:

\hat{\bar{C}} = \frac{N-1}{N} \cdot \frac{\bar{a}_{off}}{2} + \frac{1 + \bar{F}_s}{2N}

f_g = \frac{1}{2 \hat{\bar{C}}}

where N is the full reference cohort size, \bar{a}_{off} is the off-diagonal mean relationship among sampled individuals, and \bar{F}_s is their mean inbreeding coefficient.

Value

A list with class pediv containing:

• summary: A single-row data.table with columns NRef, NFounder, feH, fe, NAncestor, faH, fa, fafe, fg, MeanCoan, GeneDiv, NSampledCoan, NeCoancestry, NeInbreeding, NeDemographic. Here feH and faH are the Shannon-entropy (q=1) effective numbers of founders and ancestors, respectively. GeneDiv is the pedigree-based retained genetic diversity, computed as 1 - \bar{C}, where \bar{C} is the diagonal-corrected population mean coancestry (MeanCoan).

• founders: A data.table of top founder contributions.

• ancestors: A data.table of top ancestor contributions.

See Also

pedcontrib, pedne, pedstats

Examples

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

visPedigree documentation built on March 30, 2026, 9:07 a.m.