qsd_converge: Calculate time to reach quasi-stationary stage distribution

In Rage: Life History Metrics from Matrix Population Models

Calculate time to reach quasi-stationary stage distribution

Description

Calculates the time for a cohort projected with a matrix population model to reach a defined quasi-stationary stage distribution.

Usage

qsd_converge(mat, start = 1L, conv = 0.01, N = 100000L)

Arguments

mat	A matrix population model, or component thereof (i.e., a square projection matrix). Optionally with named rows and columns indicating the corresponding life stage names.
start	The index (or stage name) of the first stage at which the author considers the beginning of life. Defaults to 1. Alternately, a numeric vector giving the starting population vector (in which case length(start) must match ncol(matU)). See section Starting from multiple stages.
conv	Proportional distance threshold from the stationary stage distribution indicating convergence. For example, this value should be 0.01 if the user wants to obtain the time step when the stage distribution is within a distance of 1% of the stationary stage distribution.
N	Maximum number of time steps over which the population will be projected. Time steps are in the same units as the matrix population model (see AnnualPeriodicity column in COM(P)ADRE metadata). Defaults to 100,000.

Details

Some matrix population models are parameterised with a stasis loop at the largest/most-developed stage class, which can lead to artefactual plateaus in the mortality or fertility trajectories derived from such models. These plateaus occur as a projected cohort approaches its stationary stage distribution (SSD). Though there is generally no single time point at which the SSD is reached, we can define a quasi-stationary stage distribution (QSD) based on a given distance threshold from the SSD, and calculate the number of time steps required for a cohort to reach the QSD. This quantity can then be used to subset age trajectories of mortality or fertility to periods earlier than the QSD, so as to avoid artefactual plateaus in mortality or fertility.

Starting from multiple stages

Rather than specifying argument start as a single stage class from which all individuals start life, it may sometimes be desirable to allow for multiple starting stage classes. For example, if we want to start our calculation of QSD from reproductive maturity (i.e., first reproduction), we should account for the possibility that there may be multiple stage classes in which an individual could first reproduce.

To specify multiple starting stage classes, specify argument start as the desired starting population vector, giving the proportion of individuals starting in each stage class (the length of start should match the number of columns in the relevant MPM).

Value

An integer indicating the first time step at which the quasi-stationary stage distribution is reached (or an NA and a warning if the quasi-stationary distribution is not reached).

Note

The time required for a cohort to reach its QSD depends on the initial population vector of the cohort (for our purposes, the starting stage class), and so does not fundamentally require an ergodic matrix (where the long-term equilibrium traits are independent of the initial population vector). However, methods for efficiently calculating the stationary stage distribution (SSD) generally do require ergodicity.

If the supplied matrix (mat) is non-ergodic, qsd_converge first checks for stage classes with no connection (of any degree) from the starting stage class specified by argument start, and strips such stages from the matrix. These unconnected stages have no impact on age-specific traits that we might derive from the matrix (given the specified starting stage), but often lead to non-ergodicity and therefore prevent the reliable calculation of SSD. If the reduced matrix is ergodic, the function internally updates the starting stage class and continues with the regular calculation. Otherwise, if the matrix cannot be made ergodic, the function will return NA with a warning.

Author(s)

Hal Caswell <[e-mail]>

Owen Jones <[e-mail]>

Roberto Salguero-Gomez <[e-mail]>

Patrick Barks <[e-mail]>

References

Caswell, H. 2001. Matrix Population Models: Construction, Analysis, and Interpretation. Sinauer Associates; 2nd edition. ISBN: 978-0878930968

Horvitz, C. C., & Tuljapurkar, S. 2008. Stage dynamics, period survival, and mortality plateaus. The American Naturalist, 172(2), 203–215.

Jones, O. R., Scheuerlein, A., Salguero-Gomez, R., Camarda, C. G., Schaible, R., Casper, B. B., Dahlgren, J. P., Ehrlén, J., García, M. B., Menges, E., Quintana-Ascencio, P. F., Caswell, H., Baudisch, A. & Vaupel, J. 2014. Diversity of ageing across the tree of life. Nature 505, 169-173. <doi:10.1038/nature12789>

Salguero-Gomez R. 2018. Implications of clonality for ageing research. Evolutionary Ecology, 32, 9-28. <doi:10.1007/s10682-017-9923-2>

See Also

mature_distrib for calculating the proportion of individuals achieving reproductive maturity in each stage class.

Other life tables: age_from_stage, lifetable_convert, mpm_to_table()

Examples

data(mpm1)

# starting stage = 2 (i.e., "small")
qsd_converge(mpm1$matU, start = 2)
qsd_converge(mpm1$matU, start = "small") # equivalent using named life stages

# convergence threshold = 0.001
qsd_converge(mpm1$matU, start = 2, conv = 0.001)

# starting from first reproduction
repstages <- repro_stages(mpm1$matF)
n1 <- mature_distrib(mpm1$matU, start = 2, repro_stages = repstages)
qsd_converge(mpm1$matU, start = n1)

Rage documentation built on Sept. 30, 2023, 1:06 a.m.