% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mpm_elasticity.R
\name{mpm_elasticity}
\alias{mpm_elasticity}
\title{Elasticity of \eqn{\lambda} or \ifelse{latex}{\eqn{R_0}}{R0} with respect to entries of \code{matA}}
\usage{
mpm_elasticity(
  matA = NULL,
  matF = NULL,
  matU = NULL,
  matC = NULL,
  framework = c("lambda", "R0"),
  normalize = TRUE,
  tol = 1e-12
)
}
\arguments{
\item{matA}{A square projection matrix (numeric matrix). Required when
\code{framework = "lambda"}. Must be \code{NULL} when \code{framework = "R0"}.}

\item{matF}{A square fecundity/sexual reproduction matrix (numeric matrix).
Required when \code{framework = "R0"}. Must be \code{NULL} when
\code{framework = "lambda"}.}

\item{matU}{A square survival/growth/transition matrix (numeric matrix).
Required when \code{framework = "R0"}. Must be \code{NULL} when
\code{framework = "lambda"}.}

\item{matC}{Optional square clonal reproduction matrix (numeric matrix).
Only allowed when \code{framework = "R0"}.}

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

\item{normalize}{Logical. Must be either \code{TRUE} or \code{FALSE}. This is
relevant only when \code{framework = "R0"}. When true, the elasticity of
\code{"R0"} with respect to the entries of \code{"matA"} are scaled to
sum to 1.}

\item{tol}{Numeric tolerance used for nonnegativity checks. Default \code{1e-12}.}
}
\value{
A list with elements:
\itemize{
  \item \code{framework}: the chosen framework.
  \item \code{elasticity}: a matrix of elasticities with the same dimensionality as
    \code{matA}.
}
}
\description{
Compute elasticities of either the dominant eigenvalue \eqn{\lambda} (\eqn{\lambda}
framework) or the net reproductive rate \eqn{R_0} (\eqn{R_0} framework) with respect
to the entries of the population projection matrix \code{matA}.
}
\details{
The function enforces a strict separation of inputs by framework:
\itemize{
  \item \code{framework = "lambda"}: \code{matA} must be provided and
    \code{matF}, \code{matU}, and \code{matC} must be \code{NULL}.
  \item \code{framework = "R0"}: \code{matF} and \code{matU} must be provided,
    \code{matC} is optional, and \code{matA} must be \code{NULL}. The projection
    matrix is constructed internally as \code{matA = matR + matU}, where
    \code{matR = matF (+ matC)}.
}

Irreducibility of the resulting \code{matA} is enforced using the internal helper
\code{.check_irreducible_hj} (defined elsewhere in the package).

Eigen-elements (e.g., dominant eigenvalue, left and right eigenvectors) are
obtained via the function \code{\link{dominant_eigen}}.


Lambda framework: Elasticity is the elasticity of \eqn{\lambda} with respect
to the entries of \code{matA}.

R0 framework: Elasticity is the elasticity of \eqn{R_0} with respect
to the entries of the internally constructed \code{matA}.
}
\examples{
## Lambda framework: matA provided directly
matA <- matrix(
  c(0.2, 1.2,
    0.3, 0.4),
  nrow = 2, byrow = TRUE
)
out_lambda <- mpm_elasticity(matA = matA, framework = "lambda")
str(out_lambda)

## R0 framework: matA constructed from matF and matU
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
)
out_R0 <- mpm_elasticity(matF = matF, matU = matU, framework = "R0")
str(out_R0)

}
\references{
Caswell, H. (2001). \emph{Matrix population models: construction, analysis and
interpretation} (2nd ed.). Sinauer.
}
\seealso{
\code{\link{dominant_eigen}}, \code{\link{spectral_radius}}
}
