HIV model tutorials and examples¶

The EMOD HIV model is explained in detail in HIV model overview. While the various components that comprise the model are explained with examples, it may be more useful to learn the model through hands-on implementation. The following sections will introduce sets of example files that illustrate how the HIV model works on particular topics. All files are available in the downloadable EMODScenarios folder, and in addition to the explanations below, each scenario will have a more detailed README file to cover relevant information. Within the EMODScenarios > Scenarios > HIV folder is an Excel worksheet titled “Weibull.xlsx,” which can be used to explore how Weibull parameters influence the shape of the distribution. Note that Weibull parameters are used often in the HIV model, so it will be useful to to understand the factors governing their shape.

Contents

General information
Relationship networks
HIV-specific biology
Transmission
Health care

General information ¶

The README files located in each scenario folder will contain instructions for running simulations to test the different aspects of the model described below. This section is intended to provide useful information for running any simulation (including custom configurations). Note that for each scenario, campaign and configuration files are located in the scenario folder. Demographics files (which are listed under “Demographics_Filenames” in the config.json) are all located in the demographics folder.

Reports ¶

The HIV model includes a variety of different output reports created as .csv files. To create particular reports, enable the parameter by setting the value to 1 for the desired report. Note that some reports, such as the ReportHIVInfection.csv, will report information about each individual at each time step; it is not recommended to enable these types of reports when populations are large, as output files will become very large and the simulation will run very slowly. For a complete list of all available output reports, see the “Output settings” section of Configuration parameters.

Overlay files ¶

An alternative to changing parameter values or adding parameters to base files is to create what is called an “overlay file.” These files contain parameter settings or additional parameters that will overwrite the settings configured in the base configuration and demographic files. When using an overlay for configuration parameters, include the files in the working directory. For demographic overlay files, all files to be used must be listed in the array for Demographics_Filenames. The order of these files is important: the base file must be listed first, and the overlay listed second. When there is more than one overlay file, the order of the overlays determines what information will be overridden; the last file in order will overlay all files preceding it. Overlay files can make it simple to swap out different parameter values without having to modify the base files, so you can experiment with different settings. Demographic overlays make it simple to increase the complexity of the population structure without having to create complex files.

Manipulating population size ¶

It is often useful to re-use the same demographics files for running different simulations. Depending on the dynamics of the simulation, or the output reports that are desired, it may be important to change the size of the population. An alternative to modifying the demographics file is to use the configuration parameter, Base_Population_Scale_Factor. This parameter lets you adjust the population set by the demographics parameter, InitialPopulation.

Weibull distributions ¶

Many of the HIV parameters use a Weibull distribution. To explore the impact that the scale and heterogeneity parameters have on the shape of the distribution, there is an Excel spreadsheet called “Weibull.xlsx” included in the scenarios folder.

Creating campaigns ¶

Much of the power and flexibility of EMOD comes from the customizable campaign interventions. For more information on creating campaigns, see Creating campaigns. Briefly, campaigns are created through the hierarchical organization of parameter groups, which includes:

Campaign events: the “when” and “where” the intervention is distributed. Calendar years can be specified, such that an intervention is distributed in the year 1985, or if 1985.5 is specified, halfway through the year 1985.
Event coordinators: “who” receives the intervention; the “who” is determined by filtering on age, gender, or on the IndividualProperties configured in the demographics files, such as HIV risk group or sociodemographic category. For example, it is possible, by setting Target_Demographic to ExplicitAgeRangesAndGender to apply an intervention to 75% of males between the ages of 15 and 25; further, the intervention can also be restricted to those that are accessible, i.e. those with an IndividualProperty of “Accessibility: Yes”.
Interventions: “what” will actually be distributed; it is also possible (but not required) to configure “why” a particular intervention is distributed by adding trigger conditions to the intervention. For example, interventions can be triggered by notifications broadcast by an individual upon some life event, such as Births (the individual’s own birth), GaveBirth, NewInfectionEvent, TwelveWeeksPregnant, STIDebut, HIVSymptomatic, and EveryUpdate. It is also possible to have one intervention trigger another intervention by asking the first intervention to broadcast a unique string, and having the second intervention be triggered upon receipt of that string.

All campaign events and event coordinators can be found in Events and event coordinators; node-level interventions can be found in Node-level interventions; and individual-level interventions can be found in Individual-level interventions.

Relationship networks ¶

To use a contact network as the basis for disease transmission, the Simulation_Type should be set to STI_SIM. This simulation type does not include any HIV-specific biology, which will be included in later tutorials.

In the EMODScenarios > Scenarios > HIV > Relationship_networks folder, you will find sets of files to run simulations modeling contact networks. These simulations do not include disease outbreaks or subsequent transmission, but will demonstrate how to configure relationship networks beginning with eligibility for pair formation, preference for particular partner ages, relationship types and durations, concurrency in relationships, and coital frequency and dilution.

HIV-specific biology ¶

HIV parameters are added to the STI relationship networks when the Simulation_Type is set to HIV_SIM. Specifically, this adds transmission rates, mortality rates, and the evolution of biomarkers such as CD4 count specific to HIV-infected individuals. These factors impact the survival of HIV+ individuals according to their age, disease state, co-infection status, and use of antiretroviral therapy (ART) or other interventions.

In the EMODScenarios > Scenarios > HIV > HIVBiology folder you will find files to run an HIV simulation. In the README file, you will find instructions on how to configure baseline HIV transmission, how to change survival time for children and adults, how CD4 count and WHO stage progress, and how to configure heterogeneity in CD4 count.

Transmission ¶

HIV can be transmitted via two routes: sexually through a relationship network, or vertically by mother-to-child transmission. In EMOD, to initially seed a population with disease, you must use the campaign interventions Outbreak or OutbreakIndividual (see Outbreak or OutbreakIndividual for more information). These two campaign intervention classes work by “distributing” HIV to the configured population. After the initial seeding, transmission can occur via the sexual or vertical routes.

In the EMODScenarios > Scenarios > HIV > Transmission folder you will find files to run an HIV simulation. In the README file, you will find instructions on how to configure sexual transmission, vertical transmission, and how to initiate co-infections.

For detailed configuration instructions and example exercises to try, see the README in the Transmission folder.

Health care ¶

Health care is critical for individuals with HIV. In EMOD, a system of health care can be created by using multiple interventions. Interventions can be linked to create a network of actions and results, where the outcome of one intervention can initiate the start of the next. This creates a cascade of care, where individuals enter the system due to a positive diagnostic test, and then move through the healthcare system created, with options for follow-up tests, and treatment options. Some individuals will exit the care system (e.g. “lost to follow up”), and in some cases, individuals that exit the care system may re-initiate care and return.

In the EMODScenarios > Scenarios > HIV > Health_care folder, you will find files to run simulations with a configured cascade of care. In the README file, you will be provided with instructions for working with cascades of care.

Care systems can range from simple diagnostics to a series of complex interventions, and the files within this section highlight these important aspects. Several interventions involved with care are highlighted, namely:

Voluntary male medical circumcision (VMMC)
Prevention of mother-to-child transmission (PMTCT)
Antiretroviral treatment (ART)
Steps in the care process, such as testing, staging, linking to care, treatment eligibility, and how to prevent individuals from entering care cascades multiple times.