% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pedanalysis.R
\name{pedstats}
\alias{pedstats}
\title{Pedigree Statistics}
\usage{
pedstats(
  ped,
  timevar = NULL,
  unit = "year",
  cycle = NULL,
  ecg = TRUE,
  genint = TRUE,
  ...
)
}
\arguments{
\item{ped}{A \code{tidyped} object.}

\item{timevar}{Optional character. Name of the column containing the
\strong{birth date} (or hatch date) of each individual.
Accepted column formats:
\itemize{
  \item \code{Date} or \code{POSIXct} (recommended).
  \item A date string parseable by \code{as.POSIXct}
    (e.g., \code{"2020-06-15"}).  Use \code{format} via \code{...}
    for non-ISO strings.
  \item A numeric year (e.g., \code{2020}).  Automatically converted
    to \code{Date} (\code{"YYYY-07-01"}) with a message.
}
If \code{NULL}, attempts auto-detection from common column names
(\code{"BirthYear"}, \code{"Year"}, \code{"BirthDate"}, etc.).}

\item{unit}{Character. Time unit for reporting generation intervals:
\code{"year"} (default), \code{"month"}, \code{"day"}, or \code{"hour"}.}

\item{cycle}{Numeric. Optional target generation cycle length in
\code{unit}s. When provided, \code{gen_intervals} will include a
\code{GenEquiv} column (observed Mean / cycle). See
\code{\link{pedgenint}} for details.}

\item{ecg}{Logical. Whether to compute equivalent complete generations
for each individual via \code{\link{pedecg}}. Default \code{TRUE}.}

\item{genint}{Logical. Whether to compute generation intervals via
\code{\link{pedgenint}}. Requires a detectable \code{timevar} column.
Default \code{TRUE}.}

\item{...}{Additional arguments passed to \code{\link{pedgenint}},
e.g., \code{format} for custom date parsing or \code{by} for grouping.}
}
\value{
An object of class \code{pedstats}, which is a list containing:
\itemize{
  \item \code{summary}: A \code{data.table} with one row summarising the
    whole pedigree.  Columns:
    \itemize{
      \item \code{N} — total number of individuals.
      \item \code{NSire} — number of unique sires.
      \item \code{NDam} — number of unique dams.
      \item \code{NFounder} — number of founder individuals
        (both parents unknown).
      \item \code{MaxGen} — maximum generation number.
    }
  \item \code{ecg}: A \code{data.table} with one row per individual
    (\code{NULL} if \code{ecg = FALSE}).  Columns:
    \itemize{
      \item \code{Ind} — individual identifier.
      \item \code{ECG} — equivalent complete generations.
      \item \code{FullGen} — number of fully known generations.
      \item \code{MaxGen} — maximum traceable generation depth.
    }
  \item \code{gen_intervals}: A \code{data.table} of generation intervals
    (\code{NULL} if no \code{timevar} is detected or
    \code{genint = FALSE}).  Columns:
    \itemize{
      \item \code{Pathway} — gametic pathway label.  Seven values:
        \code{"SS"} (sire to son), \code{"SD"} (sire to daughter),
        \code{"DS"} (dam to son), \code{"DD"} (dam to daughter) —
        require offspring sex; \code{"SO"} (sire to offspring) and
        \code{"DO"} (dam to offspring) — sex-independent; and
        \code{"Average"} — all parent-offspring pairs combined.
      \item \code{N} — number of parent-offspring pairs.
      \item \code{Mean} — mean generation interval.
      \item \code{SD} — standard deviation of the interval.
      \item \code{GenEquiv} — \code{Mean / cycle} (only present when
        \code{cycle} is supplied).
    }
}
}
\description{
Calculates comprehensive statistics for a pedigree, including population structure,
generation intervals, and ancestral depth.
}
\examples{
\donttest{
# ---- Without time variable ----
tp <- tidyped(simple_ped)
ps <- pedstats(tp)
ps$summary
ps$ecg

# ---- With annual Year column (big_family_size_ped) ----
tp2 <- tidyped(big_family_size_ped)
ps2 <- pedstats(tp2, timevar = "Year")
ps2$summary
ps2$gen_intervals
}

}
