% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pedanalysis.R
\name{pedcontrib}
\alias{pedcontrib}
\title{Calculate Founder and Ancestor Contributions}
\usage{
pedcontrib(
  ped,
  reference = NULL,
  mode = c("both", "founder", "ancestor"),
  top = 20
)
}
\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{mode}{Character. Type of contribution to calculate:
\itemize{
  \item \code{"founder"}: Founder contributions ($f_e$).
  \item \code{"ancestor"}: Ancestor contributions ($f_a$).
  \item \code{"both"}: Both founder and ancestor contributions.
}}

\item{top}{Integer. Number of top contributors to return. Default is 20.}
}
\value{
A list with class \code{pedcontrib} containing:
\itemize{
  \item \code{founders}: A \code{data.table} of founder contributions (if mode includes "founder", or "both").
  \item \code{ancestors}: A \code{data.table} of ancestor contributions (if mode includes "ancestor", or "both").
  \item \code{summary}: A \code{list} of summary statistics including:
    \itemize{
      \item \code{f_e}: Classical effective number of founders (\eqn{q=2}, Lacy 1989).
      \item \code{f_e_H}: Information-theoretic effective number of founders
        (\eqn{q=1}, Shannon entropy): \eqn{f_e^{(H)} = \exp(-\sum p_i \ln p_i)}.
      \item \code{f_a}: Classical effective number of ancestors (\eqn{q=2}, Boichard 1997).
      \item \code{f_a_H}: Information-theoretic effective number of ancestors
        (\eqn{q=1}): \eqn{f_a^{(H)} = \exp(-\sum q_k \ln q_k)}.
    }
}

Each contribution table contains:
\itemize{
  \item \code{Ind}: Individual ID.
  \item \code{Contrib}: Contribution to the reference population (0-1).
  \item \code{CumContrib}: Cumulative contribution.
  \item \code{Rank}: Rank by contribution.
}
}
\description{
Calculates genetic contributions from founders and influential ancestors.
Implements the gene dropping algorithm for founder contributions and Boichard's 
algorithm for ancestor contributions to estimate the effective number of founders ($f_e$) 
and ancestors ($f_a$).
}
\details{
**Founder Contributions ($f_e$):**
Calculated by probabilistic gene flow from founders to the reference cohort. 
When individual ancestors with one unknown parent exist, "phantom" parents are temporarily injected correctly conserving the probability mass.

**Ancestor Contributions ($f_a$):**
Calculated using Boichard's iterative algorithm (1997), accounting for:
\itemize{
  \item Marginal genetic contribution of each ancestor
  \item Long-term contributions through multiple pathways
}
The parameter $f_a$ acts as a stringent metric since it identifies the bottlenecks of genetic variation in pedigrees.
}
\examples{
\donttest{
library(data.table)
# Load a sample pedigree
tp <- tidyped(small_ped)

# Calculate both founder and ancestor contributions for reference population
ref_ids <- c("Z1", "Z2", "X", "Y")
contrib <- pedcontrib(tp, reference = ref_ids, mode = "both")

# Print results including f_e, f_e(H), f_a, and f_a(H)
print(contrib)

# Access Shannon-entropy effective numbers directly
contrib$summary$f_e_H   # Information-theoretic effective founders (q=1)
contrib$summary$f_e     # Classical effective founders (q=2)
contrib$summary$f_a_H   # Information-theoretic effective ancestors (q=1)
contrib$summary$f_a     # Classical effective ancestors (q=2)

# Diversity ratio rho > 1 indicates long-tail founder value
contrib$summary$f_e_H / contrib$summary$f_e
}

}
\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.
}
