4. Pedigree Analysis and Population Genetics

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

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

This vignette summarizes a practical workflow for pedigree analysis with visPedigree, with emphasis on the interpretation of the main indicators used in breeding and conservation genetics.

The discussion is organized around five questions:

1. How complete and deep is the pedigree?
2. How long is the generation cycle?
3. Has genetic diversity been eroded by unequal founder use, bottlenecks, or drift?
4. How large is the effective population size under different definitions?
5. Are relationship, inbreeding, subpopulation structure, and gene flow under control?

1. Setup and Data Preparation

Different package datasets are used for different analytical tasks.

• deep_ped is useful for pedigree depth and diversity summaries.
• big_family_size_ped contains a Year column and is suitable for generation intervals.
• small_ped is convenient for relationship examples.
• inbred_ped is convenient for inbreeding and classification examples.

library(visPedigree)
library(data.table)

data(deep_ped, package = "visPedigree")
data(big_family_size_ped, package = "visPedigree")
data(small_ped, package = "visPedigree")
data(inbred_ped, package = "visPedigree")

tp_deep <- tidyped(deep_ped)
tp_small <- tidyped(small_ped)
tp_inbred <- tidyped(inbred_ped)

2. Pedigree Overview with pedstats()

pedstats() provides a compact structural summary with three components:

• $summary: pedigree size and parental structure.
• $ecg: pedigree completeness and ancestral depth.
• $gen_intervals: generation intervals, only when a usable time column is available.

Here deep_ped has no explicit birth-date column. Accordingly, pedstats() returns $summary and $ecg, whereas $gen_intervals remains NULL.

stats_deep <- pedstats(tp_deep)

stats_deep$summary
tail(stats_deep$ecg)
stats_deep$gen_intervals

# Visualize ancestral depth (Equivalent Complete Generations)
plot(stats_deep, type = "ecg", metric = "ECG")

Pedigree depth and pedigree time are related but distinct quantities. The former is addressed by pedecg(), whereas the latter is addressed by pedgenint().

3. Pedigree Completeness with pedecg()

Equivalent complete generations (ECG) summarize the amount of ancestral information available for each individual:

$$ ECG_i = \sum_j \left(\frac{1}{2}\right)^{g_{ij}} $$

where $g_{ij}$ is the number of generations between individual $i$ and ancestor $j$. ECG increases with both pedigree depth and pedigree completeness.

In practice:

• ECG combines depth and completeness.
• FullGen counts how many fully known ancestral generations exist.
• MaxGen records the deepest known ancestral path.

ECG is especially useful because it provides the depth adjustment required by realized effective population size estimators based on inbreeding or coancestry.

ecg_deep <- pedecg(tp_deep)

ecg_deep[order(-ECG)][1:10]

4. Generation Intervals with pedgenint()

Generation interval is the age of a parent at the birth of its offspring:

$$ L = t_{offspring} - t_{parent} $$

pedgenint() estimates this quantity for seven pathway summaries:

• SS, SD, DS, DD: sex-specific gametic pathways.
• SO, DO: sex-independent sire-offspring and dam-offspring pathways.
• Average: all parent-offspring pairs combined.

The function accepts Date/POSIXct columns, date strings, or numeric years. When only an integer year is available, it is converted internally to YYYY-07-01 as a mid-year approximation.

tp_time <- tidyped(big_family_size_ped)

genint_year <- pedgenint(tp_time, timevar = "Year", unit = "year")
genint_year

# Visualize generation intervals
# Note: we can also use stats <- pedstats(tp_time, timevar = "Year") followed by plot(stats)
plot(genint_year)

The optional cycle parameter adds GenEquiv, which compares the observed mean interval with a target breeding cycle:

$$ GenEquiv_i = \frac{\bar{L}i}{L{cycle}} $$

Values larger than 1 indicate that the realized generation interval exceeds the target cycle.

genint_cycle <- pedgenint(tp_time, timevar = "Year", unit = "year", cycle = 1.2)

genint_cycle[Pathway %in% c("SS", "SD", "DS", "DD", "Average")]

5. Subpopulation Structure with pedsubpop()

Before interpreting diversity or relationship metrics, it is useful to check whether the pedigree forms a single connected population or a mixture of separate components.

pedsubpop() has two modes:

• by = NULL: summarize disconnected pedigree components.
• by = "...": summarize the pedigree by an existing grouping variable.

ped_demo <- data.table(
  Ind = c("A", "B", "C", "D", "E", "F", "G", "H"),
  Sire = c(NA, NA, "A", NA, NA, "E", NA, NA),
  Dam  = c(NA, NA, "B", NA, NA, NA, NA, NA),
  Sex = c("male", "female", "male", "female", "male", "female", "male", "female"),
  Batch = c("L1", "L1", "L1", "L1", "L2", "L2", "L3", "L3")
)

tp_demo <- tidyped(ped_demo)

pedsubpop(tp_demo)
pedsubpop(tp_demo, by = "Batch")

This is a compact summary tool. When the actual split pedigree objects are needed for downstream analysis, use splitped().

6. Diversity Indicators with pediv()

pediv() is the integrated diversity summary. It combines:

• founder and ancestor contributions (fe, fa),
• founder genome equivalents (fg),
• retained genetic diversity (GeneDiv),
• three effective population size estimates (Ne).

All of these quantities depend on the definition of the reference population. In the present example, the reference population is defined as the most recent two generations in deep_ped.

ref_pop <- tp_deep[Gen >= max(Gen) - 1, Ind]
length(ref_pop)

div_res <- pediv(tp_deep, reference = ref_pop, top = 10, seed = 42L)

div_res$summary
div_res$ancestors

6.1 fe, fa, and fg: what do they measure?

These three indicators describe diversity loss from complementary angles.

Effective number of founders (fe)

$$ f_e = \frac{1}{\sum_{i=1}^{f} p_i^2} $$

where $p_i$ is the expected contribution of founder $i$ to the reference population. fe answers the question: if all founders had contributed equally, how many founders would generate the same diversity?

Use fe when the main concern is unequal founder representation.

Effective number of ancestors (fa)

$$ f_a = \frac{1}{\sum_{j=1}^{a} q_j^2} $$

where $q_j$ is the marginal contribution of ancestor $j$ after removing the contributions already explained by more influential ancestors. fa is usually smaller than fe when bottlenecks occurred.

Use fa when the main concern is genetic bottlenecks caused by a limited set of influential ancestors.

Founder genome equivalents (fg)

In its simplest interpretation,

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

where $\bar{C}$ is the mean coancestry of the reference population. In visPedigree, fg is estimated from a diagonal-corrected mean coancestry:

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

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

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

Use fg when the main concern is the amount of founder genome still surviving after unequal use, bottlenecks, and drift. In practice, fg is often the most conservative diversity indicator.

Retained genetic diversity (GeneDiv)

GeneDiv is the pedigree-based retained genetic diversity of the reference population:

$$ GeneDiv = 1 - \bar{C} $$

where $\bar{C}$ is the same diagonal-corrected mean coancestry used to compute $f_g$. Because coancestry increases as individuals become more related by descent, $GeneDiv$ decreases towards 0 as the population becomes more uniform. An unrelated, non-inbred population has $GeneDiv = 1$; a population of full sibs from two unrelated founders has $GeneDiv \approx 0.75$.

GeneDiv and fg are both derived from $\bar{C}$, but they answer different questions. fg is measured in "equivalent number of founders" and is most useful for between-programme comparisons. GeneDiv is a dimensionless proportion and is easiest to communicate to managers and stakeholders who need a single intuitive index of diversity retention.

# GeneDiv is in the summary alongside MeanCoan
div_res$summary[, .(fg, MeanCoan, GeneDiv)]

6.2 Shannon-entropy effective numbers: feH and faH

The classical fe and fa are based on $\sum p_i^2$ (Hill number order $q = 2$), which is disproportionately influenced by a few large contributions. visPedigree also reports the information-theoretic counterpart at order $q = 1$, derived from Shannon entropy:

$$ f_e^{(H)} = \exp!\Bigl(-\sum_{i=1}^{f} p_i \ln p_i\Bigr), \qquad f_a^{(H)} = \exp!\Bigl(-\sum_{j=1}^{a} q_j \ln q_j\Bigr) $$

All four metrics satisfy a strict monotone ordering:

$$ N_f \ge f_e^{(H)} \ge f_e, \qquad K \ge f_a^{(H)} \ge f_a $$

where $N_f$ is the total number of founders and $K$ is the number of ancestors considered.

Metric guide

| Metric | Order | Sensitivity | What it measures | |---|---|---|---| | fe | $q = 2$ | Dominated by common founders | Effective number of founders if contributions were equalized. Dominated by the largest contributions; many rare founders with small $p_i$ have negligible influence on the metric. | | feH | $q = 1$ | Balanced; sensitive to rare founders | Shannon-entropy effective founders. Counts rare founders more equitably than $q = 2$; always $\ge$ fe. | | fa | $q = 2$ | Dominated by common ancestors | Effective number of ancestors accounting for bottleneck structure. Typically lower than fe. | | faH | $q = 1$ | Balanced; sensitive to rare ancestors | Shannon-entropy effective ancestors. Less dominated by the single most influential ancestor. | | fg | — | Realized coancestry | Founder genome equivalents; the most conservative indicator because it captures drift as well. | | GeneDiv | — | Retained diversity | Pedigree-based retained genetic diversity: $1 - \bar{C}$. Values on the $[0, 1]$ scale; higher values indicate more diversity retained relative to the base population. |

Interpreting the ratio $f_e^{(H)} / f_e$

The ratio $\rho = f_e^{(H)} / f_e$ is a long-tail signal:

• $\rho \approx 1$: founder contributions are already concentrated in a small number of individuals; there is no meaningful "hidden" diversity from minor founders.
• $\rho \gg 1$: many minor founders still carry genetic material into the reference population but are effectively invisible to the classical $f_e$ metric because their contributions are small. This situation is common early in a breeding programme when the pedigree is still shallow.

The analogous ratio $f_a^{(H)} / f_a$ diagnoses the same effect at the ancestor level: a large ratio means that the bottleneck signal from the dominant ancestor is masking genuine contributions from many secondary ancestors.

Management implications

Use the two ratios together to set priorities:

1. If $f_e^{(H)} / f_e$ is large but $f_e$ itself is already high, the programme has good founder coverage; no immediate action needed.
2. If $f_e^{(H)} / f_e$ is large and $f_e$ is low, minor founders carry material that could be mobilized — consider deliberately increasing their representation in the next generation.
3. If $f_a^{(H)} / f_a$ is large, secondary ancestors are still present but marginalized; diversifying sire selection could rebalance the gene pool before their lineages are lost entirely.

# Shannon metrics are included in pediv() output
div_res$summary[, .(NFounder, feH, fe, NAncestor, faH, fa)]

# The ratio feH/fe reveals long-tail founder diversity
div_res$summary[, .(rho_founder = feH / fe, rho_ancestor = faH / fa)]

# pedcontrib() provides the same metrics via its summary
contrib_res <- pedcontrib(tp_deep, reference = ref_pop, mode = "both")
contrib_res$summary[c("n_founder", "f_e_H", "f_e", "n_ancestor", "f_a_H", "f_a")]

7. Diversity Dynamics over Time with pedhalflife()

pediv() provides a static snapshot of diversity. When multiple time points (generations, years, etc.) are available, pedhalflife() tracks how $f_e$, $f_a$, and $f_g$ evolve and fits a log-linear decay model to quantify the rate of diversity loss.

The total loss rate $\lambda_{total}$ is decomposed into three additive components that each have a distinct biological meaning:

| Component | Symbol | Source of loss | |---|---|---| | Foundation | $\lambda_e$ | Unequal founder contributions | | Bottleneck | $\lambda_b$ | Overuse of key ancestors | | Drift | $\lambda_d$ | Random sampling loss |

The diversity half-life is the number of time units for $f_g$ to halve: $$T_{1/2} = \frac{\ln 2}{\lambda_{total}}$$

hl <- pedhalflife(tp_deep, timevar = "Gen")
print(hl)

The printed half-life shows the unit in parentheses — (Gen) here — taken directly from the timevar argument. The full object exposes three components:

• hl$timeseries — per-time-point table (see column guide below).
• hl$decay — single-row table with LambdaE, LambdaB, LambdaD, LambdaTotal, and THalf.
• hl$timevar — the timevar string passed to the call.

7.1 Column guide for $timeseries

The cascade rests on a simple algebraic identity:

$$ \ln f_g = \underbrace{\ln f_e}{\texttt{lnfe}} + \underbrace{\ln!\left(\frac{f_a}{f_e}\right)}{\texttt{lnfafe}} + \underbrace{\ln!\left(\frac{f_g}{f_a}\right)}_{\texttt{lnfgfa}} $$

Because OLS is linear, the slope of $\ln f_g$ versus time equals the sum of the slopes of the three right-hand terms. This guarantees exact additivity: $\lambda_{total} = \lambda_e + \lambda_b + \lambda_d$.

| Column | Formula | What it measures | |---|---|---| | lnfe | $\ln f_e$ | Log effective-founder diversity. Declines when founder contributions become more unequal over time. | | lnfa | $\ln f_a$ | Log effective-ancestor diversity. Lies below lnfe whenever bottleneck ancestors have been over-used. | | lnfg | $\ln f_g$ | Log founder-genome equivalents. The most comprehensive diversity signal; integrates founder use, bottlenecks, and drift. | | lnfafe | $\ln(f_a/f_e)$ | Bottleneck gap. When this ratio decreases over time, a small number of ancestors dominate the gene pool even beyond what unequal founder use would predict. | | lnfgfa | $\ln(f_g/f_a)$ | Drift gap. Captures random allele loss due to finite population size. Because $f_g \le f_a$ always, this term is $\le 0$ and becomes more negative as genetic drift accumulates. | | TimeStep | numeric | OLS time axis (same as Time for numeric timevar; sequential indices otherwise). |

7.2 Interpreting the $\lambda$ components

The negative OLS slope of each log column gives the corresponding loss rate. All three terms have a distinct policy implication:

$\lambda_e$ (Foundation) — rate of increase in founder-contribution inequality. A large $\lambda_e$ suggests that founder representation is still diverging, possibly because some founders are reaching later generations through many more breeding pathways than others. Remedy: broaden founder use in the breeding programme.

$\lambda_b$ (Bottleneck) — rate at which a few key ancestors capture an ever-larger share of the gene pool beyond what founder inequality alone explains. A large $\lambda_b$ points to systematic over-selection of certain families or sires. Remedy: restrict the number of offspring per high-ranking animal; rotate breeding males.

$\lambda_d$ (Drift) — rate of random allele loss in finite populations. This component is always present and increases with small effective population size. It is the only component that cannot be reversed by changing selection decisions; it can only be slowed by maintaining a larger breeding population or by cryopreservation of genetic material.

When $\lambda_d \gg \lambda_e + \lambda_b$ (as in the example above), drift is the dominant driver of diversity loss and should be the primary management target.

7.3 Interpreting $T_{1/2}$

$T_{1/2}$ is the number of time units (generations, years, etc.) required for $f_g$ to fall to half its current value, assuming the observed decay rate continues. It is a single headline figure that combines all three loss channels.

As a rough benchmark: a half-life shorter than five to ten generations is generally considered a cause for concern in conservation and aquaculture genetics. Breed registries and conservation programmes often use $T_{1/2}$ as a threshold indicator for triggering corrective management.

hl$timeseries

To focus on a specific time window, pass the desired values to the at argument:

hl_recent <- pedhalflife(tp_deep, timevar = "Gen",
                         at = tail(sort(unique(tp_deep$Gen)), 4))
print(hl_recent)

Plotting the object shows the log-linear decay of each diversity metric:

plot(hl, type = "log")

A type = "raw" plot shows the equivalent numbers on the original scale:

plot(hl, type = "raw")

8. Effective Population Size with pedne() and pediv()

pediv() reports three complementary effective population size definitions. Each addresses a distinct biological question.

8.1 Demographic Ne

$$ N_e = \frac{4 N_m N_f}{N_m + N_f} $$

where $N_m$ and $N_f$ are the numbers of contributing males and females. This is the easiest estimate to understand, but it ignores realized pedigree structure, inbreeding, and drift. It is therefore often optimistic.

8.2 Inbreeding Ne

$$ \Delta F_i = 1 - (1 - F_i)^{1/(ECG_i - 1)} $$

$$ N_e = \frac{1}{2\overline{\Delta F}} $$

This estimator uses the realized rate of inbreeding. ECG standardizes individuals with different pedigree depths. Use this estimate when the primary concern is the rate of inbreeding accumulation.

8.3 Coancestry Ne

$$ \Delta c_{ij} = 1 - (1 - c_{ij})^{1/(\frac{ECG_i + ECG_j}{2})} $$

$$ N_e = \frac{1}{2\overline{\Delta c}} $$

This estimator is based on the rate of coancestry among members of the reference population. Because it captures the accumulation of relatedness before it is fully expressed as realized inbreeding, it is often the strictest and most sensitive warning signal in managed breeding populations.

9. Average Relationship Trends with pedrel()

pedrel() summarizes pairwise relatedness within groups. Two complementary scales are available via the scale argument.

9.1 Mean additive relationship (scale = "relationship")

The default scale returns the mean off-diagonal additive relationship:

$$ MeanRel = \frac{1}{n(n-1)} \sum_{i \ne j} a_{ij} $$

where $a_{ij} = 2c_{ij}$ is the additive relationship and $c_{ij}$ is the coancestry (kinship coefficient) between individuals $i$ and $j$. A higher MeanRel means that individuals within the group are, on average, more related by descent.

tp_small$BirthYear <- 2010 + tp_small$Gen

rel_by_gen <- pedrel(tp_small, by = "Gen")
rel_by_gen

The reference argument lets you focus on a subset of interest inside each group, such as candidate breeders.

ref_ids <- c("Z1", "Z2", "X", "Y")

pedrel(tp_small, by = "Gen", reference = ref_ids)

9.2 Corrected mean coancestry (scale = "coancestry")

When scale = "coancestry", pedrel() returns the diagonal-corrected population mean coancestry following Caballero & Toro (2000):

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

where $\bar{a}_{off}$ is the mean off-diagonal relationship, $\bar{F}$ is the mean inbreeding coefficient of the group, and $N$ is the group size. This $\bar{C}$ accounts for self-coancestry within the group and matches the internal coancestry quantity used by pediv() to derive $f_g$.

coan_by_gen <- pedrel(tp_small, by = "Gen", scale = "coancestry")
coan_by_gen

Use scale = "relationship" to track mean pairwise relatedness trends. Use scale = "coancestry" when you need a population-level coancestry consistent with diversity metrics from pediv().

pedrel(scale = "coancestry") applies the same diagonal-corrected formula as pediv(). The resulting MeanCoan values are therefore directly comparable to pediv()$summary$MeanCoan, and GeneDiv = 1 - MeanCoan translates the trend table from pedrel() into a retained-diversity timeline without any additional computation.

MeanRel and coancestry-based Ne are conceptually linked, but they are not identical summaries. MeanRel is an average additive relationship within a group, whereas coancestry-based Ne is derived from the rate of increase in coancestry across pedigree depth.

10. Inbreeding Trends with inbreed() and pedfclass()

Wright's inbreeding coefficient $F$ is the probability that the two alleles of an individual are identical by descent. A practical starting point is to inspect the mean trend by generation.

tp_inbred_f <- inbreed(tp_inbred)

f_trend <- tp_inbred_f[, .(MeanF = mean(f, na.rm = TRUE)), by = Gen]
f_trend

For classification by inbreeding severity, pedfclass() can be applied directly to the pedigree object. If the inbreeding coefficient is not yet present, the function computes it internally.

pedfclass(tp_inbred)

Custom reporting thresholds can be supplied through breaks.

pedfclass(tp_inbred, breaks = c(0.03125, 0.0625, 0.125, 0.25))

The default thresholds correspond approximately to familiar pedigree scenarios:

• $F = 0.0625$: half-sib mating.
• $F = 0.125$: avuncular or grandparent-grandchild mating.
• $F = 0.25$: full-sib or parent-offspring mating.

11. Gene Flow and Partial Inbreeding

11.1 pedancestry(): founder-line proportions

pedancestry() tracks how founder groups contribute to later descendants. This is useful when founders are labeled by line, strain, or geographic origin.

ped_line <- data.table(
  Ind = c("A", "B", "C", "D", "E", "F", "G"),
  Sire = c(NA, NA, NA, NA, "A", "C", "E"),
  Dam  = c(NA, NA, NA, NA, "B", "D", "F"),
  Sex = c("male", "female", "male", "female", "male", "female", "male"),
  Line = c("Line1", "Line1", "Line2", "Line2", NA, NA, NA)
)

tp_line <- tidyped(ped_line)

anc <- pedancestry(tp_line, foundervar = "Line")
anc

11.2 pedpartial(): which ancestors explain inbreeding?

pedpartial() decomposes total inbreeding into contributions from selected ancestors. It is useful for identifying which ancestors are most responsible for the observed inbreeding.

partial_f <- pedpartial(tp_inbred, ancestors = c("A", "B"))
partial_f

12. Practical Interpretation

One useful interpretation order is:

1. Check pedigree depth and completeness with pedecg().
2. Check generation timing with pedgenint().
3. Quantify static diversity with fe, fa, fg, and GeneDiv via pediv(); compare with feH and faH to assess long-tail founder value. Use GeneDiv (= $1 - \bar{C}$) as the headline retained-diversity index for management reporting.
4. Track diversity dynamics over time with pedhalflife(). Inspect $\lambda_e$, $\lambda_b$, and $\lambda_d$ to identify the dominant driver of loss; use $T_{1/2}$ as a headline indicator for management reporting.
5. Compare demographic, inbreeding, and coancestry-based Ne.
6. Monitor MeanRel and MeanF over time.
7. Use pedsubpop(), pedancestry(), and pedpartial() to diagnose structure, introgression, and bottlenecks.

References

• Boichard, D., Maignel, L., & Verrier, É. (1997). The value of using probabilities of gene origin to measure genetic variability in a population. Genetics Selection Evolution, 29(1), 5-23.
• Caballero, A., & Toro, M. A. (2000). Interrelations between effective population size and other pedigree tools for the management of conserved populations. Genetical Research, 75(3), 331-343.
• Cervantes, I., Goyache, F., Molina, A., Valera, M., & Gutiérrez, J. P. (2011). Estimation of effective population size from the rate of coancestry in pedigreed populations. Journal of Animal Breeding and Genetics, 128(1), 56-63.
• Gutiérrez, J. P., Cervantes, I., Molina, A., Valera, M., & Goyache, F. (2008). Individual increase in inbreeding allows estimating effective sizes from pedigrees. Genetics Selection Evolution, 40(4), 359-378.
• Gutiérrez, J. P., Cervantes, I., & Goyache, F. (2009). Improving the estimation of realized effective population sizes in farm animals. Journal of Animal Breeding and Genetics, 126(4), 327-332.
• Hill, M. O. (1973). Diversity and evenness: a unifying notation and its consequences. Ecology, 54(2), 427-432.
• Jost, L. (2006). Entropy and diversity. Oikos, 113(2), 363-375.
• Lacy, R. C. (1989). Analysis of founder representation in pedigrees: founder equivalents and founder genome equivalents. Zoo Biology, 8(2), 111-123.
• Wright, S. (1922). Coefficients of inbreeding and relationship. The American Naturalist, 56(645), 330-338.
• Wright, S. (1931). Evolution in Mendelian populations. Genetics, 16(2), 97-159.

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