R/qsd_converge.R
qsd_converge.RdCalculates the time for a cohort projected with a matrix population model to reach a defined quasi-stationary stage distribution.
qsd_converge(mat, start = 1L, conv = 0.01, N = 100000L)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.
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.
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.
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.
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).
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).
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.
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>
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()
data(mpm1)
# starting stage = 2 (i.e., "small")
qsd_converge(mpm1$matU, start = 2)
#> [1] 6
qsd_converge(mpm1$matU, start = "small") # equivalent using named life stages
#> [1] 6
# convergence threshold = 0.001
qsd_converge(mpm1$matU, start = 2, conv = 0.001)
#> [1] 8
# 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)
#> [1] 5