laser.core.demographics.kmestimator

laser.core.demographics.kmestimator

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

Classes:

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

Functions:

Name	Description
- _pyod	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	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)

laser.core.demographics.kmestimator.KaplanMeierEstimator(source)

Initializes the KMEstimator with the given source data.

Parameters:

Name	Type	Description	Default
source	(ndarray, list, Path, str)	The source data for the KMEstimator. A numpy array of unsigned 32-bit integers. A list of integers. A Path object pointing to a file containing the data. A string representing the file path.	required

Raises:

Type	Description
FileNotFoundError	If the provided file path does not exist or is not a file.
TypeError	If the source type is not one of the accepted types (np.ndarray, list, Path, str).
ValueError	If the source inputs contain negative values or are not monotonically non-decreasing.

Notes

• If the source is a file path, the file should contain comma-separated values with the data in the second column.
• The source data is converted to a numpy array of unsigned 32-bit integers.

laser.core.demographics.kmestimator.KaplanMeierEstimator.cumulative_deaths property

Returns the original source data.

laser.core.demographics.kmestimator.KaplanMeierEstimator.predict_age_at_death(ages_days, max_year=None)

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

Parameters:

Name	Type	Description	Default
ages_days	ndarray	The ages of the individuals in days.	required
max_year	int	The maximum year to consider for calculating the predicted year of death. Default is None, which uses the maximum year from the source data.	None

Returns:

Name	Type	Description
age_at_death	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])

laser.core.demographics.kmestimator.KaplanMeierEstimator.predict_year_of_death(ages_years, max_year=None)

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

Parameters:

Name	Type	Description	Default
ages_years	ndarray	The ages of the individuals in years.	required
max_year	int	The maximum year to consider for calculating the predicted year of death. Default is None, which uses the maximum year from the source data.	None

Returns:

Name	Type	Description
year_of_death	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.kmestimator.KaplanMeierEstimator.sample(current, max_index=None)

Similar to predict_year_of_death, but operates on indices rather than years. This method predicts the expiration (death) index for each individual, given their current index.

Parameters:

Name	Type	Description	Default
current	ndarray	The current indices of the individuals.	required
max_index	int	The maximum index to consider for calculating the predicted expiration. Default is None, which uses the maximum index from the source data.	None

Returns:

Name	Type	Description
predictions	ndarray	The predicted expiration indices for each individual.