laser_core.demographics package

Submodules

laser_core.demographics.kmestimator module

This module provides the KaplanMeierEstimator class for predicting the year and age at death based on given ages and cumulative death data.

Classes:

• KaplanMeierEstimator: A class to perform Kaplan-Meier estimation for predicting the year and age at death.

Functions:

• _pyod(ages_years: np.ndarray, cumulative_deaths: np.ndarray, max_year: np.uint32 = 100): Calculate the predicted year of death based on the given ages in years.

• _pdod(age_in_days: np.ndarray, year_of_death: np.ndarray, day_of_death: np.ndarray): Calculate the predicted day of death based on the given ages in days and predicted years of death.

Usage example:

estimator = KaplanMeierEstimator(cumulative_deaths=np.array([...]))
year_of_death = estimator.predict_year_of_death(np.array([40, 50, 60]), max_year=80)
age_at_death = estimator.predict_age_at_death(np.array([40*365, 50*365, 60*365]), max_year=80)

class laser_core.demographics.kmestimator.KaplanMeierEstimator(source: ndarray | list | Path | str)

Bases: object

property cumulative_deaths: ndarray

Returns the original source data.

predict_age_at_death(ages_days: ndarray[Any, dtype[integer]], max_year: uint32 = 100) → ndarray

Calculate the predicted age at death (in days) based on the given ages in days.

Parameters:

• ages_days (np.ndarray) – The ages of the individuals in days.

• max_year (int) – The maximum year to consider for calculating the predicted year of death. Default is 100.

Returns:

age_at_death (np.ndarray) – The predicted days of death.

Example:

predict_age_at_death(np.array([40*365, 50*365, 60*365]), max_year=80) # returns something like array([22732, 26297, 29862])

predict_year_of_death(ages_years: ndarray[Any, dtype[integer]], max_year: uint32 = 100) → ndarray

Calculate the predicted year of death based on the given ages in years.

Parameters:

• ages_years (np.ndarray) – The ages of the individuals in years.

• max_year (int) – The maximum year to consider for calculating the predicted year of death. Default is 100.

Returns:

year_of_death (np.ndarray) – The predicted years of death.

Example:

predict_year_of_death(np.array([40, 50, 60]), max_year=80) # returns something like array([62, 72, 82])

laser_core.demographics.pyramid module

A class for generating samples from a distribution using the Vose alias method.

class laser_core.demographics.pyramid.AliasedDistribution(counts)

Bases: object

A class to generate samples from a distribution using the Vose alias method.

property alias: ndarray

property probs: ndarray

sample(count=1, dtype=<class 'numpy.int32'>) → int

Generate samples from the distribution.

Parameters:

count (int) – The number of samples to generate. Default is 1.

Returns:

int or numpy.ndarray – A single integer if count is 1, otherwise an array of integers representing the generated samples.

property total: int

laser_core.demographics.pyramid.load_pyramid_csv(file: Path, verbose=False) → ndarray

Load a CSV file with population pyramid data and return it as a NumPy array.

The CSV file is expected to have the following schema:

• The first line is a header: “Age,M,F”

• Subsequent lines contain age ranges and population counts for males and females:

"low-high,#males,#females"
...
"max+,#males,#females"

Where low, high, males, females, and max are integer values >= 0.

The function processes the CSV file to create a NumPy array with the following columns:

• Start age of the range

• End age of the range

• Number of males

• Number of females

Parameters:

• file (Path) – The path to the CSV file.

• verbose (bool) – If True, prints the file reading status. Default is False.

Returns:

np.ndarray – A NumPy array with the processed population pyramid data.

Module contents

class laser_core.demographics.AliasedDistribution(counts)

Bases: object

A class to generate samples from a distribution using the Vose alias method.

property alias: ndarray

property probs: ndarray

sample(count=1, dtype=<class 'numpy.int32'>) → int

Generate samples from the distribution.

Parameters:

count (int) – The number of samples to generate. Default is 1.

Returns:

int or numpy.ndarray – A single integer if count is 1, otherwise an array of integers representing the generated samples.

property total: int

class laser_core.demographics.KaplanMeierEstimator(source: ndarray | list | Path | str)

Bases: object

property cumulative_deaths: ndarray

Returns the original source data.

predict_age_at_death(ages_days: ndarray[Any, dtype[integer]], max_year: uint32 = 100) → ndarray

Calculate the predicted age at death (in days) based on the given ages in days.

Parameters:

• ages_days (np.ndarray) – The ages of the individuals in days.

• max_year (int) – The maximum year to consider for calculating the predicted year of death. Default is 100.

Returns:

age_at_death (np.ndarray) – The predicted days of death.

Example:

predict_age_at_death(np.array([40*365, 50*365, 60*365]), max_year=80) # returns something like array([22732, 26297, 29862])

predict_year_of_death(ages_years: ndarray[Any, dtype[integer]], max_year: uint32 = 100) → ndarray

Calculate the predicted year of death based on the given ages in years.

Parameters:

• ages_years (np.ndarray) – The ages of the individuals in years.

• max_year (int) – The maximum year to consider for calculating the predicted year of death. Default is 100.

Returns:

year_of_death (np.ndarray) – The predicted years of death.

Example:

predict_year_of_death(np.array([40, 50, 60]), max_year=80) # returns something like array([62, 72, 82])

laser_core.demographics.load_pyramid_csv(file: Path, verbose=False) → ndarray

Load a CSV file with population pyramid data and return it as a NumPy array.

The CSV file is expected to have the following schema:

• The first line is a header: “Age,M,F”

• Subsequent lines contain age ranges and population counts for males and females:

"low-high,#males,#females"
...
"max+,#males,#females"

Where low, high, males, females, and max are integer values >= 0.

The function processes the CSV file to create a NumPy array with the following columns:

• Start age of the range

• End age of the range

• Number of males

• Number of females

Parameters:

• file (Path) – The path to the CSV file.

• verbose (bool) – If True, prints the file reading status. Default is False.

Returns:

np.ndarray – A NumPy array with the processed population pyramid data.