% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pedhalflife.R
\name{pedhalflife}
\alias{pedhalflife}
\alias{print.pedhalflife}
\alias{plot.pedhalflife}
\title{Calculate Information-Theoretic Diversity Half-Life}
\usage{
pedhalflife(
  ped,
  timevar = "Gen",
  at = NULL,
  nsamples = 1000,
  ncores = 1,
  seed = NULL
)

\method{print}{pedhalflife}(x, ...)

\method{plot}{pedhalflife}(x, type = c("log", "raw"), ...)
}
\arguments{
\item{ped}{A \code{tidyped} object.}

\item{timevar}{Character.
Column name in \code{ped} that defines time points
(e.g. \code{"Gen"}, \code{"Year"}).  Default: \code{"Gen"}.}

\item{at}{Optional vector of values selecting which time points to include
(e.g., \code{2:4}, \code{2010:2020}, or non-consecutive \code{c(2015, 2018, 2022)}).
Values must match entries in the \code{timevar} column.  Non-numeric values
are accepted but the OLS time axis will fall back to sequential indices.
If \code{NULL} (default), all non-NA unique values in \code{timevar} are used.}

\item{nsamples}{Integer.
Sample size per time point for coancestry estimation
(passed to the internal coancestry engine).  Default: 1000.}

\item{ncores}{Integer.
Number of OpenMP threads for C++ backends.  Default: 1.}

\item{seed}{Integer or \code{NULL}.
Random seed for reproducible coancestry sampling.
Default: \code{NULL}.}

\item{x}{A \code{pedhalflife} object.}

\item{...}{Additional arguments (ignored).}

\item{type}{Character.
\code{"log"} for log-transformed values;
\code{"raw"} for \eqn{f_e}, \eqn{f_a}, \eqn{f_g}.}
}
\value{
A list of class \code{pedhalflife} with two \code{data.table}
  components:
  \describe{
    \item{\code{timeseries}}{Per-time-point tracking with columns
      \code{Time} (time-point label from \code{timevar}), \code{NRef},
      \code{fe}, \code{fa}, \code{fg} and their log transformations
      (\code{lnfe}, \code{lnfa}, \code{lnfg}, \code{lnfafe},
      \code{lnfgfa}), plus \code{TimeStep} (numeric OLS time axis).}
    \item{\code{decay}}{Single-row table with \code{lambda_e},
      \code{lambda_b}, \code{lambda_d}, \code{lambda_total}, and
      \code{thalf}.}
  }
}
\description{
Calculates the diversity half-life (\eqn{T_{1/2}}) of a pedigree across
time points using a Renyi-2 entropy cascade framework.  The total loss rate of
genetic diversity is partitioned into three additive components:
\itemize{
  \item \eqn{\lambda_e}: foundation bottleneck (unequal founder
    contributions).
  \item \eqn{\lambda_b}: breeding bottleneck (overuse of key ancestors).
  \item \eqn{\lambda_d}: genetic drift (random sampling loss).
}

The function rolls over time points defined by \code{timevar}, computing
\eqn{f_e} and \eqn{f_a} (via \code{\link{pedcontrib}}) and \eqn{f_g}
(via the internal matrix-free coancestry engine) for each time point. Only
the \eqn{f_g} statistic is requested; no redundant Ne calculations are
performed.
}
\details{
The mathematical identity underlying the cascade is:
\deqn{\ln f_g = \ln f_e + \ln(f_a / f_e) + \ln(f_g / f_a)}
Taking the negative time-slope of each term gives the \eqn{\lambda}
components, which sum exactly by linearity of OLS:
\deqn{\lambda_{total} = \lambda_e + \lambda_b + \lambda_d}

\eqn{T_{1/2} = \ln 2 / \lambda_{total}} is the number of time-units
(time points, years, generations) for diversity to halve.
}
\examples{
\donttest{
library(visPedigree)
data(simple_ped)
tp <- tidyped(simple_ped)

# 1. Calculate half-life using all available generations
hl <- pedhalflife(tp, timevar = "Gen")
print(hl)

# 2. View the underlying log-linear decay plot
plot(hl, type = "log")

# 3. Calculate half-life for a specific time window (e.g., Generations 2 to 4)
hl_subset <- pedhalflife(tp, timevar = "Gen", at = c(2, 3, 4))
print(hl_subset)
}

}
\seealso{
\code{\link{pediv}}, \code{\link{pedcontrib}}, \code{\link{tidyped}}
}
