diseases.hiv
diseases.hiv
Define HIV disease module
Classes
| Name | Description |
|---|---|
| HIV | HIV disease module. |
| HIVPars | Parameters for the HIV disease module. |
HIV
diseases.hiv.HIV(
pars=None,
init_prev_data=None,
age_bins=default_age_bins,
sex_keys=default_sex_keys,
**kwargs,
)HIV disease module.
Models HIV infection with CD4-driven natural history (acute, latent, and falling stages), ART treatment with CD4 reconstitution, diagnosis tracking, and AIDS-related mortality. Supports mother-to-child transmission when a pregnancy demographic module is present.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| pars | dict | Override default parameters from HIVPars. |
None |
| init_prev_data | Optional initial prevalence data by age/sex/risk group. | None |
|
| age_bins | list | Bin edges for age-stratified results; None skips them entirely. |
default_age_bins |
| sex_keys | dict | Sex strata for results; None skips sex-stratified results. |
default_sex_keys |
| **kwargs | Additional parameters passed to update_pars. |
{} |
Methods
| Name | Description |
|---|---|
| acute_decline | Acute decline in CD4 |
| cd4_increase | Increase CD4 counts for people who are receiving treatment. |
| circumcise | Mark agents as circumcised. Idempotent: already-circumcised agents in |
| falling_decline | Decline in CD4 during late-stage infection, when counts are falling |
| get_art_mortality_hazard | Per-timestep HIV death probability for agents currently on ART. |
| init_care_seeking | Set care seeking behavior |
| init_cd4 | Set CD4 counts |
| init_post | Set states |
| init_results | Initialize results |
| make_p_hiv_death | Calculate per-timestep HIV death probability based on current CD4 count. |
| plot | Plot key HIV results |
| post_art_decline | Decline in CD4 after going off treatment |
| set_prognoses | Set prognoses upon infection |
| start_art | Check who is ready to start ART treatment and put them on ART |
| start_prep | Start a PrEP course for uids not already on PrEP |
| step_die | Clear all states for dead agents |
| step_state | Carry out autonomous updates at the start of the timestep (prior to transmission) |
| stop_art | Check who is stopping ART treatment and put them off ART |
| stop_prep | Stop PrEP for uids, or (if None) everyone whose current course has expired. |
| update_results | Update results at each time step |
| update_transmission | Update rel_trans and rel_sus for all agents. These are reset on each timestep then adjusted depending on states. |
acute_decline
diseases.hiv.HIV.acute_decline(uids)Acute decline in CD4
cd4_increase
diseases.hiv.HIV.cd4_increase(uids)Increase CD4 counts for people who are receiving treatment. Growth curves are calculated to match EMODs CD4 reconstitution equation for people who initiate treatment with a CD4 count of 50 (https://docs.idmod.org/projects/emod-hiv/en/latest/hiv-model-healthcare-systems.html) However, here we use a logistic growth function and assume that ART CD4 count depends on CD4 at initiation. Sources:
- https://i-base.info/guides/starting/cd4-increase
- https://www.sciencedirect.com/science/article/pii/S1876034117302022
- https://bmcinfectdis.biomedcentral.com/articles/10.1186/1471-2334-8-20circumcise
diseases.hiv.HIV.circumcise(uids, traditional=False)Mark agents as circumcised. Idempotent: already-circumcised agents in uids keep their original circ_traditional/ti_circumcised, so a traditional-MC pass can’t overwrite someone circumcised by a program.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | agents to circumcise | required | |
| traditional | False=program (medical) VMMC (default), True=traditional (non-program) | False |
falling_decline
diseases.hiv.HIV.falling_decline(uids)Decline in CD4 during late-stage infection, when counts are falling
get_art_mortality_hazard
diseases.hiv.HIV.get_art_mortality_hazard(uids)Per-timestep HIV death probability for agents currently on ART.
Anchored to the off-ART CD4-based hazard (same cd4_death_bins/ cd4_death_rates/rel_death/rel_death_f used by make_p_hiv_death, at the agent’s CURRENT CD4) rather than an independent baseline + CD4 table:
rate = off_art_rate(cd4, sex) * rel_art_mortality[effective? / sex] * age_mult(age)rel_art_mortality_unsupp is sex-specific (rel_art_mortality_unsupp_m/f) so the non-suppressive/effective mortality RATIO can differ by sex (currently 2x higher for men than women); rel_art_mortality_effective and rel_death_f are not adherence-specific, so they don’t affect that ratio – rel_death_f is folded into off_art_rate itself (shared with make_p_hiv_death), so it applies equally on- and off-ART and cancels out of the ratio. Anchoring to off_art_rate guarantees, by construction, that on-ART mortality can never exceed off-ART mortality at the same CD4 count – as long as rel_art_mortality_effective/unsupp_m/unsupp_f times the largest age/duration multiplier stays <= 1 (true for the shipped defaults; see the note by those pars in HIVPars).
init_care_seeking
diseases.hiv.HIV.init_care_seeking()Set care seeking behavior
init_cd4
diseases.hiv.HIV.init_cd4()Set CD4 counts
init_post
diseases.hiv.HIV.init_post()Set states
init_results
diseases.hiv.HIV.init_results()Initialize results
make_p_hiv_death
diseases.hiv.HIV.make_p_hiv_death(uids=None)Calculate per-timestep HIV death probability based on current CD4 count.
Reads bins/rates from pars.cd4_death_bins/cd4_death_rates, scales by pars.rel_death and pars.rel_death_f (females), then converts from per-year to per-timestep probabilities. This is the same off-ART baseline that get_art_mortality_hazard anchors on-ART mortality to.
plot
diseases.hiv.HIV.plot()Plot key HIV results
post_art_decline
diseases.hiv.HIV.post_art_decline(uids)Decline in CD4 after going off treatment This implementation has the possibly-undesirable feature that a person who goes on ART for a year and then off again might have a slightly shorter lifespan than if they’d never started treatment.
set_prognoses
diseases.hiv.HIV.set_prognoses(uids, sources=None, ti=None)Set prognoses upon infection
start_art
diseases.hiv.HIV.start_art(uids, p_effective_art=None)Check who is ready to start ART treatment and put them on ART
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | agents starting ART treatment | required | |
| p_effective_art | float / ss.Dist |
probability that each agent achieves viral suppression (effective ART) rather than non-suppressive ART. Pass a float to override self.pars.p_effective_art’s probability, or an already-initialized ss.Dist (e.g. an intervention’s own par) to use it directly. Defaults to self.pars.p_effective_art (default: always effective). |
None |
start_prep
diseases.hiv.HIV.start_prep(uids, eff, dur, source_id, adh=1.0)Start a PrEP course for uids not already on PrEP
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | agents to start | required | |
| eff | base efficacy (0-1) of this course when fully adherent | required | |
| dur | course duration (an ss.dur/Time value) before renewal is needed | required | |
| source_id | numeric id of the enrolling Prep instance (for that instance’s own coverage-target accounting) | required | |
| adh | adherence level (0-1), multiplied into eff to get the realized efficacy (default 1.0 = fully adherent, i.e. realized eff == eff) | 1.0 |
Returns
| Name | Type | Description |
|---|---|---|
| The subset of uids actually started (already-on-PrEP agents excluded). |
step_die
diseases.hiv.HIV.step_die(uids)Clear all states for dead agents
step_state
diseases.hiv.HIV.step_state()Carry out autonomous updates at the start of the timestep (prior to transmission)
stop_art
diseases.hiv.HIV.stop_art(uids=None)Check who is stopping ART treatment and put them off ART
stop_prep
diseases.hiv.HIV.stop_prep(uids=None)Stop PrEP for uids, or (if None) everyone whose current course has expired.
update_results
diseases.hiv.HIV.update_results()Update results at each time step
update_transmission
diseases.hiv.HIV.update_transmission()Update rel_trans and rel_sus for all agents. These are reset on each timestep then adjusted depending on states. Adjustments are made throughout different modules:
- rel_trans for acute and late-stage untreated infection are adjusted below
- rel_trans for all people on treatment (including pregnant women) below
- rel_sus for unborn babies of pregnant WLHIV receiving treatment is adjusted in the ART intervention
HIVPars
diseases.hiv.HIVPars(**kwargs)Parameters for the HIV disease module.
Holds natural history parameters (CD4 dynamics, acute/latent/falling stage durations), transmission rates, ART treatment effects, and care-seeking behavior configuration.