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 is 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, resourcefilepath=None, run_with_checks=False)

The HIV Disease Module

Bases: tlo.core.Module

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_behaviour_change	REAL	Relative risk of HIV with behaviour modification
proportion_reduction_in_risk_of_hiv_aq_if_on_prep	REAL	Proportion reduction in risk of HIV acquisition if on PrEP. 0 for no efficacy; 1.0 for perfect efficacy.
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
treatment_initiation_adjustment	REAL	adjustment to current ART coverage levels to account for defaulters
vs_adjustment	REAL	adjustment to current viral suppression levels to account for defaulters
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
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
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_treatment_adjustment	REAL	probability of death if aids and tb, person on treatment for tb
dispensation_period_months	REAL	length of prescription for ARVs in months, same for all PLHIV

PROPERTIES:

Item	Type	Description
hv_inf	BOOL	Is person currently infected with HIV (NB. AIDS status is determined by prescence 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	BOOL	Whether the person is currently taking and receiving a protective effect from 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_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

Class attributes:

ADDITIONAL_DEPENDENCIES : {‘Tb’, ‘NewbornOutcomes’}

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

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

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

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

OPTIONAL_INIT_DEPENDENCIES : {‘HealthBurden’}

Functions (defined or overridden in class Hiv):

__init__(name=None, resourcefilepath=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(data_folder)

• 1. Reads the ResourceFiles

• 2. Declare the Symptoms

pre_initialise_population()

• 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

• 2. Schedule the Logging Event

• 3. Determine who has AIDS and impose the Symptoms ‘aids_symptoms’

• 4. Schedule the AIDS onset events and AIDS death event for those infected already

• 5. (Optionally) Schedule the event to check the configuration of all properties

• 6. Define the DxTests

• 7. Look-up and save the codes for consumables

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.

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) be 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(year, age_of_person)

returns the probability of viral suppression once on ART data from 2012 - 2020 from spectrum assume constant values 2010-2012 and 2020 on time-series ends at 2025

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.

check_config_of_properties()

check that the properties are currently configured correctly

do_at_generic_first_appt(patient_id: int, symptoms: List[str], **kwargs) → Dict[str, Any]

Actions to be take during a NON-emergency generic HSI.

Derived classes should overwrite this method so that they are compatible with the HealthSystem module, and can schedule HSI events when a patient 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 implementing this method using the Module.healthsystem.schedule_hsi() method. However, they should not write updates back to the population DataFrame in this method - these values should be returned as a dictionary as described below:

The return value of this function should be a dictionary containing any changes that need to be made to the individual’s row in the population DataFrame. Key/value pairs should be the column name and the new value to assign to the patient. In the event no updates are required; return an object that evaluates to False when cast to a bool. Your options are: - Omit a return statement and value (preferred). - Return an empty dictionary. Use this case when patient details might need updating conditionally, on EG patient symptoms or consumable availability. In which case, an empty dictionary should be created and key-value pairs added to this dictionary as such conditionals are checked. If no conditionals are met, the empty dictionary will be returned. - Use a return statement with no values (use if the logic of your module-specific method necessitates the explicit return). - Return None (not recommended, use “return” on its own, as above).

Parameters:

• patient_id – Row index (ID) of the individual target of the HSI event in the population DataFrame.

• patient_details – Patient details as provided in the population DataFrame.

• symptoms – List of symptoms the patient is experiencing.

• diagnosis_function – A function that can run diagnosis tests based on the patient’s symptoms.

• consumables_checker – A function that can query the HealthSystem 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.

• random_state – Random number generator to be used when making random choices during event creation.

class HivRegularPollingEvent(module)

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

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.

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

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

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

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

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)

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.

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

Functions (defined or overridden in class Hiv_DecisionToContinueOnPrEP):

__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_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.

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 HSI_Hiv_TestAndRefer(module, person_id, do_not_refer_if_neg=False, suppress_footprint=False, referred_from=None)

The 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

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)

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)

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)

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)

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 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)

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

Class attributes:

EXPECTED_APPT_FOOTPRINT : <property object at 0x124d848b0>

__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)

Helper function to determine the VL status that the person will have. Return what will be the status of “hv_art”

get_drugs(age_of_person)

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 HivLoggingEvent(module)

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)

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.

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, ]

Class attributes:

ALTERNATIVE_TO : {‘Hiv’}

INIT_DEPENDENCIES : {‘Demography’}

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(data_folder)

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.

Must be implemented by subclasses.

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.

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

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