HIV Comorbidity Module

This module implements HIV disease modeling and its interactions with tuberculosis, including disease progression, ART treatment, and TB-HIV connectors.

HIV Disease Model

class tbsim.comorbidities.hiv.hiv.HIVState(value)[source]

Bases: IntEnum

Enum representing the possible HIV states an agent can be in.

States:

  • ATRISK: Agent is HIV-negative but at risk.

  • ACUTE: Recently infected with HIV.

  • LATENT: Chronic HIV infection.

  • AIDS: Advanced stage of HIV infection.

ATRISK = 0
ACUTE = 1
LATENT = 2
AIDS = 3
class tbsim.comorbidities.hiv.hiv.HIV(*args: Any, **kwargs: Any)[source]

Bases: Disease

A simplified agent-based HIV disease model for use with the Starsim framework.

This model tracks HIV state progression through ACUTE, LATENT, and AIDS phases, influenced by whether the agent is receiving ART (antiretroviral therapy).

Key Features:

  • Initial infection and ART status are assigned during the first timestep, unless a high-level intervention labeled ‘hivinterventions’ is present.

  • Disease progression is stochastic and modified by ART presence.

  • ART reduces the probability of progression from ACUTE → LATENT and LATENT → AIDS.

  • AIDS → DEAD transition is defined but not applied in this model.

Parameters:

  • init_prev (-) – Initial probability of infection (ACUTE).

  • init_onart (-) – Probability of being on ART at initialization (if infected).

  • acute_to_latent (-) – Daily transition probability from ACUTE to LATENT.

  • latent_to_aids (-) – Daily transition probability from LATENT to AIDS.

  • aids_to_dead (-) – Daily transition probability from AIDS to DEAD (unused).

  • art_progression_factor (-) – Multiplier applied to progression probabilities for agents on ART.

States:

  • state: HIV progression state (ATRISK, ACUTE, LATENT, AIDS, DEAD).

  • on_ART: Boolean indicating whether agent is on ART.

Results Tracked:

  • hiv_prevalence: Proportion of total agents with HIV.

  • infected: Total number of HIV-positive agents.

  • on_art: Number of agents on ART.

  • atrisk, acute, latent, aids: Percent of population in each state.

  • n_active: Total number of agents in ACUTE, LATENT, or AIDS states.

__init__(pars=None, **kwargs)[source]
set_prognoses()[source]

Initialize HIV infection and ART status for agents in the simulation.

This method is called at the beginning of the simulation (time index 0) to assign initial disease states and treatment (ART) status.

Behavior:

  • If a high-level intervention labeled ‘hivinterventions’ is present in the simulation,

initialization is skipped entirely, assuming that the intervention will handle infection and ART assignments dynamically at the appropriate time. - If no HIV states are currently set to ACUTE, a subset of agents is randomly assigned to ACUTE based on the init_prev parameter. - If no agents are currently on ART, a subset of those in the ACUTE state is randomly assigned to be on ART based on the init_onart parameter.

Notes

  • This check ensures the model does not reinitialize infected or ART states

if they’ve already been set or will be handled externally. - It also avoids reapplying ART if ART status was assigned previously.

Returns:

None

step()[source]

Update state transitions based solely on state and ART. If an agent is on ART, progression probabilities are reduced.

init_results()[source]
update_results()[source]

HIV State Enumeration

Enum representing the possible HIV states an agent can be in.

States:

  • ATRISK: Agent is HIV-negative but at risk.

  • ACUTE: Recently infected with HIV.

  • LATENT: Chronic HIV infection.

  • AIDS: Advanced stage of HIV infection.

HIV Interventions

TB-HIV Connector

class tbsim.comorbidities.hiv.tb_hiv_cnn.TB_HIV_Connector(pars=None, **kwargs)[source]

Bases: Connector

Connector between TB and HIV.

This connector uses the HIV state ( ACUTE, LATENT, AIDS) from the HIV disease model to modify TB progression parameters.

Adjustments:
  • TB-infected individuals have increased:

    • Risk of progression from latent TB to presymptomatic TB (via rr_activation)

State multipliers:

  • ACUTE: 1.5

  • LATENT: 2.0

  • AIDS: 3.0

__init__(pars=None, **kwargs)[source]
static compute_tb_hiv_risk_rr(self, tb, hiv, uids, base_factor=1.0)[source]

Computes the relative risk (RR) multiplier for TB progression and mortality based on HIV state and ART (antiretroviral therapy) status. :param tb: The TB model object (not directly used in this function). :type tb: object :param hiv: The HIV model object containing state and ART status information. :type hiv: object :param uids: Array of unique identifiers for individuals. :type uids: array-like :param base_factor: A base multiplier applied to the computed RR.

Defaults to 1.0.

Returns:

An array of relative risk multipliers for the given individuals.

Return type:

numpy.ndarray

Notes

  • The function initializes the RR multipliers to 1.0 for all individuals.

  • It applies state-specific multipliers based on the individual’s HIV state.

  • The final RR is scaled by the base_factor parameter.

step()[source]

This is where the actual modification of TB parameters occurs.

Model Overview

The HIV comorbidity module provides comprehensive modeling of HIV infection and its bidirectional interactions with tuberculosis:

HIV Disease States

  • ATRISK (0): HIV-negative but at risk

  • ACUTE (1): Recently infected with HIV

  • LATENT (2): Chronic HIV infection

  • AIDS (3): Advanced stage of HIV infection

Disease Progression

  • Stochastic progression through HIV states

  • ART treatment effects on progression rates

  • Age and risk factor considerations

  • Natural history modeling

TB-HIV Interactions

  • HIV modifies TB progression and mortality risks

  • State-specific risk multipliers (ACUTE: 1.22x, LATENT: 1.90x, AIDS: 2.60x)

  • ART effects on TB-HIV interactions

  • Bidirectional disease dynamics

Key Features

HIV Disease Modeling

  • Initial infection and ART status assignment

  • Disease progression through ACUTE → LATENT → AIDS

  • ART treatment effects on progression rates

  • Population-level prevalence and incidence tracking

Intervention Framework

  • Prevalence adjustment to target levels

  • ART coverage management

  • Age-specific targeting

  • Dynamic intervention timing

TB-HIV Integration

  • Risk ratio calculations for TB progression

  • State-dependent risk modifications

  • ART status consideration in risk calculations

  • Real-time parameter adjustment during simulation

Usage Examples

Basic HIV simulation:

from tbsim.comorbidities.hiv.hiv import HIV
import starsim as ss

sim = ss.Sim(diseases=HIV())
sim.run()

With custom parameters:

from tbsim.comorbidities.hiv.hiv import HIV

hiv = HIV(pars={
    'init_prev': 0.15,           # 15% initial HIV prevalence
    'init_onart': 0.60,          # 60% of infected on ART initially
    'acute_to_latent': 0.1,      # Progression rate from acute to latent
    'latent_to_aids': 0.05,      # Progression rate from latent to AIDS
    'art_progression_factor': 0.1 # ART reduces progression by 90%
})

sim = ss.Sim(diseases=hiv)
sim.run()

HIV interventions:

from tbsim.comorbidities.hiv.intervention import HivInterventions

# Create HIV intervention
hiv_intervention = HivInterventions(pars={
    'mode': 'both',              # Apply both prevalence and ART adjustments
    'prevalence': 0.20,          # Target 20% HIV prevalence
    'percent_on_ART': 0.775,     # Target 77.5% ART coverage
    'start': ss.date('2000-01-01'),
    'stop': ss.date('2035-12-31')
})

sim.add_intervention(hiv_intervention)
sim.run()

TB-HIV integration:

from tbsim.comorbidities.hiv.tb_hiv_cnn import TB_HIV_Connector
from tbsim import TB, HIV

# Add both diseases and connector for interactions
connector = TB_HIV_Connector(pars={
    'acute_multiplier': 1.5,     # Custom risk multiplier for acute HIV
    'latent_multiplier': 2.0,    # Custom risk multiplier for latent HIV
    'aids_multiplier': 3.0       # Custom risk multiplier for AIDS
})

sim = ss.Sim(
    diseases=[TB(), HIV()],
    connectors=connector
)
sim.run()

Accessing results:

# HIV-specific results
hiv_results = hiv.results
hiv_prevalence = hiv_results.hiv_prevalence
art_coverage = hiv_results.on_art
state_distribution = {
    'atrisk': hiv_results.atrisk,
    'acute': hiv_results.acute,
    'latent': hiv_results.latent,
    'aids': hiv_results.aids
}

# Current states
current_hiv_states = hiv.state
on_art_status = hiv.on_ART

Mathematical Framework

HIV Progression

  • Exponential progression rates between states

  • ART modification: effective_rate = base_rate × art_factor

  • State-specific progression probabilities

TB-HIV Risk Ratios

  • RR_activation = base_rate × HIV_multiplier

  • Multipliers: ACUTE (1.22), LATENT (1.90), AIDS (2.60)

  • Real-time adjustment during simulation

Intervention Effects

  • Prevalence targeting with age constraints

  • ART coverage management with eligibility criteria

  • Dynamic parameter adjustment based on targets

For detailed information about specific methods and parameters, see the individual class documentation above. All methods include comprehensive mathematical models and implementation details in their docstrings.