tlo.methods.hiv module

The HIV Module Overview: HIV infection —> AIDS onset Event (defined by the presence of AIDS symptoms) –> AIDS Death Event Testing is spontaneously taken-up and can lead to accessing intervention services (ART, VMMC, PrEP). AIDS symptoms can also lead to care-seeking and there is routine testing for HIV at all non-emergency Generic HSI

events.

Persons can be on ART -

with viral suppression: when the person with not develop AIDS, or if they have already, it is relieved and they
will not die of AIDS; and the person is not infectious
without viral suppression: when there is no benefit in avoiding AIDS and infectiousness is unchanged.

Maintenance on ART and PrEP is re-assessed at periodic ‘Decision Events’, at which it is determined if the person

will attend the “next” HSI for continuation of the service; and if not, they are removed from that service and “stop treatment”. If a stock-out or non-availability of health system resources prevent treatment continuation, the person “stops treatment”. Stopping treatment leads to a new AIDS Event being scheduled. Persons can restart treatment. If a person has developed AIDS, starts treatment and then defaults from treatment, their ‘original’ AIDS Death Event will still occur.

If PrEP is not available due to limitations in the HealthSystem, the person defaults to not being on PrEP. # Things to note:

Need to incorporate testing for HIV at first ANC appointment (as it does in generic HSI)

Need to incorporate testing for infants born to HIV-positive mothers (currently done in on_birth here).

Need to incorporate cotrim for infants born to HIV-positive mothers (not done here)

Cotrimoxazole is not included - either in effect of consumption of the drug (because the effect is not known).

Calibration has not been done: most things look OK - except HIV-AIDS deaths

class Hiv(name=None, run_with_checks=False)

The HIV Disease Module

Construct a new disease module ready to be included in a simulation.

Initialises an empty parameters dictionary and module-specific random number generator.

Parameters:: name – the name to use for this module. Defaults to the concrete subclass’ name.

Bases: tlo.core.Module, tlo.methods.hsi_generic_first_appts.GenericFirstAppointmentsMixin

PARAMETERS:

Item	Type	Description
time_inf	DATA_FRAME	prob of time since infection for baseline adult pop
art_coverage	DATA_FRAME	coverage of ART at baseline
treatment_cascade	DATA_FRAME	spectrum estimates of treatment cascade
beta	REAL	Transmission rate
unaids_prevalence_adjustment_factor	REAL	adjustment for baseline age-specific prevalence values to give correct population prevalence
prob_mtct_untreated	REAL	Probability of mother to child transmission
prob_mtct_treated	REAL	Probability of mother to child transmission, mother on ART
prob_mtct_incident_preg	REAL	Probability of mother to child transmission, mother infected during pregnancy
monthly_prob_mtct_bf_untreated	REAL	Probability of mother to child transmission during breastfeeding
monthly_prob_mtct_bf_treated	REAL	Probability of mother to child transmission, mother infected during breastfeeding
rr_fsw	REAL	Relative risk of HIV with female sex work
rr_circumcision	REAL	Relative risk of HIV with circumcision
rr_rural	REAL	Relative risk of HIV in rural location
rr_windex_poorer	REAL	Relative risk of HIV with wealth level poorer
rr_windex_middle	REAL	Relative risk of HIV with wealth level middle
rr_windex_richer	REAL	Relative risk of HIV with wealth level richer
rr_windex_richest	REAL	Relative risk of HIV with wealth level richest
rr_sex_f	REAL	Relative risk of HIV if female
rr_edlevel_primary	REAL	Relative risk of HIV with primary education
rr_edlevel_secondary	REAL	Relative risk of HIV with secondary education
rr_edlevel_higher	REAL	Relative risk of HIV with higher education
rr_schisto	REAL	Relative risk of HIV with high intensity S. haematobium infection
rr_behaviour_change	REAL	Relative risk of HIV with behaviour modification
proportion_reduction_in_risk_of_hiv_aq_if_on_oral_prep	REAL	Proportion reduction in risk of HIV acquisition if on oral PrEP. 0 for no efficacy; 1.0 for perfect efficacy.
proportion_reduction_in_risk_of_hiv_aq_if_on_inj_prep	REAL	Proportion reduction in risk of HIV acquisition if on inj PrEP. 0 for no efficacy; 1.0 for perfect efficacy.
min_months_between_aids_and_death	INT	Minimum number of months for the time between AIDS and AIDS Death
mean_months_between_aids_and_death	REAL	Mean number of months (distributed exponentially) for the time between AIDS and AIDS Death
mean_months_between_aids_and_death_infant	REAL	Mean number of months for the time between AIDS and AIDS Death for infants
infection_to_death_weibull_shape_1519	REAL	Shape parameter for Weibull describing time between infection and death for 15-19 yo (units: years)
infection_to_death_weibull_shape_2024	REAL	Shape parameter for Weibull describing time between infection and death for 20-24 yo (units: years)
infection_to_death_weibull_shape_2529	REAL	Shape parameter for Weibull describing time between infection and death for 25-29 yo (units: years)
infection_to_death_weibull_shape_3034	REAL	Shape parameter for Weibull describing time between infection and death for 30-34 yo (units: years)
infection_to_death_weibull_shape_3539	REAL	Shape parameter for Weibull describing time between infection and death for 35-39 yo (units: years)
infection_to_death_weibull_shape_4044	REAL	Shape parameter for Weibull describing time between infection and death for 40-44 yo (units: years)
infection_to_death_weibull_shape_4549	REAL	Shape parameter for Weibull describing time between infection and death for 45-49 yo (units: years)
infection_to_death_weibull_scale_1519	REAL	Scale parameter for Weibull describing time between infection and death for 15-19 yo (units: years)
infection_to_death_weibull_scale_2024	REAL	Scale parameter for Weibull describing time between infection and death for 20-24 yo (units: years)
infection_to_death_weibull_scale_2529	REAL	Scale parameter for Weibull describing time between infection and death for 25-29 yo (units: years)
infection_to_death_weibull_scale_3034	REAL	Scale parameter for Weibull describing time between infection and death for 30-34 yo (units: years)
infection_to_death_weibull_scale_3539	REAL	Scale parameter for Weibull describing time between infection and death for 35-39 yo (units: years)
infection_to_death_weibull_scale_4044	REAL	Scale parameter for Weibull describing time between infection and death for 40-44 yo (units: years)
infection_to_death_weibull_scale_4549	REAL	Scale parameter for Weibull describing time between infection and death for 45-49 yo (units: years)
art_default_to_aids_mean_years	REAL	Mean years between when a person (any change) stops being on treatment to when AIDS is onset (if the absence of resuming treatment).
prop_delayed_aids_onset	REAL	Proportion of PLHIV that will have delayed AIDS onset to compensate for AIDS-TB
mean_survival_for_infants_infected_prior_to_birth	REAL	Exponential rate parameter for mortality in infants who are infected before birth
infection_to_death_infant_infection_after_birth_weibull_scale	REAL	Weibull scale parameter for mortality in infants who are infected after birth
infection_to_death_infant_infection_after_birth_weibull_shape	REAL	Weibull shape parameter for mortality in infants who are infected after birth
hiv_testing_rates	DATA_FRAME	annual rates of testing for children and adults
rr_test_hiv_positive	REAL	relative likelihood of having HIV test for people with HIV
hiv_testing_rate_adjustment	REAL	adjustment to current testing rates to account for multiple routes into HIV testing
prob_hiv_test_at_anc_or_delivery	REAL	probability of a women having hiv test at anc or following delivery
prob_hiv_test_for_newborn_infant	REAL	probability of a newborn infant having HIV test pre-discharge
prob_start_art_or_vs	REAL	Probability that a person will start treatment and be virally suppressed following testing, from 2016 inputs reduced viral suppression rates to account for viral load testing effect
prob_behav_chg_after_hiv_test	REAL	Probability that a person will change risk behaviours, if HIV-negative, following testing
prob_prep_for_fsw_after_hiv_test	REAL	Probability that a FSW will start PrEP, if HIV-negative, following testing
prob_prep_for_agyw	REAL	Probability that adolescent girls / young women will start PrEP
prob_circ_after_hiv_test	REAL	Probability that a male will be circumcised, if HIV-negative, following testing
increase_in_prob_circ_2019	REAL	increase in probability that a male will be circumcised, if HIV-negative, following testingfrom 2019 onwards
prob_circ_for_child_before_2020	REAL	Probability that a male aging <15 yrs will be circumcised before year 2020
prob_circ_for_child_from_2020	REAL	Probability that a male aging <15 yrs will be circumcised from year 2020, which is different from before 2020 as children vmmc policy/fund/cases has changed, according to PEPFAR 2020 Country Operational Plan and DHIS2 data
probability_of_being_retained_on_prep_every_3_months	REAL	Probability that someone who has initiated on prep will attend an appointment and be on prep for the next 3 months, until the next appointment.
probability_of_being_retained_on_art_every_3_months	REAL	Probability that someone who has initiated on treatment will attend an appointment and be on treatment for next 3 months, until the next appointment.
probability_of_seeking_further_art_appointment_if_drug_not_available	REAL	Probability that a person who ‘should’ be on art will seek another appointment (the following day and try for each of the next 7 days) if drugs were not available.
probability_of_seeking_further_art_appointment_if_appointment_not_available	REAL	Probability that a person who ‘should’ be on art will seek another appointment if the health-system has not been able to provide them with an appointment
prep_start_year	REAL	Year from which PrEP is available
ART_age_cutoff_young_child	INT	Age cutoff for ART regimen for young children
ART_age_cutoff_older_child	INT	Age cutoff for ART regimen for older children
rel_probability_art_baseline_aids	REAL	relative probability of person with HIV infection over 10 years being on ART at baseline
aids_tb_death_rate_with_tb_treatment	REAL	probability of death if aids and tb, person on treatment for tb
aids_tb_death_rate_no_tb_treatment	REAL	probability of death if aids and tb, person not on treatment for tb
hiv_healthseekingbehaviour_cap	INT	number of repeat visits assumed for healthcare services
initial_dispensation_period_months	INT	length of prescription for ARVs in months for prescriptions pre-2021
dispensation_period_months	DATA_FRAME	prescription length probabilities for ARVs in months, varies by age/sex/year
dispensation_min_days	REAL	Minimum days to attain ARV dispensation
length_of_inpatient_stay_if_terminal	LIST	length in days of inpatient stay for end-of-life HIV patients: list has two elements [low-bound-inclusive, high-bound-exclusive]
aids_death_beddays_default	INT	Default number of bed days for end-of-life AIDS care
type_of_scaleup	STRING	argument to determine type scale-up of program which will be implemented, can be ‘none’, ‘target’ or ‘max’
scaleup_start_year	INT	the year when the scale-up starts (it will occur on 1st January of that year)
scaleup_parameters	DATA_FRAME	the parameters and values changed in scenario analysis
interval_for_viral_load_measurement_months	REAL	the interval for viral load monitoring in months
annual_rate_selftest	REAL	the annual rate of having an HIV self-test for those not on ART
selftest_start_year	REAL	the year in which HIV self-tests become available
selftest_available	BOOL	whether self-tests for HIV are available from the scale-up start date
young_adult_vls_factor	REAL	adjustment factor for viral load suppression probability for young adults compared to older adults
proportion_young_adult_on_art	REAL	proportion of adults on ART who are aged 15-29
prob_receive_viral_load_test_result	REAL	the probability of receiving viral load test result
sensitivity_viral_load_test	REAL	sensitivity of a viral load test
prob_of_viral_suppression_following_VL_test	REAL	the probability of viral suppression following a viral load test
viral_load_testing_start_year	INT	the year when the viral load testing starts (it will occur on 1st January of that year
delay_from_viral_load_to_result_months_min	REAL	the minimum delay in months from viral load test to receiving result, months
delay_from_viral_load_to_result_months_max	REAL	the maximum delay in months from viral load test to receiving result, months
tdf_test_replace_vl_test	BOOL	whether urine TDF test should replace viral load monitoring during follow-up appts
targeted_adherence_monitoring	BOOL	whether viral load monitoring or TDF testing should be targeted to specific groups
p_tdf_positive_given_suppressed	REAL	probability of a urine TDF test returning positive if person virally suppressed
p_tdf_positive_given_not_suppressed	REAL	probability of a urine TDF test returning positive if person not virally suppressed
switch_vl_test_to_tdf	BOOL	whether TDF urine test is being used in place of VL testing
injectable_prep_allowed	BOOL	whether injectable prep is allowed
prob_injectable_prep_vs_oral	REAL	probability of injectable prep vs oral prep, given if injectable_prep_allowed=True
linked_to_care_after_selftest	REAL	probability a person who has had a self-test will be linked to care
selftest_sensitivity	REAL	sensitivity of an HIV self-test
delay_from_selftest_to_facility_weibull_shape	REAL	Weibull distribution shape parameter for number of days between a self-test result and confirmatory test
delay_from_selftest_to_facility_weibull_scale	REAL	Weibull distribution scale parameter for number of days between a self-test result and confirmatory test
proportion_on_treatment_not_lost_to_follow_up	REAL	proportion of people who are lost to follow up due to not attending follow-up appointments
hiv_regular_polling_event_frequency_months	INT	Frequency in months for HivRegularPollingEvent
regular_polling_event_initialisation_delay_days	INT	Delay in days for initial HivRegularPollingEvent
hiv_check_properties_event_delay_months	INT	Delay in months for HivCheckPropertiesEvent, which checks configuration of all properties
baseline_year	INT	Baseline year at which simulation starts
end_year_circumcision_data	INT	End year for circumcision data availability
end_year_treatment_data	INT	End year for treatment data availability
end_year_testing_data	INT	End year for HIV testing data availability
years_since_infection_threshold_for_higher_art_probability	INT	Minimum years since HIV infection required to assign higher ART probability at baseline
years_offset_for_dummy_test_date_at_baseline	INT	Years prior to simulation start date to assign test date at baseline; Required for logical consistency so that all persons on ART have been tested and diagnosed,
age_threshold_child_adult_distinction	INT	Age threshold for child/adult distinction
age_max_adult	INT	Maximum age for adult categorization
age_max_infant	INT	Maximum age for infant categorization
age_default_adult	INT	Default age for adult viral suppression calculations
age_default_children	INT	Default age for children viral suppression calculations
age_min_agyw	INT	Minimum age for adolescent girls and young women (AGYW) category
age_max_agyw	INT	Maximum age for adolescent girls and young women (AGYW) category
age_max_prep	INT	Maximum age for PrEP eligibility
age_max_hiv_early_infant_test_years	REAL	Maximum age in years for early infant HIV test eligibility
age_max_prophylaxis_years	REAL	Maximum age in years for infant HIV prophylaxis
hiv_infection_to_aids_untreated_threshold_years	INT	Number of years after HIV infection at which a person is assumed to have AIDS if not virally suppressed on ART
prop_aids_death_is_tb_coinfection	REAL	Proportion of AIDS deaths that have TB co-infection
hiv_early_infant_test_sensitivity	REAL	Sensitivity of early infant HIV test
hiv_early_infant_test_specificity	REAL	Specificity of early infant HIV test
hv_min_test_interval_days	INT	Minimum interval in days between HIV tests
infant_hiv_test_first_weeks	INT	Timing of first infant HIV test in weeks after birth in weeks
infant_hiv_test_second_months	INT	Timing of second infant HIV test in months after birth in months
infant_hiv_test_third_months	INT	Timing of third infant HIV test in months after birth in months
hiv_testing_initial_window_for_individuals_with_aids_at_init_days	INT	Initial window in days for HIV testing via HSI event HSI_Test_and_Refer for individuals with AIDS at initialization
hiv_testing_close_window_for_individuals_with_aids_at_init_days	INT	Close window in days for HIV testing via HSI event HSI_Test_and_Referfor individuals with AIDS at initialization
odds_ratio_health_seeking_aids_symptoms_adults	REAL	Odds ratio for health seeking behavior in adults with AIDS symptoms
odds_ratio_health_seeking_aids_symptoms_children	REAL	Odds ratio for health seeking behavior in children with AIDS symptoms
hiv_prep_refill_appointment_window_days	INT	Window in days for PrEP refill appointments, checked if retained on prep every 3 months
prep_continuation_reevaluation_period_months	INT	Months between PrEP continuation re-evaluation appointments
prep_cons_notavailable_retry_days	INT	Days to retry PrEP appointment if consumables not available
art_continuation_appointment_window_days	INT	Window in days for ART continuation appointments
art_restart_appointment_delay_months	INT	Delay in months for scheduling ART restart appointment
art_drug_notavailable_default_retry_months	INT	Default months to retry ART appointment if drugs not available
art_level1a_healthseekingbehaviour_cap	INT	Maximum number of retry attempts at level 1a facility before referral
art_level1a_appointment_delay_months	INT	Delay in months for ART appointment retry at level 1a facility
art_level1b_appointment_delay_days	INT	Delay in days for ART appointment at level 1b facility after referral
seek_further_art_appointment_if_appointment_not_available_min_delay_days	INT	Minimum delay in days to seek further ART appointment if appointment not available
seek_further_art_appointment_if_appointment_not_available_max_delay_days	INT	Maximum delay in days to seek further ART appointment if appointment not available
hiv_circ_procedure_first_followup_days	INT	Days after circumcision procedure for first follow-up appointment
hiv_circ_procedure_second_followup_days	INT	Days after circumcision procedure for second follow-up appointment
hiv_circ_cons_notavailable_retry_procedure_weeks	INT	Weeks to retry circumcision procedure if consumables not available
infant_prophylaxis_followup_months	INT	Months after starting infant prophylaxis for follow-up appointment
infant_prophylaxis_cons_notavailable_retry_days	INT	Days to retry infant prophylaxis if consumables not available

PROPERTIES:

Item	Type	Description
hv_inf	BOOL	Is person currently infected with HIV (NB. AIDS status is determined by presence of the AIDS Symptom.
hv_art	CATEGORICAL	ART status of person, whether on ART or not; and whether viral load is suppressed or not if on ART.. Possible values are: [not, on_VL_suppressed, on_not_VL_suppressed, ]
hv_on_cotrimoxazole	BOOL	Whether the person is currently taking and receiving a malaria-protective effect from cotrimoxazole
hv_is_on_prep_oral	BOOL	Whether the person is currently taking and receiving a protective effect from oral Pre-Exposure Prophylaxis
hv_is_on_prep_inj	BOOL	Whether the person is currently taking and receiving a protective effect from injectable Pre-Exposure Prophylaxis
hv_behaviour_change	BOOL	Has this person been exposed to HIV prevention counselling following a negative HIV test result
hv_diagnosed	BOOL	Knows that they are HIV+: i.e. is HIV+ and tested as HIV+
hv_number_tests	INT	Number of HIV tests ever taken
hv_arv_dispensing_interval	REAL	Number of months of ARVs dispensed in current prescription
hv_last_test_date	DATE	Date of last HIV test
hv_date_inf	DATE	Date infected with HIV
hv_date_treated	DATE	date hiv treatment started
hv_date_last_ART	DATE	date of last ART dispensation
hv_VMMC_in_last_year	BOOL	whether VMMC was performed in the last year
hv_days_on_oral_prep_AGYW	INT	number of days spent on oral prep per logger time interval for AGYW
hv_days_on_oral_prep_FSW	INT	number of days spent on oral prep per logger time interval for FSW
hv_days_on_inj_prep_AGYW	INT	number of days spent on inj prep per logger time interval for AGYW
hv_days_on_inj_prep_FSW	INT	number of days spent on inj prep per logger time interval for FSW

Class attributes:

ADDITIONAL_DEPENDENCIES : {‘Tb’, ‘NewbornOutcomes’}

CAUSES_OF_DEATH : {‘AIDS_non_TB’: <tlo.methods.causes.Cause object at 0x13e892690>, ‘AIDS_TB’: <tlo.methods.causes.Cause object at 0x13e8901d0>}

CAUSES_OF_DISABILITY : {‘HIV’: <tlo.methods.causes.Cause object at 0x13e891b50>}

INIT_DEPENDENCIES : {‘HealthSystem’, ‘SymptomManager’, ‘Demography’, ‘Lifestyle’}

METADATA : {<Metadata.USES_HEALTHSYSTEM: 3>, <Metadata.REPORTS_DISEASE_NUMBERS: 5>, <Metadata.USES_SYMPTOMMANAGER: 2>, <Metadata.USES_HEALTHBURDEN: 4>, <Metadata.DISEASE_MODULE: 1>}

OPTIONAL_INIT_DEPENDENCIES : {‘HealthBurden’}

__annotations__ : {}

Functions (defined or overridden in class Hiv):

__init__(name=None, run_with_checks=False)

Construct a new disease module ready to be included in a simulation.

Initialises an empty parameters dictionary and module-specific random number generator.

Parameters:: name – the name to use for this module. Defaults to the concrete subclass’ name.

read_parameters(resourcefilepath: Path | None = None)

1. Reads the ResourceFiles
1. Declare the Symptoms

adjust_viral_load_suppression_rates(): Adjusts the ‘virally_suppressed_on_art’ column in a DataFrame using the VL testing adjustment formula.

pre_initialise_population(): Do things required before the population is created * Build the LinearModels

_build_linear_models(): Establish the Linear Models

initialise_population(population): Set our property values for the initial population.

initialise_baseline_prevalence(population): Assign baseline HIV prevalence, according to age, sex and key other variables (established in analysis of DHS data).

initialise_baseline_art(population): assign initial art coverage levels also assign hiv test properties if allocated ART probability of being on ART scaled by length of time infected (>10 years)

initialise_baseline_tested(population): assign initial hiv testing levels, only for adults all who have been allocated ART will already have property hv_diagnosed=True use the spectrum proportion PLHIV who know status to assign remaining tests

initialise_simulation(sim)

1. Schedule the Main HIV Regular Polling Event
1. Schedule the Logging Event
1. Determine who has AIDS and impose the Symptoms ‘aids_symptoms’
1. Schedule the AIDS onset events and AIDS death event for those infected already
1. (Optionally) Schedule the event to check the configuration of all properties
1. Define the DxTests
1. Look-up and save the codes for consumables

update_parameters_for_program_change(): options for program scale-up are ‘target’ or ‘max’ other options switch on / off various interventions

on_birth(mother_id, child_id)

Initialise our properties for a newborn individual;
schedule testing;
schedule infection during breastfeeding

report_daly_values(): Report DALYS for HIV, based on current symptomatic state of persons.

report_summary_stats()

mtct_during_breastfeeding(mother_id, child_id)

Compute risk of mother-to-child transmission and schedule HivInfectionDuringBreastFeedingEvent. If the child is breastfeeding currently, consider the time-until-infection assuming a constantly monthly risk of

transmission. If the breastfeeding has ceased by the time of the scheduled infection, then it will not run.

(This means that this event can be run at birth or at the time of the mother’s infection without the need for further polling etc.)

do_new_infection(person_id): Enact that this person is infected with HIV * Update their hv_inf status and hv_date_inf * Schedule the AIDS onset event for this person

sample_time_from_infection_to_aids_given_parameters(scale, shape, offset)

Generate time(s) between onset of infection and AIDS as Pandas time deltas.

The times are generated from translated Weibull distributions discretised to an integer number of months.

Parameters:

scale – Scale parameters of Weibull distributions (unit: years).
shape – Shape parameters of Weibull distributions.
offset – Offset to (negatively) shift Weibull variable by (unit: months).

Returns:

Generated time deltas.

get_time_from_infection_to_aids_distribution_parameters(person_ids)

Compute per-person parameters of distribution of time from infection to aids.

Evaluates three linear models which output age specific scale, shape and offset parameters for the (translated) Weibull distribution used to generate the time from infection to aids for an individual.

For those infected prior to, or at, birth, a Weibull distribution with shape parameter 1 (equivalent to an exponential distribution) is used.

For those infected after birth a Weibull distribution with both shape and scale depending on age is used.

Parameters:: person_ids – Iterable of ID indices of individuals to get parameters for.
Returns:: Per-person parameters as a 3-tuple (scale, shape, offset) of pandas.Series objects.

get_time_from_aids_to_death(): Gives time between onset of AIDS and death, returning a pd.DateOffset. Assumes that the time between onset of AIDS symptoms and deaths is exponentially distributed.

do_when_hiv_diagnosed(person_id): Things to do when a person has been tested and found (newly) to be HIV-positive:. * Consider if ART should be initiated, and schedule HSI if so. The person should not yet be on ART.

prob_art_start_after_test(year): returns the probability of starting ART after a positive HIV test this value for initiation can be higher than the current reported coverage levels to account for defaulters

prob_viral_suppression(df, year, age_of_person): returns the probability of viral suppression once on ART data from 2010-2025 from spectrum time-series ends at 2025

update_viral_suppression_status(): Helper function to determine whether person who is currently not virally suppressed will become virally suppressed following viral load test”

setup_art_dispensation_lookup(): Preprocess the dispensation probability table into a nested dict for fast lookup.

get_art_dispensation_length(year, person, currently_breastfeeding): Return ART dispensation duration (in months) based on year and person attributes

stops_treatment(person_id): Helper function that is called when someone stops being on ART. Sets the flag for ART status. If the person was already on ART, it schedules a new AIDSEvent

per_capita_testing_rate(): This calculates the numbers of hiv tests performed in each time period. It looks at the cumulative number of tests ever performed and subtracts the number calculated at the last time point. Values are converted to per capita testing rates. This function is called by the logger and can be called at any frequency

decide_whether_hiv_test_for_mother(person_id, referred_from) → bool: This will return a True/False for whether an HIV test should be scheduled for a mother; and schedule the HIV Test if a test should be scheduled. This is called from labour.py under interventions_delivered_pre_discharge and care_of_women_during_pregnancy.py. Mothers who are not already diagnosed will have an HIV test with a certain probability defined by a parameter;

mothers who are diagnosed already will not have another HIV test.

decide_whether_hiv_test_for_infant(mother_id, child_id) → None: This will schedule an HIV testing HSI for a child under certain conditions. It is called from newborn_outcomes.py under hiv_screening_for_at_risk_newborns.

perform_tdf_test(is_suppressed: bool) → bool

Simulate TDF urine test result based on known viral suppression status.

Parameters: - is_suppressed (bool): True if the person is virally suppressed, False if not.

Returns: - true (positive) or false (negative) based on test result

check_config_of_properties(): check that the properties are currently configured correctly

do_at_generic_first_appt(person_id: int, symptoms: List[str], schedule_hsi_event: HSIEventScheduler, **kwargs) → None

Actions to take during a non-emergency generic health system interaction (HSI).

Derived classes should overwrite this method so that they are compatible with the HealthSystem module, and can schedule HSI events when a individual presents symptoms indicative of the corresponding illness or condition.

When overwriting, arguments that are not required can be left out of the definition. If done so, the method must take a **kwargs input to avoid errors when looping over all disease modules and running their generic HSI methods.

HSI events should be scheduled by the Module subclass implementing this method using the schedule_hsi_event argument.

Implementations of this method should not make any updates to the population dataframe directly - if the target individuals properties need to be updated this should be performed by updating the individual_properties argument.

Parameters:

person_id – Row index (ID) of the individual target of the HSI event in the population dataframe.
individual_properties – Properties of individual target as provided in the population dataframe. Updates to individual properties may be written to this object.
symptoms – List of symptoms the patient is experiencing.
schedule_hsi_event – A function that can schedule subsequent HSI events.
diagnosis_function – A function that can run diagnosis tests based on the patient’s symptoms.
consumables_checker – A function that can query the health system to check for available consumables.
facility_level – The level of the facility that the patient presented at.
treatment_id – The treatment id of the HSI event triggering the generic appointment.

class HivRegularPollingEvent(module)

The HIV Regular Polling Events * Schedules persons becoming newly infected through horizontal transmission * Schedules who will present for voluntary (“spontaneous”) testing

Create a new regular event.

Parameters:

module – the module that created this event
frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HivRegularPollingEvent):

__init__(module)

Create a new regular event.

Parameters:

module – the module that created this event
frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

apply(population)

Apply this event to the given target.

This is a no-op; subclasses should override this method.

Parameters:: target – the target of the event

class HivInfectionEvent(module, person_id)

This person will become infected. * Do the infection process * Check for onward transmission through MTCT if the infection is to a mother who is currently breastfeeding.

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

Bases: tlo.events.Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class HivInfectionEvent):

__init__(module, person_id)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

apply(person_id)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:: target – the target of the event

class HivInfectionDuringBreastFeedingEvent(module, person_id)

This person will become infected during breastfeeding * Do the infection process

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

Bases: tlo.events.Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class HivInfectionDuringBreastFeedingEvent):

__init__(module, person_id)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

apply(person_id)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:: target – the target of the event

class HivAidsOnsetEvent(module, person_id, cause)

This person has developed AIDS. * Update their symptomatic status * Record the date at which AIDS onset * Schedule the AIDS death

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

Bases: tlo.events.Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class HivAidsOnsetEvent):

__init__(module, person_id, cause)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

apply(person_id)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:: target – the target of the event

class HivAidsDeathEvent(module, person_id, cause)

Causes someone to die of AIDS, if they are not VL suppressed on ART. if death scheduled by tb-aids, death event is HivAidsTbDeathEvent if death scheduled by hiv but person also has active TB, cause of death is AIDS_TB

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

Bases: tlo.events.Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class HivAidsDeathEvent):

__init__(module, person_id, cause)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

apply(person_id)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:: target – the target of the event

class HivAidsTbDeathEvent(module, person_id, cause)

This event is caused by someone co-infected with HIV and active TB it causes someone to die of AIDS-TB, death dependent on tb treatment status and not affected by ART status can be called by Tb or Hiv module if the random draw doesn’t result in AIDS-TB death, an AIDS death (HivAidsDeathEvent) will be scheduled

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

Bases: tlo.events.Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class HivAidsTbDeathEvent):

__init__(module, person_id, cause)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

apply(person_id)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:: target – the target of the event

class Hiv_DecisionToContinueOnPrEP(module, person_id, type_of_prep)

Helper event that is used to ‘decide’ if someone on PrEP should continue on PrEP. This event is scheduled by ‘HSI_Hiv_StartOrContinueOnPrep’ 3 months after it is run.

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

Bases: tlo.events.Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class Hiv_DecisionToContinueOnPrEP):

__init__(module, person_id, type_of_prep)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

apply(person_id)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:: target – the target of the event

class Hiv_DecisionToContinueTreatment(module, person_id)

Helper event that is used to ‘decide’ if someone on Treatment should continue on Treatment. This event is scheduled by ‘HSI_Hiv_StartOrContinueTreatment’ 3 months after it is run.

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

Bases: tlo.events.Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class Hiv_DecisionToContinueTreatment):

__init__(module, person_id)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

apply(person_id)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:: target – the target of the event

class Hiv_AdherenceCounselling(module, person_id)

Helper event that is used to ‘decide’ if someone on Treatment who is not currently virally suppressed will become suppressed

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

Bases: tlo.events.Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class Hiv_AdherenceCounselling):

__init__(module, person_id)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

apply(person_id)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:: target – the target of the event

class HivScaleUpEvent(module)

This event exists to change parameters or functions depending on the scenario for projections which has been set It only occurs once on date: scaleup_start_date, called by initialise_simulation

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

Bases: tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HivScaleUpEvent):

__init__(module)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.
priority – a keyword-argument to set the priority (see Priority enum)

apply(population)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:: target – the target of the event

class HSI_Hiv_SelfTest(module, person_id)

This is the HIV Self-test HSI. No consumables currently logged for HIV self-tests so counter can record numbers of tests given

Self-tests are available from 2023 onwards and can be switched off via parameter selfttest_available Self-testing is scheduled via the regular poll and a positive result prompts a referral for a confirmatory test at a facility

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HSI_Hiv_SelfTest):

__init__(module, person_id)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

apply(person_id, squeeze_factor): Do the testing and referring to other services

class HSI_Hiv_TestAndRefer(module, person_id, do_not_refer_if_neg=False, suppress_footprint=False, referred_from=None)

This is the Test-and-Refer HSI. Individuals may seek an HIV test at any time. From this, they can be referred on to other services. This event is scheduled by:

the main event poll,

when someone presents for any care through a Generic HSI.

when an infant is born to an HIV-positive mother

Following the test, they may or may not go on to present for uptake an HIV service: ART (if HIV-positive), VMMC (if HIV-negative and male) or PrEP (if HIV-negative and a female sex worker). If this event is called within another HSI, it may be desirable to limit the functionality of the HSI: do this using the arguments:

do_not_refer_if_neg=False : if the person is HIV-neg they will not be referred to VMMC or PrEP

suppress_footprint=True : the HSI will not have any footprint

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HSI_Hiv_TestAndRefer):

__init__(module, person_id, do_not_refer_if_neg=False, suppress_footprint=False, referred_from=None)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

apply(person_id, squeeze_factor): Do the testing and referring to other services

class HSI_Hiv_Circ(module, person_id)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HSI_Hiv_Circ):

__init__(module, person_id)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

apply(person_id, squeeze_factor): Do the circumcision for this man. If he is already circumcised, this is a follow-up appointment.

class HSI_Hiv_StartInfantProphylaxis(module, person_id, referred_from, repeat_visits)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HSI_Hiv_StartInfantProphylaxis):

__init__(module, person_id, referred_from, repeat_visits)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

apply(person_id, squeeze_factor): Start infant prophylaxis for this infant lasting for duration of breastfeeding or up to 18 months

never_ran(*args, **kwargs): This is called if this HSI was never run. Default the person to being off PrEP

class HSI_Hiv_StartOrContinueOnPrep(module, person_id, type_of_prep)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HSI_Hiv_StartOrContinueOnPrep):

__init__(module, person_id, type_of_prep)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

get_prep_column()

apply(person_id, squeeze_factor): Start PrEP for this person; or continue them on PrEP for 3 more months

never_ran(): This is called if this HSI was never run. Default the person to being off PrEP

class HSI_Hiv_StartOrContinueTreatment(module, person_id, facility_level_of_this_hsi)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

EXPECTED_APPT_FOOTPRINT : <property object at 0x13e627880>

__annotations__ : {}

Functions (defined or overridden in class HSI_Hiv_StartOrContinueTreatment):

__init__(module, person_id, facility_level_of_this_hsi)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

apply(person_id, squeeze_factor): This is a Health System Interaction Event - start or continue HIV treatment for 6 more months

do_at_initiation(person_id): Things to do when this the first appointment ART

do_at_continuation(person_id): Things to do when the person is already on ART

determine_vl_status(age_of_person, df): Helper function to determine the VL status that the person will have. Return what will be the status of “hv_art”

decide_test_policy(person_id): Decide (a) the probability a person is offered a VL test this encounter, and (b) which test (‘VL’, ‘TDF’).

get_drugs(age_of_person, dispensation_interval): Helper function to get the ART according to the age of the person being treated. Returns dict to indicate whether individual drugs were available

consider_tb(person_id): screen for tb Consider whether IPT is needed at this time. This is run only when treatment is initiated.

never_ran(): This is called if this HSI was never run. * Default the person to being off ART. * Determine if they will re-seek care themselves in the future:

class HSI_Hiv_EndOfLifeCare(module, person_id, beddays=None)

this is a hospital stay for terminally-ill patients with AHD it does not affect disability weight or probability of death no consumables are logged but health system capacity (HR) is allocated there are no consequences if hospital bed is not available as person has scheduled death already within 2 weeks

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HSI_Hiv_EndOfLifeCare):

__init__(module, person_id, beddays=None)

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters:: module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

apply(person_id, squeeze_factor)

Apply this event to the population.

Must be implemented by subclasses.

class HivLoggingEvent(module)

Log Current status of the population, every year

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HivLoggingEvent):

__init__(module): Log Current status of the population, every year

apply(population)

Apply this event to the given target.

This is a no-op; subclasses should override this method.

Parameters:: target – the target of the event

class HivCheckPropertiesEvent(module)

Create a new regular event.

Parameters:

module – the module that created this event
frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HivCheckPropertiesEvent):

__init__(module)

Create a new regular event.

Parameters:

module – the module that created this event
frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

apply(population)

Apply this event to the given target.

This is a no-op; subclasses should override this method.

Parameters:: target – the target of the event

class DummyHivModule(name=None, hiv_prev=0.1, art_cov=0.75)

Dummy HIV Module - it’s only job is to create and maintain the ‘hv_inf’ and ‘hv_art’ properties. This can be used in test files.

Construct a new disease module ready to be included in a simulation.

Initialises an empty parameters dictionary and module-specific random number generator.

Parameters:: name – the name to use for this module. Defaults to the concrete subclass’ name.

Bases: tlo.core.Module

PROPERTIES:

Item	Type	Description
hv_inf	BOOL	DUMMY version of the property for hv_inf
hv_art	CATEGORICAL	DUMMY version of the property for hv_art.. Possible values are: [not, on_VL_suppressed, on_not_VL_suppressed, ]
hv_diagnosed	BOOL	DUMMY version of the property for hv_diagnosed.

Class attributes:

ALTERNATIVE_TO : {‘Hiv’}

INIT_DEPENDENCIES : {‘Demography’}

__annotations__ : {}

Functions (defined or overridden in class DummyHivModule):

__init__(name=None, hiv_prev=0.1, art_cov=0.75)

Construct a new disease module ready to be included in a simulation.

Initialises an empty parameters dictionary and module-specific random number generator.

Parameters:: name – the name to use for this module. Defaults to the concrete subclass’ name.

read_parameters(resourcefilepath: Path | None = None)

Read parameter values from file, if required.

Must be implemented by subclasses.

Parameters:: data_folder – path of a folder supplied to the Simulation containing data files. Typically, modules would read a particular file within here.

initialise_population(population)

Set our property values for the initial population.

This method is called by the simulation when creating the initial population, and is responsible for assigning initial values, for every individual, of those properties ‘owned’ by this module, i.e. those declared in its PROPERTIES dictionary.

By default, all Property``s in ``self.PROPERTIES will have their columns in the population dataframe set to the default value.

Modules that wish to implement this behaviour do not need to implement this method, it will be inherited automatically. Modules that wish to perform additional steps during the initialise_population stage should reimplement this method and call

`python super().initialise_population(population=population) `

at the beginning of the method, then proceed with their additional steps. Modules that do not wish to inherit this default behaviour should re-implement initialise_population without the call to super() above.

TODO: We probably need to declare somehow which properties we ‘read’ here, so the simulation knows what order to initialise modules in!

Parameters:: population – The population of individuals in the simulation.

initialise_simulation(sim)

Get ready for simulation start.

Must be implemented by subclasses.

This method is called just before the main simulation loop begins, and after all modules have read their parameters and the initial population has been created. It is a good place to add initial events to the event queue.

on_birth(mother, child)

Initialise our properties for a newborn individual.

Must be implemented by subclasses.

This is called by the simulation whenever a new person is born.

Parameters:

mother_id – the person id for the mother of this child (can be -1 if the mother is not identified).
child_id – the person id of new child