Type:	Package
Title:	Aggregate Matrix Population Models
Version:	0.2.5
Date:	2026-03-30
Author:	Richard A. Hinrichsen [aut, cre], Roberto Salguero-Gomez [aut], Hiroyuki Yokomizo [aut]
Maintainer:	Richard A. Hinrichsen <r.hinrichsen.ecology@gmail.com>
Description:	Aggregates matrix population models (MPMs) in both the lambda (stable growth rate) and R0 (net reproductive rate) frameworks, including standard and elasticity-consistent aggregators. Standard aggregation in the lambda framework maintains consistent lambda and stable stage distribution, while standard aggregation in the R0 framework maintains consistent R0 and cohort stable stage distribution. Elasticity-consistent aggregators maintain these same consistencies with respect to the chosen framework and additionally preserve consistent reproductive values in the lambda framework and cohort reproductive values in the R0 framework. Aggregation can take the form of general-to-general MPM (mpm_aggregate) or Leslie-to-Leslie MPM (leslie_aggregate).
License:	MIT + file LICENSE
Encoding:	UTF-8
Imports:	expm
Suggests:	testthat (≥ 3.0.0), roxygen2, knitr, rmarkdown, Rcompadre, kableExtra, rphylopic, collidr, png
Config/testthat/edition:	3
VignetteBuilder:	knitr
RoxygenNote:	7.3.3
Depends:	R (≥ 3.5)
LazyData:	true
NeedsCompilation:	no
Packaged:	2026-03-31 03:36:50 UTC; Rich
Repository:	CRAN
Date/Publication:	2026-04-03 09:10:02 UTC

mpmaggregate: Aggregation of matrix population models

Description

mpmaggregate aggregates matrix population models (MPMs) under both the \lambda (stable population growth rate) and 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 \lambda or 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.

• framework = "lambda": aggregation targets the dominant eigenvalue \lambda and its associated eigenvectors.

• framework = "R0": aggregation targets the dominant eigenvalue R_0 of a next-generation matrix derived from reproductive and survival components.

• criterion = "standard": preserves \lambda and the stable stage distribution (\lambda framework) or R_0 and the cohort stable stage distribution (R_0 framework).

• criterion = "elasticity": additionally preserves reproductive values (\lambda) or cohort reproductive values (R_0 framework).

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

M_{\mathrm{agg}} = P_{\mathrm{eff}} \, M \, Q_{\mathrm{eff}}.

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

Aggregation can be performed in two primary settings:

• General-to-general matrix population model aggregation via mpm_aggregate. Groupings are supplied by the user as a list of stage indices (see mpm_partition).

• Leslie-to-Leslie matrix population model aggregation via 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.

Main functions

• mpm_aggregate: general-to-general MPM aggregation using user-defined groups of stages.

• leslie_aggregate: Leslie-to-Leslie MPM aggregation into ngroups contiguous age classes.

• generation_time: return the generation time in either the lambda framework or R0 (cohort-based) framework.

• mpm_elasticity: compute elasticities of either the dominant eigenvalue \lambda (\lambda framework) or the net reproductive rate R_0 (R_0 framework) with respect to the entries of the population projection matrix matA.

Utility functions

• mpm_partition: convert a user-supplied grouping list into a partitioning matrix.

• spectral_radius: compute the spectral radius (dominant eigenvalue modulus) of a square matrix.

• dominant_eigen: return the dominant eigenvalue and its associated stable stage distribution and reproductive values for a population projection matrix.

• leslie_dominant_eigen: return the dominant eigenvalue and its associated stable age distribution and reproductive values for a Leslie population projection matrix.

• is_leslie: check whether the input matrix is a Leslie population projection matrix.

• leslie_disaggregate: disaggregate a Leslie population projection model so that its dimensionality is compatible with that of the aggregated model.

• stable_stage: return the stable stage distribution (w) associated with the dominant eigenvalue, scaled so that sum(w) = 1.

• reproductive_values: return the reproductive values (v) associated with the dominant eigenvalue, scaled so that sum(v * w) = 1.

• leslie_stable_age: return the stable age distribution (w) associated with the dominant eigenvalue of a Leslie matrix, scaled so that sum(w) = 1.

• leslie_reproductive_values: return the reproductive values (v) associated with the dominant eigenvalue of a Leslie matrix, scaled so that sum(v * w) = 1.

Author(s)

Maintainer: Richard A. Hinrichsen r.hinrichsen.ecology@gmail.com (ORCID)

Authors:

• Roberto Salguero-Gomez rob.salguero@zoo.ox.ac.uk (ORCID)

• Hiroyuki Yokomizo hiroyuki.yokomizo@nies.go.jp (ORCID)

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. 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. The American Naturalist, 185(6), 834-843. doi:10.1086/681104

Caswell, H. (2001). 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. 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. bioRxiv, preprint. doi:10.64898/2026.02.04.703802

Salguero-Gómez, R., & Gamelon, M., eds. (2021). 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. The American Naturalist, 176, 710-722. doi:10.1086/657044

See Also

mpm_aggregate, leslie_aggregate

Greatest common divisor of a set of integers

Description

Computes the greatest common divisor (GCD) of a numeric vector x of positive integers. Used by LCM.

Usage

GCD(x)

Arguments

Value

A positive integer giving the GCD of x.

Least common multiple of two integers

Description

Computes the least common multiple (LCM) of two positive integers. Used by leslie_disaggregate.

Usage

LCM(a, b)

Arguments

Value

A positive integer giving the LCM of a and b.

Dominant eigen-elements of a population projection matrix

Description

Returns the dominant eigenvalue and its associated right/left eigenvectors (stable stage distribution w and reproductive values v) for a square population projection matrix A.

Usage

dominant_eigen(A, tol = 1e-12, ensure_positive = TRUE)

Arguments

Details

The output is normalized using the conventions in stable_stage and reproductive_values:

• w is scaled so that sum(w) = 1

• v is scaled so that sum(v * w) = 1

Value

A named list with elements:

• lambda: spectral radius of A

• w: stable stage distribution (right eigenvector), sum(w)=1

• v: reproductive values (left eigenvector), sum(v*w)=1

References

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

See Also

spectral_radius, stable_stage, reproductive_values

Examples

A <- matrix(c(
  0,   1,   2,
  0.5, 0,   0,
  0,   0.8, 0.9
), nrow = 3, byrow = TRUE)

dom <- dominant_eigen(A)
dom$lambda
sum(dom$w)
sum(dom$v * dom$w)

Generation time from a matrix population model

Description

Returns a generation time for either the \lambda or R_0 framework.

Usage

generation_time(
  matF,
  matU,
  matC = NULL,
  framework = c("lambda", "R0"),
  tol = 1e-12
)

Arguments

Details

The full projection matrix matA is constructed internally as matA = matU + matF (+ matC) and is not accepted as an input because matA alone is not sufficient to define the required decomposition.

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

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

This function performs input validation, constructs matA and matR, and sets up the framework-specific branch for computing generation time.

Value

A list with elements:

• framework: the chosen framework ("lambda" or "R0").

• generation_time: generation time (numeric scalar).

References

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

Ellner, S. P. (2018). Generation time in structured populations. The American Naturalist, 192(1), 105-110. doi:10.1086/697539

See Also

dominant_eigen, spectral_radius.

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")

Test whether a matrix is a Leslie matrix

Description

Checks whether a matrix A has Leslie form: nonzero entries are allowed only in the first row (fertility rates) and on the subdiagonal (survival probabilities). Survival probabilities must be in (0, 1] (within tolerance), fertility rates must be nonnegative, and at least one fertility rate must be positive.

Usage

is_leslie(A, tol = sqrt(.Machine$double.eps))

Arguments

Details

A 1x1 matrix with a positive entry is treated as a valid (degenerate) Leslie matrix.

Value

Logical; TRUE if A is a Leslie matrix, otherwise FALSE.

Examples

L <- matrix(c(
  0, 2, 1,
  0.6, 0, 0,
  0, 0.7, 0
), nrow = 3, byrow = TRUE)
is_leslie(L)

Aggregate Leslie-to-Leslie matrix population model

Description

Aggregates a Leslie matrix into a smaller Leslie matrix with ngroups contiguous age classes.

Usage

leslie_aggregate(
  matA,
  ngroups,
  framework = c("lambda", "R0"),
  criterion = c("standard", "elasticity"),
  tol = 1e-12,
  ...
)

Arguments

Details

This function assumes the input is a valid Leslie matrix and checks the Leslie structure internally. If the original dimensionality n is not an integer multiple of m, a disaggregation step is applied internally so that the expanded dimensionality is divisible by m before aggregation proceeds.

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

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

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

Aggregation proceeds on a k-step matrix where k = n/m, with n the dimension of the input Leslie matrix and m = ngroups. The function returns an m \times m k-step Leslie matrix (stored as 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 framework and criterion. When 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 effectiveness is computed for both criteria:

• For criterion = "standard", effectiveness is computed using weights based on the reference stable age distribution w.

• For criterion = "elasticity", effectiveness is computed after balancing transformations (with weights based on w * v).

Value

A named list with elements:

framework

The matched framework used ("lambda" or "R0").

criterion

The matched criterion used ("standard" or "elasticity").

matAk_agg

Aggregated k-step Leslie matrix (m \times m).

effectiveness

A numeric effectiveness measure for the aggregation (definition depends on criterion).

References

Hinrichsen, R. A. (2023). Aggregation of Leslie matrix models with application to ten diverse animal species. 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. bioRxiv, preprint. doi:10.64898/2026.02.04.703802

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

Disaggregate a Leslie matrix population model to a compatible dimensionality

Description

Expands an n \times n Leslie matrix A to an n_{new} \times n_{new} Leslie matrix, where n_{new} = \mathrm{LCM}(n, m).

Usage

leslie_disaggregate(A, m)

Arguments

Details

Disaggregation is required when aggregating a Leslie model to dimensionality m whenever m does not divide n evenly. The expanded matrix introduces a finer age structure that is compatible with both dimensionalities.

Each original age class is subdivided into n_{new} / n sub-classes. Fertility rates from original age class i are placed at the end of the corresponding block, deterministic aging within blocks is represented by ones on the subdiagonal, and original survival probabilities are inserted at block boundaries.

Value

A Leslie matrix of dimensionality n_{new} \times n_{new}, where n_{new} = \mathrm{LCM}(n, m).

References

Hinrichsen, R. A. (2023). Aggregation of Leslie matrix models with application to ten diverse animal species. 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. bioRxiv, preprint. doi:10.64898/2026.02.04.703802

Examples

L <- matrix(c(
  0, 2, 1,
  0.6, 0, 0,
  0, 0.7, 0
), nrow = 3, byrow = TRUE)
leslie_disaggregate(L, m = 2)

Dominant eigen-elements of a Leslie matrix

Description

Returns the dominant eigenvalue (\lambda) and the stable age distribution w and reproductive values v for a Leslie matrix A.

Usage

leslie_dominant_eigen(A)

Arguments

Details

Normalization: The output is normalized using the conventions in leslie_stable_age and leslie_reproductive_values

• w is scaled so that sum(w) = 1

• v is scaled so that sum(v * w) = 1

Value

A named list with elements:

• lambda: spectral radius of A

• w: stable age distribution, sum(w)=1

• v: reproductive values, sum(v*w)=1

References

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

Demetrius, L. (1974). Demographic parameters and natural selection. Proceedings of the National Academy of Sciences, 71(12), 4645-4647. doi:10.1073/pnas.71.12.4645

See Also

spectral_radius, leslie_stable_age, leslie_reproductive_values

Examples

leslie_dominant_eigen(1)

L <- matrix(c(
  0, 2, 1,
  0.6, 0, 0,
  0, 0.7, 0
), nrow = 3, byrow = TRUE)
dom <- leslie_dominant_eigen(L)
dom$lambda
sum(dom$w)
sum(dom$v * dom$w)

Reproductive values for a Leslie matrix

Description

Computes the reproductive value vector v for a Leslie matrix A, scaled so that sum(v * w) = 1, where w is the stable age distribution returned by leslie_stable_age.

Usage

leslie_reproductive_values(A)

Arguments

Details

This implementation follows Demetrius (1974) equation expressed in terms of the stable age distribution and fertility rates.

A length-1 positive numeric is treated as a 1x1 Leslie matrix and returns 1.

Value

A numeric vector of length nrow(A) giving reproductive values, normalized so that sum(v * w) = 1.

References

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

Demetrius, L. (1974). Demographic parameters and natural selection. Proceedings of the National Academy of Sciences, 71(12), 4645-4647. doi:10.1073/pnas.71.12.4645

Examples

leslie_reproductive_values(1)

L <- matrix(c(
  0, 2, 1,
  0.6, 0, 0,
  0, 0.7, 0
), nrow = 3, byrow = TRUE)
v <- leslie_reproductive_values(L)
w <- leslie_stable_age(L)
sum(v * w)  # should be 1

Stable age distribution for a Leslie matrix

Description

Computes the stable age distribution for a Leslie matrix A using the standard recursion based on subdiagonal survival probabilities and the dominant eigenvalue. The output is scaled so that sum(w) = 1.

Usage

leslie_stable_age(A)

Arguments

Details

A length-1 positive numeric is treated as a 1x1 Leslie matrix and returns 1.

Value

A numeric vector of length nrow(A) giving the stable age distribution, scaled so that sum(w) = 1.

References

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

Demetrius, L. (1974). Demographic parameters and natural selection. Proceedings of the National Academy of Sciences, 71(12), 4645-4647. doi:10.1073/pnas.71.12.4645

Examples

leslie_stable_age(1)

L <- matrix(c(
  0, 2, 1,
  0.6, 0, 0,
  0, 0.7, 0
), nrow = 3, byrow = TRUE)
leslie_stable_age(L)

Coarse-scale Asian elephant projection matrix

Description

A female-only projection matrix for an Asian elephant population, included with the package for examples and vignettes. The matrix has dimension 12 × 12 and a projection interval of 5 years.

Usage

matA_elephant1

Format

A numeric matrix with 12 rows and 12 columns.

Details

Population/model ID: 249273 — a coarser model with a 5-year projection interval for the Nagarhole National Park elephant population in India (Chelliah et al., 2013).

The matrix was originally retrieved from the COMADRE Animal Matrix Database using the 'Rcompadre' package and bundled with this package so examples and vignettes can run without requiring internet access.

Source

COMADRE Animal Matrix Database, MatrixID 249273.

References

Chelliah, K., Bukka, H., & Sukumar, R. (2013). Modeling harvest rates and numbers from age and sex ratios: a demonstration for elephant populations. Biological Conservation, 165, 54–61. doi:10.1016/j.biocon.2013.05.008

Fine-scale Asian elephant projection matrix

Description

A female-only projection matrix for an Asian elephant population, included with the package for examples and vignettes. The matrix has dimension 60 × 60 and a projection interval of 1 year.

Usage

matA_elephant2

Format

A numeric matrix with 60 rows and 60 columns.

Details

Population/model ID: 249274 — a fine-grained model with a 1-year projection interval for the Periyar Reserve elephant population in India (Goswami et al., 2014).

The matrix was originally retrieved from the COMADRE Animal Matrix Database using the 'Rcompadre' package and bundled with this package so examples and vignettes can run without requiring internet access. The final entry was zeroed out so that the matrix is a true Leslie matrix.

Source

COMADRE Animal Matrix Database, MatrixID 249274.

References

Goswami, V. R., Vasudev, D., & Oli, M. K. (2014). The importance of conflict-induced mortality for conservation planning in areas of human–elephant co-occurrence. Biological Conservation, 176, 191–198. doi:10.1016/j.biocon.2014.05.026

Aggregate a general-to-general matrix population model

Description

Aggregates one or more matrix population model (MPM) components from an n \times n model to an m \times m model by combining stages into user-defined groups.

Usage

mpm_aggregate(
  matA = NULL,
  matU = NULL,
  matF = NULL,
  matC = NULL,
  groups,
  framework = c("lambda", "R0"),
  criterion = c("standard", "elasticity"),
  tol = 1e-12,
  ...
)

Arguments

Details

Groupings are supplied by groups, a list of integer vectors specifying how original stages (1,...,n) are combined; see mpm_partition. Each original stage must appear exactly once.

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

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

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

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

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

Effectiveness measures how closely the aggregated model reproduces the behavior of the original model under the chosen framework and criterion. When 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 effectiveness is computed for both criteria:

• For criterion = "standard", effectiveness is computed using weights based on the reference stable stage distribution w.

• For criterion = "elasticity", effectiveness is computed after balancing transformations (with weights based on w * v).

Value

A named list with elements:

framework

The matched framework used ("lambda" or "R0").

criterion

The matched criterion used ("standard" or "elasticity").

matA_agg

Aggregated projection matrix A_{\mathrm{agg}}.

matU_agg

Aggregated survival-transition matrix U_{\mathrm{agg}}, or NULL if matU was not supplied.

matF_agg

Aggregated fecundity matrix F_{\mathrm{agg}}, or NULL if matF was not supplied.

matC_agg

Aggregated clonal reproduction matrix C_{\mathrm{agg}}, or NULL if matC was not supplied.

effectiveness

Numeric effectiveness measure for the aggregation (definition depends on criterion).

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. 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. 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. The American Naturalist, 176, 710-722. doi:10.1086/657044

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

Elasticity of \lambda or R0 with respect to entries of matA

Description

Compute elasticities of either the dominant eigenvalue \lambda (\lambda framework) or the net reproductive rate R_0 (R_0 framework) with respect to the entries of the population projection matrix matA.

Usage

mpm_elasticity(
  matA = NULL,
  matF = NULL,
  matU = NULL,
  matC = NULL,
  framework = c("lambda", "R0"),
  normalize = TRUE,
  tol = 1e-12
)

Arguments

Details

The function enforces a strict separation of inputs by framework:

• framework = "lambda": matA must be provided and matF, matU, and matC must be NULL.

• framework = "R0": matF and matU must be provided, matC is optional, and matA must be NULL. The projection matrix is constructed internally as matA = matR + matU, where matR = matF (+ matC).

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

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

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

R0 framework: Elasticity is the elasticity of R_0 with respect to the entries of the internally constructed matA.

Value

A list with elements:

• framework: the chosen framework.

• elasticity: a matrix of elasticities with the same dimensionality as matA.

References

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

See Also

dominant_eigen, spectral_radius

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)

Create a partitioning matrix for MPM aggregation

Description

Builds a 0/1 partitioning matrix P that maps an n-stage model to an m-stage aggregated model by summing specified original stages within each aggregated stage.

Usage

mpm_partition(groups, n = NULL)

Arguments

Details

The grouping is provided as a list of integer vectors. For example, groups = list(c(1), c(2:3)) defines m = 2 aggregated stages: the first contains original stage 1, and the second contains original stages 2 and 3.

Each original stage index 1:n must appear exactly once across groups.

Value

A numeric matrix P of dimensionality m x n with entries 0 or 1.

Examples

g <- list(c(1), c(2:3))
P <- mpm_partition(g, n = 3)
P

Compute reproductive values

Description

Returns the reproductive value vector v for a square nonegative matrix A, defined as the left eigenvector associated with the dominant eigenvalue (spectral radius). The vector is normalized in the usual demographic way so that sum(v * w) = 1, where w is the stable stage distribution returned by stable_stage.

Usage

reproductive_values(A, tol = 1e-12, ensure_positive = TRUE)

Arguments

Details

For matrix population models with nonegative irreducible matrix, reproductive values are strictly positive (up to scaling).

Value

A numeric vector of length nrow(A) giving reproductive values, scaled so that sum(v * w) = 1.

References

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

Examples

#irreducible example
A <- matrix(c(
  0, 1,
  0.5, 0
), nrow = 2, byrow = TRUE)

w <- stable_stage(A)
v <- reproductive_values(A)
v
sum(v * w)  # should be 1

Compute the spectral radius of a matrix

Description

Returns the spectral radius of a square matrix, defined as the maximum modulus of its eigenvalues:

\rho(A) = \max |\lambda_i|

Usage

spectral_radius(A)

Arguments

Details

This function is primarily intended for use with matrix population models, where the spectral radius corresponds to the stable growth rate (i.e., \lambda) when the governing matrix is square and nonnegative. It is also used to calculate net reproductive rate R_0 from a next generation matrix.

Value

A single numeric value giving the spectral radius of A.

References

Horn, R. A. and Johnson, C. R. (2013). Matrix analysis. Cambridge University Press.

Examples

A <- matrix(c(
  0, 1,
  0.5, 0
), nrow = 2, byrow = TRUE)

spectral_radius(A)

Compute the stable stage distribution

Description

Returns the stable stage distribution for a square nonnegative matrix A, defined as the right eigenvector associated with the dominant eigenvalue. The returned vector w is normalized so that sum(w) = 1.

Usage

stable_stage(A, tol = 1e-12, ensure_positive = TRUE)

Arguments

Details

For matrix population models with nonegative irreducible matrix, stable stage densities are strictly positive.

Value

A numeric vector of length nrow(A) giving the stable stage distribution, normalized to sum to 1.

References

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

Examples

#irreducible example
A <- matrix(c(
  0, 1,
  0.5, 0
), nrow = 2, byrow = TRUE)

w <- stable_stage(A)
w
sum(w)