These functions use age-from-stage decomposition methods to calculate
age-specific survivorship (lx), survival probability (px),
mortality hazard (hx), or reproduction (mx) from a matrix
population model (MPM). A detailed description of these methods can be found
in sections 5.3.1 and 5.3.2 of Caswell (2001). A separate function
mpm_to_table uses the same methods to calculate a full life
table.
mpm_to_mx(matU, matR, start = 1L, xmax = 1000, lx_crit = 0.01, tol = 1e-04)
mpm_to_lx(matU, start = 1L, xmax = 1000, lx_crit = 0.01, tol = 1e-04)
mpm_to_px(matU, start = 1L, xmax = 1000, lx_crit = 0.01, tol = 1e-04)
mpm_to_hx(matU, start = 1L, xmax = 1000, lx_crit = 0.01, tol = 1e-04)The survival component of a MPM (i.e., a square projection matrix reflecting survival-related transitions; e.g., progression, stasis, and retrogression). Optionally with named rows and columns indicating the corresponding life stage names.
The reproductive component of a MPM (i.e., a square projection matrix reflecting transitions due to reproduction; either sexual, clonal, or both). 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.
Maximum age to which age-specific traits will be calculated
(defaults to 1000).
Minimum value of lx to which age-specific traits will
be calculated (defaults to 0.01).
To account for floating point errors that occasionally lead to
values of lx slightly greater than 1, values of lx within the
open interval (1, 1 + tol) are coerced to 1. Defaults to
0.0001. To prevent coercion, set tol to 0.
A vector
Note that the units of time for the returned vectors (i.e., x)
are the same as the projection interval (ProjectionInterval) of the
MPM.
The output vector is calculated recursively until the age class
(x) reaches xmax or survivorship (lx) falls below
lx_crit, whichever comes first. To force calculation to xmax,
set lx_crit to 0. Conversely, to force calculation to
lx_crit, set xmax to Inf.
Note that the units of time in returned values (i.e., x) are the
same as the projection interval (`ProjectionInterval`) of the MPM.
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 users want to start their
calculation of age-specific traits from reproductive maturity (i.e., first
reproduction), they 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, users should specify argument
start as the desired starting population vector (n1), giving
the proportion of individuals starting in each stage class (the length of
start should match the number of columns in the relevant MPM).
See function mature_distrib for calculating the proportion of
individuals achieving reproductive maturity in each stage class.
Caswell, H. 2001. Matrix Population Models: Construction, Analysis, and Interpretation. Sinauer Associates; 2nd edition. ISBN: 978-0878930968
Jones O. R. 2021. Life tables: Construction and interpretation In: Demographic Methods Across the Tree of Life. Edited by Salguero-Gomez R & Gamelon M. Oxford University Press. Oxford, UK. ISBN: 9780198838609
Preston, S., Heuveline, P., & Guillot, M. 2000. Demography: Measuring and Modeling Population Processes. Wiley. ISBN: 9781557864512
Other life tables:
lifetable_convert,
mpm_to_table(),
qsd_converge()
data(mpm1)
# age-specific survivorship
mpm_to_lx(mpm1$matU)
#> [1] 1.00000000 0.15000000 0.04000000 0.01984000 0.01241465 0.00843715
mpm_to_lx(mpm1$matU, start = 2) # starting from stage 2
#> [1] 1.000000000 0.500000000 0.316800000 0.208613000 0.143913710 0.100583791
#> [7] 0.070696700 0.049775083 0.035066091 0.024708430 0.017411268 0.012269430
#> [13] 0.008646119
mpm_to_lx(mpm1$matU, start = "small") # equivalent using named life stages
#> [1] 1.000000000 0.500000000 0.316800000 0.208613000 0.143913710 0.100583791
#> [7] 0.070696700 0.049775083 0.035066091 0.024708430 0.017411268 0.012269430
#> [13] 0.008646119
mpm_to_lx(mpm1$matU, xmax = 10) # to a maximum age of 10
#> [1] 1.00000000 0.15000000 0.04000000 0.01984000 0.01241465 0.00843715
mpm_to_lx(mpm1$matU, lx_crit = 0.05) # to a minimum lx of 0.05
#> [1] 1.00 0.15 0.04
# age-specific survival probability
mpm_to_px(mpm1$matU)
#> [1] 0.1500000 0.2666667 0.4960000 0.6257384 0.6796124 NA
# age-specific mortality hazard
mpm_to_hx(mpm1$matU)
#> [1] 1.8971200 1.3217558 0.7011794 0.4688229 0.3862326 NA
# age-specific fecundity
mpm_to_mx(mpm1$matU, mpm1$matF)
#> [1] 0.00000 0.00000 9.54125 19.49277 24.83256 26.79977
### starting from first reproduction
repstages <- repro_stages(mpm1$matF)
n1 <- mature_distrib(mpm1$matU, start = 2, repro_stages = repstages)
mpm_to_lx(mpm1$matU, start = n1)
#> [1] 1.000000000 0.675789474 0.448939474 0.312842500 0.219247752 0.154280646
#> [7] 0.108661787 0.076560740 0.053948683 0.038016464 0.026789679 0.018878389
#> [13] 0.013303407 0.009374777
mpm_to_px(mpm1$matU, start = n1)
#> [1] 0.6757895 0.6643185 0.6968478 0.7008247 0.7036818 0.7043125 0.7045783
#> [8] 0.7046521 0.7046783 0.7046862 0.7046889 0.7046897 0.7046900 NA
mpm_to_hx(mpm1$matU, start = n1)
#> [1] 0.3918737 0.4089935 0.3611882 0.3554975 0.3514291 0.3505331 0.3501558
#> [8] 0.3500511 0.3500139 0.3500026 0.3499989 0.3499977 0.3499973 NA
mpm_to_mx(mpm1$matU, mpm1$matF, start = n1)
#> [1] 20.08684 23.58049 26.70449 27.41101 27.72566 27.81222 27.84348 27.85293
#> [9] 27.85610 27.85709 27.85742 27.85752 27.85756 27.85757