mpm_to_table: Generate a life table from a matrix population model

In Rage: Life History Metrics from Matrix Population Models

Generate a life table from a matrix population model

Description

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

Usage

mpm_to_table(
  matU,
  matF = NULL,
  matC = NULL,
  start = 1L,
  xmax = 1000,
  lx_crit = 0.01,
  radix = 1,
  remove_final = FALSE
)

Arguments

matU	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.
matF	(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.
matC	(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.
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 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).
lx_crit	Minimum value of lx to which age-specific traits will be calculated (defaults to 0.01).
radix	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.
remove_final	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').

Value

A data.frame containing a variable number columns, depending on input variables. Columns include:

x	age at the start of the age interval [x, x+1)
Nx	The number of individuals alive at age x. The initial number is set with radix
Dx	proportion of original cohort dying during the age interval [x, x+1)
lx	survivorship, defined as the proportion of initial cohort surviving to the start of age interval [x, x+1)
dx	proportion of original cohort dying in the age interval [x, x+1)
ax	The average time survived within the interval by those that die during the age interval [x, x+1). Assumed to be 0.5
hx	force of mortality (hazard) during the age interval [x, x+1)
qx	probability of death during the interval [x, x+1) for those entering the interval
px	probability of survival for the interval [x, x+1) for those entering the interval
Lx	total person-years lived during the interval [x, x+1)
Tx	total person years lived beyond age x
ex	remaining life expectancy at age x

If matF is provided, also includes:

mx	per-capita rate of sexual reproduction during the interval [x, x+1)
lxmx	expected number of sexual offspring per original cohort member produced during the interval [x, x+1)

If matC is provided, also includes:

cx	per-capita rate of clonal reproduction during the interval [x, x+1)
lxcx	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:

mxcx	per-capita rate of total reproduction (sexual + clonal) during the interval [x, x+1)
lxmxcx	expected number of total offspring (sexual + clonal) per original cohort member produced during the interval [x, x+1)

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

Note

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.

Author(s)

Owen R. Jones <[e-mail]>

Roberto Salguero-Gómez <[e-mail]>

Hal Caswell <[e-mail]>

References

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

See Also

Other life tables: age_from_stage, lifetable_convert, qsd_converge()

Examples

data(mpm1)

mpm_to_table(matU = mpm1$matU, start = 2, xmax = 15)

# equivalent using named life stages
mpm_to_table(matU = mpm1$matU, start = "small", xmax = 15)
mpm_to_table(matU = mpm1$matU, matF = mpm1$matF, start = 2, xmax = 15)

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

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