% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/generation_time.R
\name{generation_time}
\alias{generation_time}
\title{Generation time from a matrix population model}
\usage{
generation_time(
  matF,
  matU,
  matC = NULL,
  framework = c("lambda", "R0"),
  tol = 1e-12
)
}
\arguments{
\item{matF}{A square fecundity/sexual reproduction matrix (numeric matrix).
Must not be \code{NULL}.}

\item{matU}{A square survival/growth/transition matrix (numeric matrix).
Must not be \code{NULL}.}

\item{matC}{Optional square clonal reproduction matrix (numeric matrix),
same dimensions as \code{matF} and \code{matU}. Default \code{NULL}.}

\item{framework}{Character scalar. Must be either \code{"lambda"} or \code{"R0"}.}

\item{tol}{Numeric tolerance used for nonnegativity checks and near-zero screening.}
}
\value{
A list with elements:
\itemize{
  \item \code{framework}: the chosen framework (\code{"lambda"} or \code{"R0"}).
  \item \code{generation_time}: generation time (numeric scalar).
}
}
\description{
Returns a generation time for either the \eqn{\lambda} or \eqn{R_0} framework.
}
\details{
The full projection matrix \code{matA} is constructed internally as
\code{matA = matU + matF (+ matC)} and is not accepted as an input because
\code{matA} alone is not sufficient to define the required decomposition.

Eigen-elements (e.g., \eqn{\lambda}, \eqn{R_0}, stable stage distribution,
and reproductive values) are obtained via the function \code{\link{dominant_eigen}}.

If \code{matC} is supplied, the reproductive matrix is defined as
\code{matR = matF + matC}. Otherwise, \code{matR = matF}.

This function performs input validation, constructs \code{matA} and \code{matR},
and sets up the framework-specific branch for computing generation time.
}
\examples{
matU <- matrix(c(0.2, 0.0,
                0.3, 0.4), nrow = 2, byrow = TRUE)
matF <- matrix(c(0.0, 1.2,
                0.0, 0.0), nrow = 2, byrow = TRUE)
generation_time(matF = matF, matU = matU, framework = "lambda")
generation_time(matF = matF, matU = matU, framework = "R0")

}
\references{
Bienvenu, F. & Legendre, S. (2015). A new approach to the generation time in
matrix population models. \emph{The American Naturalist}, 185(6), 834-843.
\doi{10.1086/681104}

Ellner, S. P. (2018). Generation time in structured populations.
\emph{The American Naturalist}, 192(1), 105-110.
\doi{10.1086/697539}
}
\seealso{
\code{\link{dominant_eigen}}, \code{\link{spectral_radius}}.
}
