pearl.parameters

Parameters class

Classes

Parameters(output_folder, replication, ...)

This class holds all the parameters needed for PEARL to run.

class pearl.parameters.Parameters(output_folder: Path, replication: int, group_name: str, new_dx: str, start_year: int, final_year: int, mortality_model: str, mortality_threshold_flag: bool, idu_threshold: str, seed: int, history: List[str] | None = None, final_state: bool = False, ignore_columns: List[str] | None = None, bmi_intervention_scenario: int = 0, bmi_intervention_start_year: int = 2020, bmi_intervention_end_year: int = 2030, bmi_intervention_coverage: float = 1.0, bmi_intervention_effectiveness: float = 1.0, sa_variables: list[str] | None = None)[source]

Bases: object

This class holds all the parameters needed for PEARL to run.

parameters_path: Path to the parameters file for the PEARL model.

output_folder: File path to the folder where PEARL outputs will be saved.

replication: Replication number for the model run.

group_name: Group name for the model run.

new_dx_val: Diagnosis model to use for the model run.

start_year: Start year of the model run.

final_year: Final year of the model run.

year: Current year of the model run, initialized to start_year.

mortality_model: Mortality model to use for the model run.

mortality_threshold_flag: Mortality threshold flag for the model run.

idu_threshold: IDU threshold for the model run.

seed: Random seed for the model run.

random_state: Random state object for the model run, initialized with seed using np.random.RandomState.

init_random_state: Random state object for parameter initialization, initialized with replication number using np.random.RandomState.

history: Whether or not to store history.

final_state: Whether or not to only store final state.

ignore_columns: Columns to ignore when storing history.

on_art_2009: Parameter for number of people on ART in 2009 for given group.

age_in_2009: Parameter for age distribution of people in 2009 for given group.

h1yy_by_age_2009: Paramters for year of HIV diagnosis by age in 2009 for given group.

cd4n_by_h1yy_2009: Parameters for CD4 count by year of HIV diagnosis in 2009 for given group.

linkage_to_care: Parameter for linkage to care for given group.

age_by_h1yy: Parameter for age by year of HIV diagnosis for given group.

cd4n_by_h1yy: Parameter for CD4 count by year of HIV diagnosis for given group.

new_dx: pandas.DataFrame: Parameter for new ART initiators. Chosen based on new_dx input, either “base” or “ehe” for given group.

mortality_in_care: Parameter for mortality in care for given group. Chosen based on mortality_model input.

mortality_in_care_age: Parameter for mortality in care by age for given group. Chosen based on mortality_model input.

mortality_in_care_sqrtcd4: Parameter for mortality in care by sqrt CD4 count for given group. Chosen based on mortality_model input.

mortality_in_care_vcov: Parameter for variance-covariance matrix for mortality in care for given group.

mortality_out_care: Parameter for mortality out of care for given group. Chosen based on mortality_model input.

mortality_out_care_age: Parameter for mortality out of care by age for given group. Chosen based on mortality_model input.

mortality_out_care_tv_sqrtcd4: Parameter for mortality out of care by time-varying sqrt CD4 count for given group. Chosen based on mortality_model input.

mortality_out_care_vcov: Parameter for variance-covariance matrix for mortality out of care for given group.

mortality_threshold: pandas.DataFrame: Parameter for mortality threshold for given group. Chosen based on idu_threshold input. If idu_threshold is not 2x, then the mortality threshold is dependent on the idu_threshold. If idu_threshold is 2x, then the mortality threshold is dependent on the mortality_model.

loss_to_follow_up: Parameter for loss to follow up for given group.

ltfu_knots: Parameter for loss to follow up knots for given group.

loss_to_follow_up_vcov: Parameter for variance-covariance matrix for loss to follow up for given group.

cd4_increase: Parameter for CD4 increase for given group.

cd4_increase_vcov: Parameter for variance-covariance matrix for CD4 increase for given group.

cd4_increase_knots_age: Parameter for CD4 increase knots by age for given group.

cd4_increase_knots_cd4_init: Parameter for CD4 increase knots by initial CD4 count for given group.

cd4_increase_knots_time_from_h1yy: Parameter for CD4 increase knots by time from HIV diagnosis for given group.

cd4_decrease: Parameter for CD4 decrease for all groups.

cd4_decrease_vcov: Parameter for variance-covariance matrix for CD4 decrease for all groups.

years_out_of_care: Parameter for years out of care for all groups.

pre_art_bmi: Parameter for pre-ART BMI for given group.

pre_art_bmi_model: Parameter for pre-ART BMI model for given group.

pre_art_bmi_age_knots: Parameter for pre-ART BMI age knots for given group.

pre_art_bmi_h1yy_knots: Parameter for pre-ART BMI year of HIV diagnosis knots for given group.

pre_art_bmi_rse: Parameter for pre-ART BMI residual standard error for given group.

post_art_bmi: Parameter for post-ART BMI for given group.

post_art_bmi_age_knots: Parameter for post-ART BMI age knots for given group.

post_art_bmi_pre_art_bmi_knots: Parameter for post-ART BMI pre-ART BMI knots for given group.

post_art_bmi_cd4_knots: Parameter for post-ART BMI CD4 count knots for given group.

post_art_bmi_cd4_post_knots: Parameter for post-ART BMI CD4 count after ART initiation knots for given group.

post_art_bmi_rse: Parameter for post-ART BMI residual standard error for given group.

bmi_intervention_scenario: Parameter for BMI intervention scenario to apply for given group. Must be 0, 1, 2, or 3. 0 corresponds to no intervention, 1 corresponds to a lifestyle intervention for those with BMI over 25, 2 corresponds to a lifestyle intervention for those with BMI over 30, and 3 corresponds to a pharmacological intervention for those with BMI over 30.

bmi_intervention_start_year: Parameter for BMI intervention start year for given group.

bmi_intervention_end_year: Parameter for BMI intervention end year for given group.

bmi_intervention_coverage: Parameter for BMI intervention coverage for given group. Must be between 0 and 1 inclusive. Represents the proportion of eligible population that receives the BMI intervention.

bmi_intervention_effectiveness: Parameter for BMI intervention effectiveness for given group. Must be between 0 and 1 inclusive. Represents the proportion of eligible population that receives the BMI intervention.

prev_users_dict: Parameter for prevalence of comorbidity among users for given group. Dictionary with keys for each comorbidity and values as the prevalence of that comorbidity among users for the given group.

prev_inits_dict: Parameter for prevalence of comorbidity among new initiators for given group. Dictionary with keys for each comorbidity and values as the prevalence of that comorbidity among new initiators for the given group.

comorbidity_coeff_dict: Parameter for coefficient for comorbidity in the CD4 decrease model for given group. Dictionary with keys for each comorbidity and values as the coefficient for that comorbidity in the CD4 decrease model for the given group.

delta_bmi_dict: Parameter for change in BMI associated with comorbidity for given group. Dictionary with keys for each comorbidity and values as the change in BMI associated with that comorbidity for the given group.

post_art_bmi_dict: Parameter for post-ART BMI associated with comorbidity for given group. Dictionary with keys for each comorbidity and values as the post-ART BMI associated with that comorbidity for the given group.

mortality_in_care_co: Parameter for mortality in care for given group. Coefficients for the mortality in care model for the given group.

mortality_in_care_post_art_bmi: Parameter for mortality in care for given group. Coefficients for the post-ART BMI variable in the mortality in care model for the given group.

mortality_out_care_co: Parameter for mortality out of care for given group. Coefficients for the mortality out of care model for the given group.

mortality_out_care_post_art_bmi: Parameter for mortality out of care for given group. Coefficients for the post-ART BMI variable in the mortality out of care model for the given group.

AGES: Parameter for age range of agents in the model. Minimum age is 18 and maximum age is 86.

AGE_CATS: Parameter for age categories for agents in the model. Age categories are defined as 18-29, 30-39, 40-49, 50-59, 60-69, and 70-79.

SIMULATION_YEARS: Parameter for years of the simulation. Simulation runs from 2010 to final_year.

ALL_YEARS: Parameter for all years in the model. Range from 2000 to final_year.

INITIAL_YEARS: Parameter for initial years of the model. Range from 2000 to 2009.

CD4_BINS: Parameter for CD4 count bins for the model. Range from 0 to 2000.

sa_variables: Parameter for sensitivity analysis variables. List of variables to include in sensitivity analysis.

sa_scalars: Parameter for sensitivity analysis scalars. Dictionary with keys for each variable included in sensitivity analysis and values as the scalar to multiply that variable by for the sensitivity analysis.

n_initial_users: Parameter for number of ART users in 2009 for given group, taken from on_art_2009 parameter.

n_initial_nonusers: int: Parameter for number of ART non-users in 2009 for given group. Calculated based on the number of new ART initiators each year and the assumption that those not initiating ART in the first few years of the model are the initial ART non-users.

n_new_agents: int: Parameter for number of new agents entering the model each year. Calculated based on the number of new ART initiators each year and the number of new ART non-users each year.

save_parameters() → None[source]: Save all parameters as a dataframe.

simulate_new_dx() → Tuple[int, pandas.DataFrame][source]

Return the number of ART non-users in 2009 as an integer and the number of agents entering the model each year as art users and non-users as a dataframe. Draw number of new diagnoses from a uniform distribution between upper and lower bounds. Calculate number of new art initiators by assuming a certain number link in the first year as estimated by a linear regression on CDC data, capped at 95%. We assume that 40% of the remaining population links to care over the next 3 years. We assume that 70% of those linking to care begin ART, rising to 85% in 2011 and 97% afterwards. We take the number of people not initiating ART 2006 - 2009 in this calculation to be the out of care population size in 2009 for our simulation.

Parameters:

parameters (Parameters) – Parameter object with new_dx and linkage_to_care attributes.
random_state (np.random.RandomState) – Random State object for random number sampling.

Returns:

(number of ART non-users in 2009 as an integer, number of agents entering the model each year as art users and non-users as a dataframe)

Return type:

Tuple[int, pd.DataFrame]