% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mpmaggregate-package.R
\docType{package}
\name{mpmaggregate-package}
\alias{mpmaggregate}
\alias{mpmaggregate-package}
\title{mpmaggregate: Aggregation of matrix population models}
\description{
\pkg{mpmaggregate} aggregates matrix population models (MPMs) under both the
\eqn{\lambda} (stable population growth rate) and \eqn{R_0} (net reproductive rate)
frameworks, using either standard or elasticity-consistent aggregation.
}
\details{
The package provides methods for aggregating matrix population models while
preserving key demographic quantities under either the \eqn{\lambda} or
\eqn{R_0} framework. Aggregation can be performed using either standard or
elasticity-consistent criteria, depending on whether reproductive values are
to be preserved in addition to growth rates.

\itemize{
  \item \strong{framework = "lambda"}: aggregation targets the dominant eigenvalue
    \eqn{\lambda} and its associated eigenvectors.
  \item \strong{framework = "R0"}: aggregation targets the dominant eigenvalue
    \eqn{R_0} of a next-generation matrix derived from reproductive and
    survival components.
  \item \strong{criterion = "standard"}: preserves \eqn{\lambda} and the stable
    stage distribution (\eqn{\lambda} framework) or \eqn{R_0} and the cohort
    stable stage distribution (\eqn{R_0} framework).
  \item \strong{criterion = "elasticity"}: additionally preserves reproductive
    values (\eqn{\lambda}) or cohort reproductive values (\eqn{R_0} framework).
}

Aggregation is implemented using effective left and right operators,
\eqn{P_{\mathrm{eff}}} and \eqn{Q_{\mathrm{eff}}}, which map an original matrix
\eqn{M} (dimension \eqn{n}) to an aggregated matrix
\eqn{M_{\mathrm{agg}}} (dimension \eqn{m}):
\deqn{M_{\mathrm{agg}} = P_{\mathrm{eff}} \, M \, Q_{\mathrm{eff}}.}

These operators are constructed from the partition matrix \eqn{P} and weights
that depend on the selected framework and criterion.

Aggregation can be performed in two primary settings:
\itemize{
  \item General-to-general matrix population model aggregation via \code{\link{mpm_aggregate}}.
    Groupings are supplied by the user as a list of stage indices (see
    \code{\link{mpm_partition}}).
  \item Leslie-to-Leslie matrix population model aggregation via
    \code{\link{leslie_aggregate}}, which aggregates age classes into cohort
    blocks and may apply a disaggregation step when required.
}

Effectiveness of aggregation measures the quality of an aggregation by how closely the
aggregated model reproduces the behavior of the original model under the chosen
framework and criterion.

The package assumes that inputs are nonnegative matrices and (when required for
computing Perron eigenvectors used in aggregation) that the population projection
matrix is irreducible.
}
\section{Main functions}{

\itemize{
  \item \code{\link{mpm_aggregate}}: general-to-general MPM aggregation using
    user-defined groups of stages.
  \item \code{\link{leslie_aggregate}}: Leslie-to-Leslie MPM aggregation into
    \code{ngroups} contiguous age classes.
  \item \code{\link{generation_time}}: return the generation time in either the
    lambda framework or R0 (cohort-based) framework.
  \item \code{\link{mpm_elasticity}}: 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}.
}
}

\section{Utility functions}{

\itemize{
  \item \code{\link{mpm_partition}}: convert a user-supplied grouping list into a
    partitioning matrix.
  \item \code{\link{spectral_radius}}: compute the spectral radius (dominant
    eigenvalue modulus) of a square matrix.
  \item \code{\link{dominant_eigen}}: return the dominant eigenvalue and
    its associated stable stage distribution and reproductive values for a
    population projection matrix.
  \item \code{\link{leslie_dominant_eigen}}: return the dominant eigenvalue
    and its associated stable age distribution and reproductive values for a Leslie
    population projection matrix.
  \item \code{\link{is_leslie}}: check whether the input matrix is a
    Leslie population projection matrix.
  \item \code{\link{leslie_disaggregate}}: disaggregate a Leslie population projection
    model so that its dimensionality is compatible with that of the aggregated model.
  \item \code{\link{stable_stage}}: return the stable stage distribution (w) associated
    with the dominant eigenvalue, scaled so that \code{sum(w) = 1}.
  \item \code{\link{reproductive_values}}: return the reproductive values (v) associated
    with the dominant eigenvalue, scaled so that \code{sum(v * w) = 1}.
  \item \code{\link{leslie_stable_age}}: return the stable age distribution (w) associated
    with the dominant eigenvalue of a Leslie matrix, scaled so that \code{sum(w) = 1}.
  \item \code{\link{leslie_reproductive_values}}: return the reproductive values (v) associated
    with the dominant eigenvalue of a Leslie matrix, scaled so that \code{sum(v * w) = 1}.
}
}

\references{
Bienvenu, F., Akçay, E., Legendre, S. & 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}

 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}

 Caswell, H. (2001). \emph{Matrix population models: construction, analysis and
 interpretation} (2nd ed.). Sinauer.

 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}

 Salguero-Gómez, R., & Gamelon, M., eds. (2021). \emph{Demographic methods across the
 tree of life}. Oxford University Press.

 Salguero-Gómez, 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}
}
\seealso{
\code{\link{mpm_aggregate}}, \code{\link{leslie_aggregate}}
}
\author{
\strong{Maintainer}: Richard A. Hinrichsen \email{r.hinrichsen.ecology@gmail.com} (\href{https://orcid.org/0000-0003-0761-3005}{ORCID})

Authors:
\itemize{
  \item Roberto Salguero-Gomez \email{rob.salguero@zoo.ox.ac.uk} (\href{https://orcid.org/0000-0002-6085-4433}{ORCID})
  \item Hiroyuki Yokomizo \email{hiroyuki.yokomizo@nies.go.jp} (\href{https://orcid.org/0000-0001-9814-8465}{ORCID})
}

}
