Table

LifeTable

class elizur.life.table.LifeTable(table: Iterable[float] | ndarray, name: str = '', description: str = '', initial_pop: int = 100000)

Single-decrement life table for actuarial calculations.

Computes standard actuarial functions including qx, px, lx, dx, ex, mx, commutation functions (Dx, Nx, Sx, Cx, Mx, Rx), and actuarial present values of annuities and insurances.

Parameters:

  • table – Iterable of annual failure probabilities (qx values) in sequential order starting from age 0, e.g. (q0, q1, …, qω).

  • name – Optional descriptive name for the table.

  • description – Optional extended description of the table.

  • initial_pop – Radix (l0) — the starting population size.

  • initial_pop – the size of the initial population (l0)

qx(x: int) → float
Args:

  • x - start age

Returns:

The probability of failure between ages x and x + 1

px(x: int) → float
Args:

  • x - start age

Returns:

The probability of survival between ages x and x + 1

lx(x: int) → float
Args:

  • x - start age

Returns:

The population size at age x

dx(x: int) → float
Args:

  • x - start age

Returns:

The number of failures between ages x and x + 1

ex(x: int) → float
Args:

  • x - start age

Returns:

The curtate life expectation at age x

mx(x: int) → float
Args:

  • x - start age

Returns:

The central failure rate between ages x and x + 1

nqx(n: int, x: int) → float
Args:

  • n - width of failure interval in years

  • x - start age

Returns:

The probability of failure between ages x and x + n

nqxs(n: int) → np.ndarray
Args:

  • n - width of failure interval in years

Returns:

The probability of failure between ages x and x + n for all ages

npx(n: int, x: int) → float
Args:

  • n - width of survival interval in years

  • x - start age

Returns:

The probability of survival between ages x and x + n

npxs(n: int) → np.ndarray
Args:

  • n - width of survival interval in years

Returns:

The probability of survival between ages x and x + n for all ages

nlx(n: int, x: int) → float
Args:

  • n - width of failure interval in years

  • x - start age

Returns:

The number of person years lived between ages x and x + n

ndx(n: int, x: int) → float
Args:

  • n - width of failure interval in years

  • x - start age

Returns:

The number of failures between ages x and x + n

nmx(n: int, x: int) → float
Args:

  • n - width of failure interval in years

  • x - start age

Returns:

The central failure rate between ages x and x + n

tqxn(t: int, n: int, x: int) → float
Args:

  • t - width of the failure interval in years

  • n - width of the survival interval in years

  • x - start age

Returns:

The probability of surviving from age x to x + n and then failing between age x + n and age x + n + t

tqxns(t: int, n: int) → np.ndarray
Args:

  • t - width of the failure interval in years

  • n - width of the survival interval in years

Returns:

The probability of surviving from x to x + n and failing within t years, for all ages

Dx(x: int, i: float) → float

Actuarial commutation function Dx

Args:

  • x - start age

  • i - interest rate

Returns:

Population at age x discounted for x years

Nx(x: int, i: float) → float

Actuarial commutation function Nx

Args:

  • x - start age

  • i - interest rate

Returns:

Sum of Ds from age x and onward

Sx(x: int, i: float) → float

Actuarial commutation function Sx

Args:

  • x - start age

  • i - interest rate

Returns:

Sum of Ns from age x and onward

Cx(x: int, i: float) → float

Actuarial commutation function Cx

Args:

  • x - start age

  • i - interest rate

Returns:

Failures between x and x + 1 discounted for x years

Mx(x: int, i: float) → float

Actuarial commutation function Mx

Args:

  • x - start age

  • i - interest rate

Returns:

Sum of Cs from age x and onward

Rx(x: int, i: float) → float

Actuarial commutation function Rx

Args:

  • x - start age

  • i - interest rate

Returns:

Sum of Ms from age x and onward

Ax(x: int, i: float) → float
Args:

  • x - start age

  • i - interest rate

Returns:

Actuarial present value of level whole insurance

Axn(x: int, i: float, n: int) → float
Args:

  • x - start age

  • i - interest rate

  • n - number of periods

Returns:

Actuarial present value of level temporary insurance

IAx(x: int, i: float) → float
Args:

  • x - start age

  • i - interest rate

Returns:

Actuarial present value of increasing whole insurance

IAxn(x: int, i: float, n: int) → float
Args:

  • x - start age

  • i - interest rate

  • n - number of periods

Returns:

Actuarial present value of increasing temporary insurance

ax(x: int, i: float) → float
Args:

  • x - start age

  • i - interest rate

Returns:

Actuarial present value of a level perpetuity

axn(x: int, i: float, n: int) → float
Args:

  • x - start age

  • i - interest rate

  • n - length of payments

Returns:

Actuarial present value of a temporary annuity

ax_due(x: int, i: float) → float
Args:

  • x - start age

  • i - interest rate

Returns:

Actuarial present value of a level perpetuity due

axn_due(x: int, i: float, n: int) → float
Args:

  • x - start age

  • i - interest rate

  • n - length of payments

Returns:

Actuarial present value of a temporary annuity due

to_frame() → polars.DataFrame

Export the life table as a Polars DataFrame suitable for joining against policy-level data in actuarial projection engines.

Returns:

A Polars DataFrame with columns: age, qx, px, lx, dx, mx.

get_lxs() → tuple[float, ...]

This method is deprecated and will be removed in v1.0.0

The recommended method is to use the ‘lxs’ property

Returns:

A tuple of the population counts (lxs)

get_qxs() → tuple[float, ...]

This method is deprecated and will be removed in v1.0.0

The recommended method is to use the ‘qxs’ property

Returns:

A tuple of the failure probabilities (qxs), e.g., (0q1, 2q1, …, 100q99)

property w: int

Returns: The limiting age of the life table

MultiDecrementTable

class elizur.life.table.MultiDecrementTable(mortality: LifeTable, lapse_rates: Iterable[float] | ndarray)

Two-decrement life table combining mortality and lapse decrements.

Applies the independent decrements assumption with the UDD (Uniform Distribution of Deaths) approximation to convert single-decrement probabilities into multi-decrement probabilities. This is the standard actuarial approach for IFRS 17 cashflow projection models where policies exit either by death or voluntary lapse.

Under UDD, the multi-decrement probabilities are approximated as:

q^(d)_x ≈ q’(d)_x × (1 - q’(w)_x / 2) q^(w)_x ≈ q’(w)_x × (1 - q’(d)_x / 2) q^(τ)_x = 1 - (1 - q’(d)_x) × (1 - q’(w)_x)

where q’(d) and q’(w) are the single-decrement (independent) mortality and lapse probabilities respectively.

Parameters:

  • mortality – Single-decrement mortality LifeTable. The lapse rates must be aligned to the same age indices as this table.

  • lapse_rates – Annual lapse (withdrawal) rates indexed by age, starting from age 0. Must have the same length as the mortality table.

Raises:

ValueError – If lapse_rates length does not match the mortality table size.

dx_d(x: int) → float

Expected deaths between age x and x + 1 in the multi-decrement table.

Parameters:

x – Attained age.

Returns:

Expected number of deaths between age x and x + 1.

Raises:

InvalidAge – If x is negative.

dx_w(x: int) → float

Expected lapses between age x and x + 1 in the multi-decrement table.

Parameters:

x – Attained age.

Returns:

Expected number of lapses between age x and x + 1.

Raises:

InvalidAge – If x is negative.

lx_tau(x: int) → float

Expected number of lives in the multi-decrement table at age x.

Parameters:

x – Attained age.

Returns:

Expected lives at age x under both mortality and lapse decrements.

Raises:

InvalidAge – If x is negative.

npx_tau(n: int, x: int) → float

Probability of surviving all decrements for n years from age x.

Parameters:

  • n – Number of years.

  • x – Starting age.

Returns:

Probability of surviving both mortality and lapse decrements from age x to age x + n.

Raises:
px_tau(x: int) → float

Total multi-decrement survival probability at age x.

Parameters:

x – Attained age.

Returns:

Probability of surviving all decrements between age x and x + 1.

Raises:

InvalidAge – If x is negative.

qx_d(x: int) → float

Multi-decrement probability of death at age x.

Parameters:

x – Attained age.

Returns:

Probability of decrement by death between age x and x + 1 in the multi-decrement table.

Raises:

InvalidAge – If x is negative.

qx_tau(x: int) → float

Total multi-decrement probability at age x.

Parameters:

x – Attained age.

Returns:

Probability of decrement by any cause between age x and x + 1.

Raises:

InvalidAge – If x is negative.

qx_w(x: int) → float

Multi-decrement probability of lapse at age x.

Parameters:

x – Attained age.

Returns:

Probability of decrement by lapse between age x and x + 1 in the multi-decrement table.

Raises:

InvalidAge – If x is negative.

property table_size: int

Number of ages in the table.

to_frame() → DataFrame

Export the multi-decrement table as a Polars DataFrame.

Each row represents one age from 0 to ω-1. The resulting DataFrame includes both the original single-decrement rates and the computed multi-decrement probabilities, making it suitable for joining against policy-level DataFrames in projection engines.

Returns:

  • age: integer age from 0 to table_size - 1

  • qx_prime_d: single-decrement mortality rate q’(d)_x

  • qx_prime_w: single-decrement lapse rate q’(w)_x

  • qx_d: multi-decrement mortality probability q^(d)_x

  • qx_w: multi-decrement lapse probability q^(w)_x

  • qx_tau: total decrement probability q^(τ)_x

  • px_tau: total survival probability p^(τ)_x

  • lx_tau: expected lives in multi-decrement table

  • dx_d: expected deaths in multi-decrement table

  • dx_w: expected lapses in multi-decrement table

Return type:

A Polars DataFrame with columns