R/life_expect.R
life_expect.RdApplies Markov chain approaches to obtain mean and variance of life expectancy from a matrix population model (MPM).
life_expect_mean(matU, mixdist = NULL, start = 1L)
life_expect_var(matU, mixdist = NULL, start = 1L)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.
A vector with a length equal to the dimension of the MPM defining how the function should average the output over the. possible starting states. See section Starting from multiple stages. If this argument is used, `start` must be set to `NULL`.
The index (or stage name) of the first stage of the life cycle
which the user considers to be the beginning of life. Defaults to 1.
If set to `NULL` the function returns mean life expectancy from each of the
stages of the MPM.
Returns life expectancy in the units of the projection interval
(`ProjectionInterval`) of the MPM. If matU is singular (often
indicating infinite life expectancy), returns NA.
Sometimes, it is necessary to calculate life expectancy considering multiple starting stage classes instead of just a single stage from which all individuals begin their lives. This scenario arises when there are several possible stages at which an individual can start a particular life event, such as reproductive maturity. To handle such cases, the function provides support for multiple starting stage classes. When calculating life expectancy in this context, the outputs should be averaged using weights determined by the distribution of individuals across these stages. To achieve this, the `start` argument should be set to `NULL`, indicating that the starting stage is not specified, and the `mixdist` argument should be utilized. In the context described, The `mixdist` argument expects a vector that represents the proportion of individuals with their first reproduction in each stage of the MPM. By providing this distribution, the function calculates the mean lifespan by appropriately weighting the life expectancies corresponding to each starting stage. For a practical example that demonstrates this usage, please refer to the code example below.
Caswell, H. 2001. Matrix Population Models: Construction, Analysis, and Interpretation. Sinauer Associates; 2nd edition. ISBN: 978-0878930968
Other life history traits:
entropy_d(),
entropy_k_age(),
entropy_k_stage(),
entropy_k(),
gen_time(),
life_elas(),
longevity(),
net_repro_rate(),
repro_maturity,
shape_rep(),
shape_surv()
data(mpm1)
# mean life expectancy starting from stage class 2
life_expect_mean(mpm1$matU, start = 2)
#> [1] 2.509116
# equivalent using named life stages
life_expect_mean(mpm1$matU, start = "small")
#> [1] 2.509116
# mean life expectancies starting from each of the stages
life_expect_mean(mpm1$matU, start = NULL)
#> seed small medium large dormant
#> 1.250506 2.509116 3.103368 4.061429 2.142828
# mean life expectancy starting from first reproduction, where this varies
# across individuals
rep_stages <- repro_stages(mpm1$matF)
(n1 <- mature_distrib(mpm1$matU, start = 2, repro_stages = rep_stages))
#> seed small medium large dormant
#> 0.00000000 0.00000000 0.92105263 0.07894737 0.00000000
life_expect_mean(mpm1$matU, mixdist = n1, start = NULL)
#> [1] 3.179005
# variance of life expectancy from stage class 1
life_expect_var(mpm1$matU, start = 1)
#> [1] 0.7816213
# variance of life expectancy from stage class 1
life_expect_var(mpm1$matU, start = "seed")
#> [1] 0.7816213
# variance of life expectancy from each stage class
life_expect_var(mpm1$matU, start = NULL)
#> seed small medium large dormant
#> 0.7816213 5.9010591 7.3974919 8.6697104 4.8607628
# variance of life expectancies with a set mixing distribution
life_expect_var(mpm1$matU, mixdist = c(0.0, 0.1, 0.3, 0.1, 0.5), start = NULL)
#> [1] 6.498089
# setting mixdist to ignore all but one stage should produce the same result
# as setting the start argument to that stage
life_expect_mean(mpm1$matU, start = 3)
#> [1] 3.103368
life_expect_mean(mpm1$matU, mixdist = c(0, 0, 1, 0, 0), start = NULL)
#> [1] 3.103368