pearl.events

Module for events that occur during a run in the PEARL model.

Functions

`append_new`(population)	Assign Art user status to reengaging population, assign ART non-user status to lost to follow up population, and assign dead status to those who died in the current year.
`calculate_cd4_decrease`(pop, parameters[, ...])	Calculate out of care cd4 count via a linear function of years out of care and sqrt cd4 count at exit from care.
`calculate_cd4_increase`(pop, parameters)	Return new cd4 count of the given population as calculated via a linear function of time since art initiation modeled as a spline, initial cd4 count category, age category and cross terms.
`create_ltfu_pop_matrix`(pop, knots)	Create and return the population matrix as a numpy array for use in calculating probability of loss to follow up.
`create_mortality_in_care_pop_matrix`(pop, ...)	Return the population matrix as a numpy array for calculating mortality in care.
`create_mortality_out_care_pop_matrix`(pop, ...)	Return the population matrix as a numpy array for calculating mortality out of care.
`update_mm`(population)	Calculate and update the multimorbidity, defined as the number of stage 2 and 3 comorbidities in each agent.

Classes

`AddNewUser`(parameters)	Add new users to the PEARL model.
`ComorbidityIncidence`(parameters)	Calculate the incidence of the comombidities in the PEARL model for that year.
`DecreaseCD4Count`(parameters)	Calculate the decrease in CD4 count for ART non-using population
`IncreaseCD4Count`(parameters)	Increase CD4 count for ART users in the PEARL model.
`IncrementYear`(parameters)	Increment the year of the model by one.
`KillInCare`(parameters)	Assign mortality to a portion of the in care population.
`KillOutCare`(parameters)	Assign mortality to a portion of agents out of care.
`LoseToFollowUp`(parameters)	Assign some agents to lost to follow up.
`PearlEvents`(parameters)	Base Pearl events.
`Reengage`(parameters)	Reengage a portion of the out of care population.

pearl.events.append_new(population: pandas.DataFrame) → pandas.DataFrame[source]: Assign Art user status to reengaging population, assign ART non-user status to lost to follow up population, and assign dead status to those who died in the current year.

pearl.events.create_mortality_out_care_pop_matrix(pop: pandas.DataFrame, parameters: Parameters) → Any[source]

Return the population matrix as a numpy array for calculating mortality out of care. This log odds of mortality are a linear function of calendar year and age and sqrt cd4 count modeled as restricted cubic splines. If using comorbidities, log odds of mortality are a linear function of calendar year, age category, sqrt cd4 count, delta bmi and post art bmi modeled as restricted cubic splines, and presence of each individual comorbidity modeled as binary variables.

Parameters:

pop (pd.DataFrame) – Population Dataframe containing age_cat, anx, post_art_bmi, ckd, dm, dpr, esld, hcv, ht, intercept, lipid, malig, mi, smoking, time_varying_sqrtcd4n, init_sqrtcd4n, and year columns.
parameters (Parameters) – Parameters object with mortality_out_care_post_art_bmi attribute.

Returns:

A numpy representation of the population for feedining into Pearl.calculate_prob to calculate death probability for out care mortality modeling.

Return type:

NDArray[Any]

pearl.events.calculate_cd4_decrease(pop: pandas.DataFrame, parameters: Parameters, smearing: float | None = 1.42) → numpy.typing.NDArray.typing.Any[source]

Calculate out of care cd4 count via a linear function of years out of care and sqrt cd4 count at exit from care.

Parameters:

pop (pd.DataFrame) – Population Dataframe containing intercept, ltfu_year, sqrtcd4n_exit, and year columns.
parameters (Parameters) – Parameters object with cd4_decrease attribute.
smearing (Optional[float], optional) – Smearing value, by default SMEARING value set in Pearl.definitions.

Returns:

numpy array representing the decreased cd4 count values.

Return type:

NDArray[Any]

pearl.events.create_ltfu_pop_matrix(pop: pandas.DataFrame, knots: pandas.DataFrame) → Any[source]

Create and return the population matrix as a numpy array for use in calculating probability of loss to follow up.

Parameters:

pop (pd.DataFrame) – The population DataFrame that we wish to calculate loss to follow up on.
knots (pd.DataFrame) – Quadratic spline knot values which are stored in Parameters.

Returns:

numpy array for passing into Pearl.calculate_prob

Return type:

NDArray[Any]

pearl.events.create_mortality_in_care_pop_matrix(pop: pandas.DataFrame, parameters: Parameters) → Any[source]

Return the population matrix as a numpy array for calculating mortality in care. This log odds of mortality are a linear function of calendar year, ART init year category modeled as two binary variables, and age and sqrt initial cd4 count modeled as restricted cubic splines. Log odds of mortality are a linear function of calendar year, age category, initial cd4 count, delta bmi and post art bmi modeled as restricted cubic splines, and presence of each individual comorbidity modeled as binary variables.

Parameters:

pop (pd.DataFrame) – Population Dataframe containing age_cat, anx, post_art_bmi, ckd, dm, dpr, esld, h1yy, hcv, ht, intercept, lipid, malig, mi, smoking, init_sqrtcd4n, and year columns.
parameters (Parameters) – Parameters object with mortality_in_care_post_art_bmi attribute.

Returns:

A numpy representation of the population for feedining into Pearl.calculate_prob to calculate death probability for in care mortality modeling.

Return type:

NDArray[Any]

pearl.events.update_mm(population: pandas.DataFrame) → pandas.DataFrame[source]: Calculate and update the multimorbidity, defined as the number of stage 2 and 3 comorbidities in each agent.

pearl.events.calculate_cd4_increase(pop: pandas.DataFrame, parameters: Parameters) → numpy.typing.NDArray.typing.Any[source]

Return new cd4 count of the given population as calculated via a linear function of time since art initiation modeled as a spline, initial cd4 count category, age category and cross terms.

Parameters:

pop (pd.DataFrame) – Population Dataframe containing age_cat, intercept, last_h1yy, last_init_sqrtcd4n, and year columns.
parameters (Parameters) – Parameters object with cd4_increase_knots and cd4_increase attributes.

Returns: