Rage: mpm_to_table – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

mpm_to_table

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 = 1e-04
)

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 `1e-4`).

Value

A data.frame containing 7-13 columns, depending on input variables. Columns include:

`x`	age.
`lx`	survivorship to start of age class x.
`dx`	proportion of original cohort dying in interval [x, x+1).
`qx`	force of mortality at age x.
`Lx`	survivorship to middle of age class x.
`Tx`	proportion of original cohort alive at age x and beyond.
`ex`	remaining life expectancy at age x.

If matF is provided, also includes:

`mx`	per-capita rate of sexual reproduction at age x.
`lxmx`	expected number of sexual offspring per original cohort member produced at age x.

If matC is provided, also includes:

`cx`	per-capita rate of clonal reproduction at age x.
`lxcx`	expected number of clonal offspring per original cohort member produced at age x.

If both matF and matC are provided, also includes:

`mxcx`	per-capita rate of total reproduction (sexual + clonal) at age x.
`lxmxcx`	expected number of total offspring (sexual + clonal) per original cohort member produced at age x.

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.

Author(s)

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

Hal Caswell <h.caswell@uva.nl>

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

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>

Examples

data(mpm1)

mpm_to_table(matU = mpm1$matU, start = 2, xmax = 15)
mpm_to_table(matU = mpm1$matU, start = "small", xmax = 15)  # equivalent using named life stages
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

Life History Metrics from Matrix Population Models

v1.0.0

GPL-3

Authors

Patrick Barks [aut] (<https://orcid.org/0000-0002-5947-8151>), Danny Buss [ctb], Pol Capdevila [aut] (<https://orcid.org/0000-0002-2842-4302>), Hal Caswell [aut] (<https://orcid.org/0000-0003-4394-6894>), Judy P. Che-Castaldo [aut] (<https://orcid.org/0000-0002-9118-9202>), John Jackson [aut] (<https://orcid.org/0000-0002-4563-2840>), Tamora James [aut] (<https://orcid.org/0000-0003-1363-4742>), Owen Jones [aut, cre] (<https://orcid.org/0000-0001-5720-4686>), Sam Levin [aut] (<https://orcid.org/0000-0002-3289-9925>), William K. Petry [aut] (<https://orcid.org/0000-0002-5230-5987>), Roberto Salguero-Gomez [aut] (<https://orcid.org/0000-0002-6085-4433>), Caroline Schuette [ctb] (<https://orcid.org/0000-0002-2063-8736>), Iain Stott [aut] (<https://orcid.org/0000-0003-2724-7436>), Chelsea C. Thomas [aut] (<https://orcid.org/0000-0002-8155-9353>)

Initial release