% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/leslie_aggregate.R
\name{leslie_aggregate}
\alias{leslie_aggregate}
\title{Aggregate Leslie-to-Leslie matrix population model}
\usage{
leslie_aggregate(
  matA,
  ngroups,
  framework = c("lambda", "R0"),
  criterion = c("standard", "elasticity"),
  tol = 1e-12,
  ...
)
}
\arguments{
\item{matA}{A square numeric matrix. Must be finite, nonnegative, and satisfy
the structural constraints of a Leslie matrix (checked internally).}

\item{ngroups}{Positive integer giving the number of aggregated age groups
(the dimension \eqn{m} of the aggregated model). Must satisfy \code{ngroups <= n}.}

\item{framework}{Character scalar; either \code{"lambda"} or \code{"R0"}.
Determines whether aggregation is based on the projection matrix \eqn{A}
or an \eqn{R_0}-based reference matrix built from the implied \eqn{U} and
reproductive component of the Leslie matrix.}

\item{criterion}{Character scalar; either \code{"standard"} for standard aggregation
or \code{"elasticity"} for elasticity-consistent aggregation.}

\item{tol}{Numeric tolerance used in positivity/zero-mass checks and balancing
calculations for the elasticity-consistent case.}

\item{...}{Reserved for future use.}
}
\value{
A named list with elements:
\describe{
  \item{\code{framework}}{The matched framework used (\code{"lambda"} or \code{"R0"}).}
  \item{\code{criterion}}{The matched criterion used (\code{"standard"} or \code{"elasticity"}).}
  \item{\code{matAk_agg}}{Aggregated \eqn{k}-step Leslie matrix (\eqn{m \times m}).}
  \item{\code{effectiveness}}{A numeric effectiveness measure for the aggregation (definition depends on \code{criterion}).}
}
}
\description{
Aggregates a Leslie matrix into a smaller Leslie matrix with \code{ngroups}
contiguous age classes.
}
\details{
This function assumes the input is a valid Leslie matrix and checks the Leslie
structure internally. If the original dimensionality \eqn{n} is not an integer
multiple of \eqn{m}, a disaggregation step is applied internally so that the
expanded dimensionality is divisible by \eqn{m} before aggregation proceeds.

Aggregation can be performed under two frameworks (\code{"lambda"} or \code{"R0"})
and two criteria (\code{"standard"} or \code{"elasticity"}), which determine how
age classes are weighted during aggregation.

Irreducibility requirement: The input Leslie matrix \code{matA} must be
irreducible. This function checks irreducibility of \code{matA} and will fail
if it is reducible. (Any internal disaggregation preserves irreducibility.)


The Leslie matrix is internally decomposed into a reproductive component \eqn{R}
(the first row) and a survival component \eqn{U} (the subdiagonal and any survival
terms implied by the Leslie structure). For \code{framework = "R0"}, the
next-generation matrix \eqn{K = R (I - U)^{-1}} is formed and its dominant
eigenvalue is used as \eqn{R_0}.

Aggregation proceeds on a \eqn{k}-step matrix where \eqn{k = n/m},
with \eqn{n} the dimension of the input Leslie matrix and
\eqn{m =} \code{ngroups}. The function returns an
\eqn{m \times m} \eqn{k}-step Leslie matrix (stored as
\code{matAk_agg}) describing transitions among the aggregated age classes.

Effectiveness measures how closely the aggregated model reproduces the behavior
of the original model under the chosen \code{framework} and \code{criterion}. When
\code{effectiveness} is high (close to 1), applying the original model and then
aggregating gives nearly the same result as aggregating first and then applying the
aggregated model.

The returned element \code{effectiveness} is computed for both criteria:
\itemize{
  \item For \code{criterion = "standard"}, effectiveness is computed using weights
    based on the reference stable age distribution \code{w}.
  \item For \code{criterion = "elasticity"}, effectiveness is computed after
    balancing transformations (with weights based on \code{w * v}).
}
}
\examples{
# A simple 3x3 Leslie matrix (fertility rates in first row; survival probabilities on subdiagonal)
A <- matrix(c(
  0.0, 1.2, 1.8,
  0.5, 0.0, 0.0,
  0.0, 0.7, 0.0
), nrow = 3, byrow = TRUE)

# Aggregate to 2 age groups
res_std <- leslie_aggregate(
  matA = A,
  ngroups = 2,
  framework = "lambda",
  criterion = "standard"
)
res_std$matAk_agg
res_std$effectiveness

res_el <- leslie_aggregate(
  matA = A,
  ngroups = 2,
  framework = "lambda",
  criterion = "elasticity"
)
res_el$matAk_agg
res_el$effectiveness

}
\references{
Hinrichsen, R. A. (2023). Aggregation of Leslie matrix models with application to
ten diverse animal species. \emph{Population Ecology}, 65(3), 146-166.
\doi{10.1002/1438-390X.12149}

Hinrichsen, R. A., Yokomizo, H., & Salguero-Gómez, R. (2026). From theory to
application: Elasticity-consistent aggregation of Leslie matrix population
models for comparative demography. \emph{bioRxiv}, preprint.
\doi{10.64898/2026.02.04.703802}
}
