% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pedanalysis.R
\name{pedgenint}
\alias{pedgenint}
\title{Calculate Generation Intervals}
\usage{
pedgenint(
  ped,
  timevar = NULL,
  unit = c("year", "month", "day", "hour"),
  format = NULL,
  cycle = NULL,
  by = NULL
)
}
\arguments{
\item{ped}{A \code{tidyped} object.}

\item{timevar}{Character. The name of the column containing the \strong{birth date}
(or hatch date) of each individual. The column must be one of:
\itemize{
  \item \code{Date} or \code{POSIXct} (recommended).
  \item A date string parseable by \code{as.POSIXct} (e.g., \code{"2020-03-15"}).
    Use \code{format} for non-ISO strings.
  \item A numeric year (e.g., \code{2020}). Automatically converted to
    \code{Date} (\code{"YYYY-07-01"}) with a message. For finer precision,
    convert to \code{Date} beforehand.
}
If \code{NULL}, auto-detects columns named \code{"BirthYear"}, \code{"Year"},
\code{"BirthDate"}, or \code{"Date"}.}

\item{unit}{Character. Output time unit for the interval:
\code{"year"} (default), \code{"month"}, \code{"day"}, or \code{"hour"}.}

\item{format}{Character. Optional format string for parsing \code{timevar}
when it contains non-standard date strings (e.g., \code{"\%d/\%m/\%Y"}
for \code{"15/03/2020"}).}

\item{cycle}{Numeric. Optional target (designed) length of one generation
cycle expressed in \code{unit}s. When provided, an additional column
\code{GenEquiv} is appended to the result, defined as:
\deqn{GenEquiv_i = \frac{\bar{L}_i}{L_{cycle}}}
where \eqn{\bar{L}_i} is the observed mean interval for pathway \eqn{i} and
\eqn{L_{cycle}} is \code{cycle}. A value > 1 means the observed
interval exceeds the target cycle (lower breeding efficiency).
Example: for Pacific white shrimp with a 180-day target cycle, set
\code{unit = "day", cycle = 180}.}

\item{by}{Character. Optional grouping column (e.g., \code{"Breed"}, \code{"Farm"}).
If provided, intervals are calculated within each group.}
}
\value{
A \code{data.table} with columns:
\itemize{
  \item \code{Group}: Grouping level (if \code{by} is used).
  \item \code{Pathway}: One of \code{"SS"}, \code{"SD"}, \code{"DS"}, \code{"DD"},
    \code{"SO"}, \code{"DO"}, or \code{"Average"}.
    SS/SD/DS/DD require offspring sex; SO (Sire-Offspring) and DO (Dam-Offspring)
    are computed from all parent-offspring pairs regardless of offspring sex.
  \item \code{N}: Number of parent-offspring pairs used.
  \item \code{Mean}: Average generation interval in \code{unit}.
  \item \code{SD}: Standard deviation of the interval.
  \item \code{GenEquiv}: (Optional) Generation equivalents based on \code{cycle}.
}
}
\description{
Computes the generation intervals for the four gametic pathways:
Sire to Son (SS), Sire to Daughter (SD), Dam to Son (DS), and Dam to Daughter (DD).
The generation interval is defined as the age of the parents at the birth of their offspring.
}
\details{
Parent-offspring pairs with zero or negative intervals are excluded from
the calculation because they typically indicate data entry errors or
insufficient time resolution. If many zero intervals are expected (e.g.,
when using \code{unit = "year"} with annual spawners), consider using a
finer time unit such as \code{"month"} or \code{"day"}.

Numeric year columns (e.g., \code{2020}) are automatically converted to
\code{Date} by appending \code{"-07-01"} (mid-year) as a reasonable default.
For more precise results, convert to \code{Date} before calling this function.
}
\examples{
\donttest{
# ---- Basic usage with package dataset (numeric Year auto-converted) ----
tped <- tidyped(big_family_size_ped)
gi <- pedgenint(tped, timevar = "Year")
gi

# ---- Generation equivalents with cycle ----
gi2 <- pedgenint(tped, timevar = "Year", cycle = 2)
gi2
}

}
