% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mpm_aggregate.R
\name{mpm_aggregate}
\alias{mpm_aggregate}
\title{Aggregate a general-to-general matrix population model}
\usage{
mpm_aggregate(
  matA = NULL,
  matU = NULL,
  matF = NULL,
  matC = NULL,
  groups,
  framework = c("lambda", "R0"),
  criterion = c("standard", "elasticity"),
  tol = 1e-12,
  ...
)
}
\arguments{
\item{matA}{Optional projection matrix \eqn{A} (square, finite, nonnegative).
If \code{NULL}, \eqn{A} is constructed as \eqn{U + (F + C)}.}

\item{matU}{Optional survival-transition matrix \eqn{U} (square, finite, nonnegative).
Required when \code{framework = "R0"} and/or when \code{matA} is \code{NULL}.}

\item{matF}{Optional fecundity matrix \eqn{F} (square, finite, nonnegative).
Interpreted as part of reproduction \eqn{R = F + C}.}

\item{matC}{Optional clonal reproduction matrix \eqn{C} (square, finite, nonnegative).
Treated as reproduction and combined with \code{matF} as \eqn{R = F + C}.}

\item{groups}{A non-empty list of integer vectors specifying aggregation
groups. Each stage in \code{1:n} must appear exactly once across the list.}

\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.}

\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{matA_agg}}{Aggregated projection matrix \eqn{A_{\mathrm{agg}}}.}
  \item{\code{matU_agg}}{Aggregated survival-transition matrix \eqn{U_{\mathrm{agg}}}, or \code{NULL} if \code{matU} was not supplied.}
  \item{\code{matF_agg}}{Aggregated fecundity matrix \eqn{F_{\mathrm{agg}}}, or \code{NULL} if \code{matF} was not supplied.}
  \item{\code{matC_agg}}{Aggregated clonal reproduction matrix \eqn{C_{\mathrm{agg}}}, or \code{NULL} if \code{matC} was not supplied.}
  \item{\code{effectiveness}}{Numeric effectiveness measure for the aggregation (definition depends on \code{criterion}).}
}
}
\description{
Aggregates one or more matrix population model (MPM) components from an
\eqn{n \times n} model to an \eqn{m \times m} model by combining stages into
user-defined groups.
}
\details{
Groupings are supplied by \code{groups}, a list of integer vectors specifying
how original stages (1,\dots,n) are combined; see \code{\link{mpm_partition}}.
Each original stage must appear exactly once.

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

Clonal reproduction \code{matC} is treated as reproductive output. When both
\code{matF} and \code{matC} are supplied, the effective reproductive matrix
\eqn{R = F + C} is used internally (e.g., in the \code{"R0"} framework) but is
not returned. The aggregated effective reproduction can be recovered as
\code{matF_agg + matC_agg}.

Irreducibility requirement: The effective projection matrix \eqn{A}
must be nonnegative, square, and irreducible. This function enforces
irreducibility of \eqn{A} as either \code{matA} (if supplied) or
\eqn{A = U + (F + C)} otherwise, and will fail if reducible.


When \code{framework = "R0"}, this function requires \code{matU} and at least one
of \code{matF} or \code{matC} in order to form the effective reproductive matrix
\eqn{R = F + C} and the next generation matrix
\eqn{K = R (I - U)^{-1}}. The matrix \eqn{R} is used internally for computing
reference quantities in the \code{"R0"} framework but is not returned.
The aggregated effective reproduction can be obtained as
\code{matF_agg + matC_agg} when both components are supplied.

All returned matrices are aggregated using the same weighting rules implied by
the selected \code{framework} and \code{criterion}.

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 stage distribution \code{w}.
  \item For \code{criterion = "elasticity"}, effectiveness is computed after
    balancing transformations (with weights based on \code{w * v}).
}
}
\examples{
# Example aggregation of a 3x3 projection matrix to 2x2 using groups:
# group 1 = stage 1; group 2 = stages 2 and 3.
A <- matrix(c(
  0.0, 1.0, 2.0,
  0.5, 0.0, 0.0,
  0.0, 0.8, 0.9
), nrow = 3, byrow = TRUE)

res_std <- mpm_aggregate(
  matA = A,
  groups = list(c(1), c(2, 3)),
  framework = "lambda",
  criterion = "standard"
)
res_std$matA_agg
res_std$effectiveness

res_el <- mpm_aggregate(
  matA = A,
  groups = list(c(1), c(2, 3)),
  framework = "lambda",
  criterion = "elasticity"
)
res_el$matA_agg
res_el$effectiveness

}
\references{
Bienvenu, F., Akcay, E., Legendre, S. and McCandlish, D.M. (2017). The genealogical
decomposition of a matrix population model with applications to the aggregation
of stages. \emph{Theoretical Population Biology}, 115, 69-80.
\doi{10.1016/j.tpb.2017.04.002}

Hooley, D. E. (2000). Collapsed matrices with (almost) the same eigenstuff.
\emph{The College Mathematics Journal}, 31(4), 297-299.
\doi{10.1080/07468342.2000.11974162}

Salguero-Gomez, R. & Plotkin, J. B. (2010). Matrix dimensions bias
demographic inferences: implications for comparative plant demography.
\emph{The American Naturalist}, 176, 710-722. \doi{10.1086/657044}
}
