This function uses age-from-stage decomposition methods to generate a life table from a matrix population model. A detailed description of these methods can be found in section 5.3 "Age-specific traits from stage-specific models" of Caswell (2001).
mpm_to_table(
matU,
matF = NULL,
matC = NULL,
start = 1L,
xmax = 1000,
lx_crit = 0.01,
radix = 1,
remove_final = FALSE
)The survival component of a matrix population model (i.e., a square projection matrix reflecting survival-related transitions; e.g., progression, stasis, and/or retrogression). Optionally with named rows and columns indicating the corresponding life stage names.
(Optional) The sexual component of a matrix population model (i.e., a square projection matrix reflecting transitions due to sexual reproduction). Optionally with named rows and columns indicating the corresponding life stage names.
(Optional) The clonal component of a matrix population model (i.e., a square projection matrix reflecting transitions due to clonal reproduction). 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 the life table will be calculated (defaults
to 1000). Time steps are in the same units as the matrix population
model (see MatrixPeriodicity metadata variable COM(P)ADRE).
Minimum value of lx to which age-specific traits will be
calculated (defaults to 0.01).
The starting number of individuals in the synthetic life table
(defaults to 1). If radix is set to 1, a simplified life
table is produced.
Life table calculations typically assume that the final age class is closed and that all individuals die in that age class. This can mean that mortality/hazard is artificially inflated for this age class. Users can prevent this by setting `remove_final` to `TRUE` (the default is `FALSE`).
A data.frame containing a variable number columns, depending
on input variables. Columns include:
age at the start of the age interval [x, x+1)
The number of individuals alive at age x. The initial number is
set with radix
proportion of original cohort dying during the age interval
[x, x+1)
survivorship, defined as the proportion of initial cohort
surviving to the start of age interval [x, x+1)
proportion of original cohort dying in the age interval [x,
x+1)
The average time survived within the interval by those that die
during the age interval [x, x+1). Assumed to be 0.5
force of mortality (hazard) during the age interval [x,
x+1)
probability of death during the interval [x, x+1) for
those entering the interval
probability of survival for the interval [x, x+1) for
those entering the interval
total person-years lived during the interval [x, x+1)
total person years lived beyond age x
remaining life expectancy at age x
If matF is provided, also includes:
per-capita rate of sexual reproduction during the interval
[x, x+1)
expected number of sexual offspring per original
cohort member produced during the interval [x, x+1)
If matC is provided, also includes:
per-capita rate of clonal reproduction during the interval
[x, x+1)
expected number of clonal offspring per original
cohort member produced during the interval [x, x+1)
If both matF and matC are provided, also includes:
per-capita rate of total reproduction (sexual + clonal) during
the interval [x, x+1)
expected number of total offspring (sexual + clonal) per
original cohort member produced during the interval [x, x+1)
The life table 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 = 0. Conversely, to force calculation to lx_crit, set
xmax = Inf.
The life table calculations assume that the final age interval is
closed and that all remaining individuals die in this interval. Therefore,
for this interval, the probability of death qx is 1, the probability
of survival px is 0 and, because we assume that deaths are evenly
distributed during the interval, the remaining life expectancy for
individuals at the start of the interval is 0.5. Depending on analyses, it
may be a good idea to remove the final row of the table.
If lx_crit is sufficiently small that only a very small proportion
of the cohort reach this age (i.e., < 0.05), this should have minimal
impact on results. Nevertheless, for many analyses, the final row of the
life table should be treated with caution and perhaps removed from
subsequent analyses.
Note that the units of time (e.g.. `x` and `ex`) in the returned life table 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 the user wants to start the calculation of age-specific
traits from reproductive maturity (i.e., first reproduction), the user
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 (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
Caswell, H. 2006. Applications of Markov chains in demography. pp. 319-334 in A.N. Langville and W.J. Stewart (editors) MAM2006: Markov Anniversary Meeting. Boson Books, Raleigh, North Caroline, USA
Horvitz, C. & Tuljapurkar, S. 2008. Stage dynamics, period survival, and mortality plateaus. The American Naturalist 172: 203-2015. <doi:10.1086/589453>
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>
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:
age_from_stage,
lifetable_convert,
qsd_converge()
data(mpm1)
mpm_to_table(matU = mpm1$matU, start = 2, xmax = 15)
#> x lx dx hx qx px ex
#> 1 0 1.000000000 0.500000000 0.6666667 0.5000000 0.5000000 1.988484
#> 2 1 0.500000000 0.183200000 0.4485798 0.3664000 0.6336000 2.476967
#> 3 2 0.316800000 0.108187000 0.4118170 0.3414994 0.6585006 2.620213
#> 4 3 0.208613000 0.064699290 0.3670604 0.3101403 0.6898597 2.719759
#> 5 4 0.143913710 0.043329919 0.3544406 0.3010826 0.6989174 2.717696
#> 6 5 0.100583791 0.029887091 0.3489842 0.2971363 0.7028637 2.673045
#> 7 6 0.070696700 0.020921617 0.3473281 0.2959348 0.7040652 2.591702
#> 8 7 0.049775083 0.014708992 0.3467418 0.2955091 0.7044909 2.470893
#> 9 8 0.035066091 0.010357661 0.3465577 0.2953754 0.7046246 2.297613
#> 10 9 0.024708430 0.007297162 0.3464964 0.2953309 0.7046691 2.051164
#> 11 10 0.017411268 0.005141838 0.3464769 0.2953167 0.7046833 1.701265
#> 12 11 0.012269430 0.003623311 0.3464705 0.2953121 0.7046879 1.204688
#> 13 12 0.008646119 0.008646119 2.0000000 1.0000000 0.0000000 0.500000
# equivalent using named life stages
mpm_to_table(matU = mpm1$matU, start = "small", xmax = 15)
#> x lx dx hx qx px ex
#> 1 0 1.000000000 0.500000000 0.6666667 0.5000000 0.5000000 1.988484
#> 2 1 0.500000000 0.183200000 0.4485798 0.3664000 0.6336000 2.476967
#> 3 2 0.316800000 0.108187000 0.4118170 0.3414994 0.6585006 2.620213
#> 4 3 0.208613000 0.064699290 0.3670604 0.3101403 0.6898597 2.719759
#> 5 4 0.143913710 0.043329919 0.3544406 0.3010826 0.6989174 2.717696
#> 6 5 0.100583791 0.029887091 0.3489842 0.2971363 0.7028637 2.673045
#> 7 6 0.070696700 0.020921617 0.3473281 0.2959348 0.7040652 2.591702
#> 8 7 0.049775083 0.014708992 0.3467418 0.2955091 0.7044909 2.470893
#> 9 8 0.035066091 0.010357661 0.3465577 0.2953754 0.7046246 2.297613
#> 10 9 0.024708430 0.007297162 0.3464964 0.2953309 0.7046691 2.051164
#> 11 10 0.017411268 0.005141838 0.3464769 0.2953167 0.7046833 1.701265
#> 12 11 0.012269430 0.003623311 0.3464705 0.2953121 0.7046879 1.204688
#> 13 12 0.008646119 0.008646119 2.0000000 1.0000000 0.0000000 0.500000
mpm_to_table(matU = mpm1$matU, matF = mpm1$matF, start = 2, xmax = 15)
#> x lx dx hx qx px ex mx
#> 1 0 1.000000000 0.500000000 0.6666667 0.5000000 0.5000000 1.988484 0.00000
#> 2 1 0.500000000 0.183200000 0.4485798 0.3664000 0.6336000 2.476967 15.26600
#> 3 2 0.316800000 0.108187000 0.4118170 0.3414994 0.6585006 2.620213 22.00578
#> 4 3 0.208613000 0.064699290 0.3670604 0.3101403 0.6898597 2.719759 25.84823
#> 5 4 0.143913710 0.043329919 0.3544406 0.3010826 0.6989174 2.717696 27.13917
#> 6 5 0.100583791 0.029887091 0.3489842 0.2971363 0.7028637 2.673045 27.62496
#> 7 6 0.070696700 0.020921617 0.3473281 0.2959348 0.7040652 2.591702 27.78025
#> 8 7 0.049775083 0.014708992 0.3467418 0.2955091 0.7044909 2.470893 27.83270
#> 9 8 0.035066091 0.010357661 0.3465577 0.2953754 0.7046246 2.297613 27.84948
#> 10 9 0.024708430 0.007297162 0.3464964 0.2953309 0.7046691 2.051164 27.85497
#> 11 10 0.017411268 0.005141838 0.3464769 0.2953167 0.7046833 1.701265 27.85673
#> 12 11 0.012269430 0.003623311 0.3464705 0.2953121 0.7046879 1.204688 27.85730
#> 13 12 0.008646119 0.008646119 2.0000000 1.0000000 0.0000000 0.500000 27.85749
#> lxmx
#> 1 0.0000000
#> 2 7.6330000
#> 3 6.9714300
#> 4 5.3922778
#> 5 3.9056986
#> 6 2.7786231
#> 7 1.9639717
#> 8 1.3853752
#> 9 0.9765725
#> 10 0.6882526
#> 11 0.4850211
#> 12 0.3417932
#> 13 0.2408592
### starting from first reproduction
repStages <- repro_stages(mpm1$matF)
n1 <- mature_distrib(matU = mpm1$matU, start = 2, repro_stages = repStages)
mpm_to_table(matU = mpm1$matU, start = n1)
#> x lx dx hx qx px ex
#> 1 0 1.000000000 0.324210526 0.3869347 0.3242105 0.6757895 2.656634
#> 2 1 0.675789474 0.226850000 0.4033861 0.3356815 0.6643185 2.691281
#> 3 2 0.448939474 0.136096974 0.3573121 0.3031522 0.6968478 2.798539
#> 4 3 0.312842500 0.093594748 0.3518003 0.2991753 0.7008247 2.798480
#> 5 4 0.219247752 0.064967107 0.3478563 0.2963182 0.7036818 2.779679
#> 6 5 0.154280646 0.045618859 0.3469874 0.2956875 0.7043125 2.739645
#> 7 6 0.108661787 0.032101047 0.3466214 0.2954217 0.7045783 2.679903
#> 8 7 0.076560740 0.022612057 0.3465199 0.2953479 0.7046521 2.593911
#> 9 8 0.053948683 0.015932218 0.3464838 0.2953217 0.7046783 2.471554
#> 10 9 0.038016464 0.011226786 0.3464729 0.2953138 0.7046862 2.297807
#> 11 10 0.026789679 0.007911290 0.3464692 0.2953111 0.7046889 2.051216
#> 12 11 0.018878389 0.005574982 0.3464681 0.2953103 0.7046897 1.701278
#> 13 12 0.013303407 0.003928629 0.3464677 0.2953100 0.7046900 1.204690
#> 14 13 0.009374777 0.009374777 2.0000000 1.0000000 0.0000000 0.500000