LifeTable

models.LifeTable(ages, rates)

Piecewise-constant mortality rates by age, sampled by inversion.

Parameters

Name	Type	Description	Default
ages	ArrayLike	Start age of each band, strictly increasing. Band i runs from ages[i] to ages[i + 1]; the last band has no upper end.	required
rates	ArrayLike	Annual mortality rate in each band, positive, same length as ages.	required

Example

import numpy as np from heormodel.models import LifeTable table = LifeTable(ages=[0.0, 60.0], rates=[0.01, 0.1]) round(table.life_expectancy(60.0), 1) 10.0 rng = np.random.default_rng(7) t = table.sample_time_to_death(rng, np.full(4000, 60.0)) bool(abs(t.mean() - 10.0) < 0.5) True

Methods

Name	Description
cumulative_hazard	Cumulative mortality hazard from the first table age to each age.
life_expectancy	Remaining life expectancy at an age, exact for the piecewise rates.
rate	Annual mortality rate at each age.
sample_time_to_death	Sample years until death for individuals of the given ages.

cumulative_hazard

models.LifeTable.cumulative_hazard(age)

Cumulative mortality hazard from the first table age to each age.

Example

from heormodel.models import LifeTable float(LifeTable(ages=[0.0, 60.0], rates=[0.01, 0.1]).cumulative_hazard(70.0)) 1.6

life_expectancy

models.LifeTable.life_expectancy(age, *, hazard_ratio=1.0)

Remaining life expectancy at an age, exact for the piecewise rates.

Integrates the survival function band by band, so it is the analytic mean of sample_time_to_death and a direct check on simulated death times.

Example

from heormodel.models import LifeTable LifeTable(ages=[0.0], rates=[0.02]).life_expectancy(30.0) 50.0

rate

models.LifeTable.rate(age)

Annual mortality rate at each age.

Example

from heormodel.models import LifeTable LifeTable(ages=[0.0, 60.0], rates=[0.01, 0.1]).rate([30.0, 75.0]).tolist() [0.01, 0.1]

sample_time_to_death

models.LifeTable.sample_time_to_death(rng, age, *, hazard_ratio=1.0)

Sample years until death for individuals of the given ages.

Draws by inverting the cumulative hazard: the time to death t solves hr * (H(age + t) - H(age)) = e with e standard exponential, so each draw is conditional on having survived to age. The hazard ratio scales the whole remaining hazard, the proportional-hazards form used for excess disease mortality.

Parameters

Name	Type	Description	Default
rng	np.random.Generator	Random generator supplying the exponential draws.	required
age	ArrayLike	Current age of each individual, at or above the first table age.	required
hazard_ratio	ArrayLike	Multiplier on the mortality rate, scalar or one value per individual.	1.0

Returns

Name	Type	Description
	NDArray[np.float64]	Years from age to death, one value per individual.

Example

import numpy as np from heormodel.models import LifeTable table = LifeTable(ages=[0.0], rates=[0.05]) t = table.sample_time_to_death( … np.random.default_rng(0), np.zeros(4000), hazard_ratio=5.0) bool(abs(t.mean() - 4.0) < 0.2) # exponential with rate 0.25 True