R/entropy_k_stage.R
entropy_k_stage.RdComputes the discrete-time Keyfitz entropy for a stage-based (Lefkovitch) matrix
population model using the **U** submatrix. This implementation follows the
life-disparity / life-expectancy formulation (H_N) adapted to stage models (H_N^+):
it projects survivorship directly from Umat and quantifies the dispersion of
**ages at death** (in projection steps) relative to mean life expectancy.
entropy_k_stage(Umat, init_distrib = NULL, max_age = NULL, n_is_maxage = FALSE)A square numeric matrix representing the U submatrix of a stage-based (Lefkovitch) matrix population model.
The initial cohort distribution across stages. This should sum to 1. If it does not sum to 1, the function rescales it to 1. Defaults to an equal distribution across stages.
The upper age, in units of the projection interval. Defaults to 1000 if no information is provided.
If TRUE, survival p_n is set to zero. Defaults to FALSE.
Returns a single numeric value representing the Keyfitz entropy for the given matrix. This value quantifies the dispersion of age at death (not stage at death).
Interpretation. Values reflect the shape of mortality across age:
\(H < 1\): increasing mortality with age (senescence)
\(H = 1\): approximately age-constant mortality
\(H > 1\): decreasing mortality with age (negative senescence)
The function avoids age-from-stage preprocessing by obtaining survivorship
from successive powers of \(U\) up to max_age. In pure age-class
(Leslie) models with \(k\) age classes and no persistence in the terminal
class, using max_age = k recovers the exact discrete-time value.
The result depends on the starting cohort init_distrib (e.g., all
recruits, a single stage, or recruits at equilibrium). Choose init_distrib
to match the biological question.
Keyfitz, N. 1977. Applied Mathematical Demography. New York: Wiley. Giaimo S. 2024. Discretising and validating Keyfitz entropy for any demographic classification. Methods in Ecology and Evolution. 15, 1278–1285.
Other life history traits:
entropy_d(),
entropy_k(),
entropy_k_age(),
gen_time(),
life_elas(),
life_expect_mean(),
longevity(),
net_repro_rate(),
repro_maturity,
shape_rep(),
shape_surv(),
stage_at_death_dist()
data(mpm1)
entropy_k_stage(mpm1$matU)
#> [1] 1.131567