H-DEF User Guide
Table of Contents
Overview 3
Running CEPAC 3
Run setup 3
Run organization 3
Naming conventions 4
Loading CEPAC output into H-DEF 5
Specifying H-DEF inputs 6
Transmission rates 6
Transmissions / 100 person-years by viral load stratum 7
Acute infection settings 7
Transmission rate multiplier while failed on ART 7
Transmission rate adjustments to individual runs 7
Demography 9
Year at model start 9
Calculate vs. specify susceptible entrants 9
Baseline population distribution 9
Economic parameters 10
HIV test costs 10
Background costs 10
Other parameters 11
Saving/importing H-DEF inputs 11
Running H-DEF and saving model outputs 11
Strategy-sets 11
Understanding H-DEF results 12
Epidemic trends 12
Formulating an S-I model 12
Where is equilibrium? 14
Prevalence, incidence, and duration 16
The baseline state of the population 17
Transmission rates 19
Infections, incidence, and incidence-to-prevalence-ratio 20
Heterogeneous mixing 22
Long-term treatment outcomes within H-DEF 23
CEPAC equilibrium 23
Calibration 24
Appendices 25
CEPAC equilibrium “proof” 25
Overview
The H-DEF model (HIV Dynamic Epidemic Framework) is a deterministic model of HIV transmission that interfaces with output from the CEPAC disease progression model. Using the H-DEF model involves four basic steps:
1. Running CEPAC – a given CEPAC run cannot necessarily be incorporated into H-DEF; runs must be specially tailored to work with H-DEF.
2. Loading CEPAC output into H-DEF.
3. Specifying H-DEF inputs.
4. Running H-DEF and saving model outputs.
Running CEPAC
There are few special considerations when setting up CEPAC runs for use in H-DEF. Broadly, these can be grouped into run setup, run organization, and naming conventions.
Run setup
CEPAC runs for use in H-DEF should always be undiscounted; any discounting of costs and QALMs will be performed within H-DEF. If you attempt to load discounted output into H-DEF it will produce an error message.
Run organization
In a standard CEPAC analysis, each run of the CEPAC model represents a single strategy (treatment policy). Thus, an analysis is often organized as shown in the schematic below; a unique folder is used for each scenario (e.g. basecase or a specific sensitivity analysis), within which are the runs representing each of the strategies being evaluated.
When setting up CEPAC runs for use in H-DEF, this picture becomes somewhat more complicated. In H-DEF, it generally requires more than one run to simulate a single treatment strategy – this is because it is necessary to simulate HIV-infected individuals who may occupy a variety of different states at the start of the H-DEF analysis. For example, as shown in the diagram below, individuals could be acutely-infected, chronically-infected but undiagnosed, on 1st-line ART, on 2nd-line ART, etc. Separate CEPAC runs are used to model individuals starting in each of these various baseline states – the same treatment policy will be applied in each run.
To keep track of these runs and strategies, an additional layer of folders must be introduced to sort the CEPAC runs used for an H-DEF analysis. As shown above, rather than using a single run to represent a strategy, now a folder of runs is used to represent a strategy.
Naming conventions
It’s possible to load large numbers of scenarios, folders, and CEPAC runs into H-DEF simultaneously. To keep them all organized within H-DEF, it’s important to adhere to certain naming conventions.
The various CEPAC runs within a folder should be given names beginning with a two-digit number, followed by an underscore and a short description of what baseline state that run is intended to simulate. Following this, the user is free to add in an indication of what round of runs it is, or any other information they’d like to have in the file name. For the runs in the figure above, these names could be:
01_chronicUndet_R1.in
02_acute_R1.in
03_1stLine_R1.in
04_2ndLine_R1.in
It is crucial that these names and numbers be used consistently within every folder for every scenario simulated in an analysis; for example, in the analysis above, a run whose name begins with “03” should always be a run in which patients start on 1st-line ART. These numbers are H-DEF’s only way to tell apart these runs, and to know which runs it should treat like 1st-line ART runs, and which to treat like acutely-infected runs.
If so desired, the user can append information about the strategy or the sensitivity analysis at the end of CEPAC run names. As a general rule, though, this may not be worth the effort. The names of the folders containing any run will always indicate which strategy and which sensitivity analysis it is simulating, and the full directory name (containing this information) will always be given in H-DEF output.
Finally, it’s important to also be systematic when naming the strategy folders. As with runs, these should be distinguished from one another using a two-digit number, followed by an underscore and a description of the strategy. In the example analysis, the strategy folders could be named:
01_SOC
02_Enhanced treatment
The standard of care folder (that is, whichever strategy best represents the current state of treatment in the modeled setting) should ALWAYS be given the number 01; the reason for this is described in the section on running the H-DEF model. Other folders can be numbered however the user sees fit. You don’t strictly have to be consistent with this numbering, but… why would you do that to yourself? Be consistent!
Loading CEPAC output into H-DEF
After you’ve done your CEPAC runs and saved the output somewhere, you need to get that output into H-DEF. To do this, first open up the H-DEF model and hit the button labeled “Edit CEPAC output identification”. A sub-menu will appear, which you can use to locate the output from your CEPAC runs, process those runs, and give names to the individual runs within each folder.
First, you will need to specify what CEPAC model version you used, using the drop-down menu labeled “CEPAC model version”. This is important because different model versions have different formats for their .out files. H-DEF needs to know what format it’s working with, so it knows where to look for the particular output it uses.
Next, you need to tell H-DEF where your CEPAC output is located on your hard drive/shared drive. To do this, press the “Select CEPAC output location” button and select the folder containing all of the runs that you would like to process. For example, let’s say that in the example above we wanted to process both s1 scenarios and the base case. To do this, you would select the folder containing all of these scenarios (it’d probably be called “R1” or “Runs” or something…). Next, in the input labeled “Runs per folder”, specify how many CEPAC runs are in each strategy folder; in the example analysis, this would be 4.
At this point, you can press the button labeled “Find CEPAC output”. H-DEF will search through all of the subdirectories of the folder you specified, and display the names of the run-containing folders (i.e. the lowest folders) and output files in the grid at the bottom. If any folders do not contain the expected number of output files, H-DEF will produce an error message.
Now is a good time to check that your output file names are consistent. The names will be sorted alphabetically, so the run starting with “01” should always come first, followed by “02”, etc. Do all of the “01” runs have the same name (e.g. 01_chronicUndet_R1.in)? Do all of the “02”, “03”, etc. runs have the same name? If not, something has gone wrong, and you should look into your CEPAC runs to figure out what happened. If all the runs do have the same names, well done!
Now that you’ve located the output for H-DEF, it needs to be processed – that is, H-DEF needs to extract all of the relevant numbers from each CEPAC output file. Just to give a sense of what this means, H-DEF will need to extract around 50,000 data points from each individual output file – so it can take a while. Before you start the extraction process, the model will give you an estimate of just how long it’s going to take.
Depending on the state of your CEPAC output files, there are now three options that may be presented to you:
1. If all of the folders have the correct number of runs, and the model doesn’t find any pre-existing extracted data, then you will see the message “NO DATA EXTRACTION FILE FOUND; SELECT “PROCESS .OUT FILES” TO EXTRACT DATA”. If you hit the button, the model will begin processing all of the .out files; when it’s done, the name of the file where it has stored the data will be displayed.
2. Alternately, it’s possible that a data extraction file already exists in the main folder you have selected. If this extraction file matches the sub-folders and runs in your folder, then you will be given two options. First you can reprocess the .out files, which will overwrite the existing data extraction file. Alternately, you can just use the extraction file that is already in the folder, which will save you the time of having to redo the extraction.
3. Finally, it’s possible that a data extraction file exists, but it doesn’t match the sub-folders and runs in your folder. There’s no great reason why this should happen, but clearly something got messed up! You can press the “Reprocess .out files” button to overwrite this old extraction file – it’s recommended that you first take a look through your folders to try to understand what happened here.
While extracting the data from your output files, H-DEF will test to ensure that your runs were undiscounted. To do this, it will compare two values: 1) the reported mean life-months, and 2) the mean life-months calculated by summing the monthly survival output. If these are not identical, it indicates that a nonzero discount rate was used, and the H-DEF will produce an error message.
Finally, this menu gives you the option to provide more meaningful names for the runs within in each folder. That is, if you’d like something more understandable than “01_chronicUndet_R1.in”, you can choose to label run 01 as “Chronically-infected, undetected”.
Specifying H-DEF inputs
H-DEF inputs are specified through a variety of sub-menus. The model’s main page will display a selection of these inputs in various categories, along with a message indicating whether any errors have been found in the inputs for each particular category. To edit the inputs in any category, simply click the button labeled “Edit (category)”.
Transmission rates
The Transmission rates menu is where users specify inputs related to how frequently people with HIV transmit the virus to others.
Transmissions / 100 person-years by viral load stratum
At the top, the user can specify transmission rates (expressed in transmissions/100 person-years with HIV) for the seven viral load strata in CEPAC. Before being actually used in H-DEF, these numbers will be multiplied by a calibration term that may increase or decrease all of them by some factor. Thus, their absolute values are less important than their relative values.
Acute infection settings
Next, the user can specify the characteristics of acute infection. These inputs are intended to capture the fact that, for a short period after the time of infection, HIV-infected individuals will have an extremely high viral load and tend to be very infectious. The user can specify two factors related to this acute period: first, how long it lasts, in months; and second, the multiplier applied to transmission rates during this time. For example, if a user specifies a duration of 2 and multiplier of 10, then the transmission rates applied to patients in a given run will be 10-fold higher during the first two months of that run. Note that this multiplier does not apply to individuals in the HVL vLo bucket, as they only to enter this bucket is to achieve suppression on ART.
Transmission rate multiplier while failed on ART
On the right side, the user can specify a transmission rate multiplier for individuals who have failed ART, but continue taking the drugs. This is intended to capture the fact that patients who remain on ART after failure tend to maintain some degree of partial suppression; that is, while they no longer have an undetectable viral load, they often do not rebound all the way to their set point viral load. Since CEPAC does not model this behavior, we use a failed ART transmission rate multiplier below 1 to capture its effects on infectivity within H-DEF.
Transmission rate adjustments to individual runs
Finally, at the bottom, the user has the option to apply particular adjustments specifically to individual runs. First, there are two inputs related to acute infection. For each run, the user can select yes/no for whether to apply the acute infection transmission rate multiplier during the first few months of that run. The decision of whether to use acute infection will depend on what state patients are in during the first few months of that run. Is the run intended to simulate patients starting at the time of infection? If so, use the multiplier. If the run is intended to start at some other state (e.g. on 2nd-line ART, chronically-infected but undiagnosed) then don’t use the multiplier.
Next, the user can specify whether to treat patients as in the “baseline acute” state at the start of an H-DEF projection. The meaning of this term is a bit subtle, but hopefully the following diagram will clear things up! Consider a scenario in which the acute infection phase lasts for three months. In the following diagram, the month of HIV infection is denoted with an X and the acute phase with a blue arrow; the three groups of patients who are in the acute phase at H-DEF model start are denoted with dark blue arrows: