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)

## Arguments

matU

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.

matR

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.

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.

xmax

Maximum age to which age-specific traits will be calculated (defaults to 1000).

lx_crit

Minimum value of lx to which age-specific traits will be calculated (defaults to 0.01).

tol

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

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.

## 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 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.

## References

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

lifetable_convert

Other life tables: lifetable_convert, mpm_to_table(), qsd_converge()

## Author

Owen R. Jones <jones@biology.sdu.dk>

Roberto Salguero-Gómez <rob.salguero@zoo.ox.ac.uk>

Hal Caswell <h.caswell@uva.nl>

Patrick Barks <patrick.barks@gmail.com>

## Examples

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