age_from_stage {Rage}

Calculate age-specific traits from a matrix population model

Description

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.

Usage

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.

Value

A vector

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.

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.

Author(s)

Owen R. Jones <[e-mail]>

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

Hal Caswell <[e-mail]>

Patrick Barks <[e-mail]>

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

See Also

lifetable_convert

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

Examples

data(mpm1)

# age-specific survivorship
mpm_to_lx(mpm1$matU)
mpm_to_lx(mpm1$matU, start = 2) # starting from stage 2
mpm_to_lx(mpm1$matU, start = "small") # equivalent using named life stages
mpm_to_lx(mpm1$matU, xmax = 10) # to a maximum age of 10
mpm_to_lx(mpm1$matU, lx_crit = 0.05) # to a minimum lx of 0.05

# age-specific survival probability
mpm_to_px(mpm1$matU)

# age-specific mortality hazard
mpm_to_hx(mpm1$matU)

# age-specific fecundity
mpm_to_mx(mpm1$matU, mpm1$matF)


### 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)
mpm_to_px(mpm1$matU, start = n1)
mpm_to_hx(mpm1$matU, start = n1)
mpm_to_mx(mpm1$matU, mpm1$matF, start = n1)