Mortality Module

The mortality module provides tools for working with mortality tables and survival functions.

Mortality Module

Mortality tables, survival functions, graduation, and mortality improvement models.

This module provides tools for: - Loading and manipulating mortality tables - Survival function calculations - Mortality graduation techniques - Mortality improvement models - African market-specific mortality assumptions

class actuneo.mortality.MortalityTable(ages: List[int] | ndarray, qx: List[float] | ndarray, name: str = 'Unnamed Table', metadata: Dict | None = None, table_columns: Dict[str, List[float] | ndarray] | None = None)

Bases: object

A class for handling mortality tables and related calculations.

Supports various formats of mortality data and provides methods for survival probabilities, life expectancy, and other actuarial functions.

__init__(ages: List[int] | ndarray, qx: List[float] | ndarray, name: str = 'Unnamed Table', metadata: Dict | None = None, table_columns: Dict[str, List[float] | ndarray] | None = None)

Initialize a mortality table.

Parameters:

• ages – Array of ages

• qx – Array of mortality rates (probability of death between age x and x+1)

• name – Name/description of the mortality table

• metadata – Additional metadata about the table

• table_columns – Additional actuarial columns aligned to ages (e.g. mx, lx, dx, Lx, Tx, ex)

ex(age: int) → float

classmethod from_csv(filepath: str, age_col: str = 'age', qx_col: str = 'qx', name: str | None = None, metadata: Dict | None = None) → MortalityTable

Create a MortalityTable from a CSV file.

Parameters:

• filepath – Path to CSV file

• age_col – Column name for ages

• qx_col – Column name for mortality rates

• name – Name for the table (defaults to filename)

Returns:

MortalityTable instance

classmethod from_dataframe(df: DataFrame, age_col: str = 'age', qx_col: str = 'qx', name: str = 'DataFrame Table', metadata: Dict | None = None) → MortalityTable

Create a MortalityTable from a pandas DataFrame.

Parameters:

• df – DataFrame containing age and mortality data

• age_col – Column name for ages

• qx_col – Column name for mortality rates

• name – Name for the table

Returns:

MortalityTable instance

classmethod from_zimbabwe_2023(table: str) → MortalityTable

get_px(age: int | List[int]) → float | ndarray

get_qx(age: int | List[int]) → float | ndarray

life_expectancy(age: int) → float

Calculate life expectancy at a given age.

Parameters:

age – Age to calculate life expectancy for

Returns:

Life expectancy in years

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

px(age: int | List[int]) → float | ndarray

Get survival probability(ies) for given age(s).

Parameters:

age – Age(s) to get survival probability for

Returns:

Survival probability(ies)

qx(age: int | List[int]) → float | ndarray

Get mortality rate(s) for given age(s).

Parameters:

age – Age(s) to get mortality rate for

Returns:

Mortality rate(s)

to_dataframe() → DataFrame

class actuneo.mortality.SurvivalFunctions(mortality_table: MortalityTable, interest_rate: float)

Bases: object

A class for calculating various actuarial survival functions and life contingencies based on mortality tables.

__init__(mortality_table: MortalityTable, interest_rate: float)

Initialize SurvivalFunctions with a mortality table and interest rate.

Parameters:

• mortality_table – MortalityTable instance

• interest_rate – Annual interest rate for discounting (e.g. 0.10 for 10%)

annuity_due(x: int, n: int | None = None) → float

Calculate the actuarial present value of an annuity-due: äx or äx:n

Parameters:

• x – Age

• n – Term of annuity (None for whole life)

Returns:

Actuarial present value of annuity-due

annuity_immediate(x: int, n: int | None = None) → float

Calculate the actuarial present value of an immediate annuity: a¨x or a¨x:n

Parameters:

• x – Age

• n – Term of annuity (None for whole life)

Returns:

Actuarial present value of immediate annuity

assurance(x: int, n: int | None = None) → float

Calculate the actuarial present value of a whole life assurance: Ax or Ax:n

Parameters:

• x – Age

• n – Term of assurance (None for whole life)

Returns:

Actuarial present value of assurance

net_single_premium(x: int, n: int | None = None) → float

Calculate net single premium for whole life or term assurance.

Parameters:

• x – Age

• n – Term (None for whole life)

Returns:

Net single premium

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

Calculate n-year survival probability: npx

Parameters:

• x – Age

• n – Number of years

Returns:

Probability that (x) survives n years

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

Calculate n-year mortality probability: nqx

Parameters:

• x – Age

• n – Number of years

Returns:

Probability that (x) dies within n years

tpx(x: int, t: float) → float

Calculate t-year survival probability using linear interpolation.

Parameters:

• x – Age

• t – Fractional years

Returns:

Probability that (x) survives t years

MortalityTable

class actuneo.mortality.MortalityTable(ages: List[int] | ndarray, qx: List[float] | ndarray, name: str = 'Unnamed Table', metadata: Dict | None = None, table_columns: Dict[str, List[float] | ndarray] | None = None)

Bases: object

A class for handling mortality tables and related calculations.

Supports various formats of mortality data and provides methods for survival probabilities, life expectancy, and other actuarial functions.

__init__(ages: List[int] | ndarray, qx: List[float] | ndarray, name: str = 'Unnamed Table', metadata: Dict | None = None, table_columns: Dict[str, List[float] | ndarray] | None = None)

Initialize a mortality table.

Parameters:

• ages – Array of ages

• qx – Array of mortality rates (probability of death between age x and x+1)

• name – Name/description of the mortality table

• metadata – Additional metadata about the table

• table_columns – Additional actuarial columns aligned to ages (e.g. mx, lx, dx, Lx, Tx, ex)

ex(age: int) → float

classmethod from_csv(filepath: str, age_col: str = 'age', qx_col: str = 'qx', name: str | None = None, metadata: Dict | None = None) → MortalityTable

Create a MortalityTable from a CSV file.

Parameters:

• filepath – Path to CSV file

• age_col – Column name for ages

• qx_col – Column name for mortality rates

• name – Name for the table (defaults to filename)

Returns:

MortalityTable instance

classmethod from_dataframe(df: DataFrame, age_col: str = 'age', qx_col: str = 'qx', name: str = 'DataFrame Table', metadata: Dict | None = None) → MortalityTable

Create a MortalityTable from a pandas DataFrame.

Parameters:

• df – DataFrame containing age and mortality data

• age_col – Column name for ages

• qx_col – Column name for mortality rates

• name – Name for the table

Returns:

MortalityTable instance

classmethod from_zimbabwe_2023(table: str) → MortalityTable

get_px(age: int | List[int]) → float | ndarray

get_qx(age: int | List[int]) → float | ndarray

life_expectancy(age: int) → float

Calculate life expectancy at a given age.

Parameters:

age – Age to calculate life expectancy for

Returns:

Life expectancy in years

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

px(age: int | List[int]) → float | ndarray

Get survival probability(ies) for given age(s).

Parameters:

age – Age(s) to get survival probability for

Returns:

Survival probability(ies)

qx(age: int | List[int]) → float | ndarray

Get mortality rate(s) for given age(s).

Parameters:

age – Age(s) to get mortality rate for

Returns:

Mortality rate(s)

to_dataframe() → DataFrame

SurvivalFunctions

class actuneo.mortality.SurvivalFunctions(mortality_table: MortalityTable, interest_rate: float)

Bases: object

A class for calculating various actuarial survival functions and life contingencies based on mortality tables.

__init__(mortality_table: MortalityTable, interest_rate: float)

Initialize SurvivalFunctions with a mortality table and interest rate.

Parameters:

• mortality_table – MortalityTable instance

• interest_rate – Annual interest rate for discounting (e.g. 0.10 for 10%)

annuity_due(x: int, n: int | None = None) → float

Calculate the actuarial present value of an annuity-due: äx or äx:n

Parameters:

• x – Age

• n – Term of annuity (None for whole life)

Returns:

Actuarial present value of annuity-due

annuity_immediate(x: int, n: int | None = None) → float

Calculate the actuarial present value of an immediate annuity: a¨x or a¨x:n

Parameters:

• x – Age

• n – Term of annuity (None for whole life)

Returns:

Actuarial present value of immediate annuity

assurance(x: int, n: int | None = None) → float

Calculate the actuarial present value of a whole life assurance: Ax or Ax:n

Parameters:

• x – Age

• n – Term of assurance (None for whole life)

Returns:

Actuarial present value of assurance

net_single_premium(x: int, n: int | None = None) → float

Calculate net single premium for whole life or term assurance.

Parameters:

• x – Age

• n – Term (None for whole life)

Returns:

Net single premium

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

Calculate n-year survival probability: npx

Parameters:

• x – Age

• n – Number of years

Returns:

Probability that (x) survives n years

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

Calculate n-year mortality probability: nqx

Parameters:

• x – Age

• n – Number of years

Returns:

Probability that (x) dies within n years

tpx(x: int, t: float) → float

Calculate t-year survival probability using linear interpolation.

Parameters:

• x – Age

• t – Fractional years

Returns:

Probability that (x) survives t years