For details on steps to start, see the Quick start guide.
This is an evolving document; more details are to be added. For specific questions, please see the .R function descriptions here, the parameter table here, or email the authors.
Users may interact with EvoNetHIV in one of four principal ways to conduct their own experiments: a) they may keep the model structure exactly as is, but vary some of the input parameters; b) they may use some of the alternative functional forms included with the model through the use of flag arguments; c) they may keep the model structure as is, but vary the network model and associated parameters through the use of ergm terms; d) they may change the structure of the model through the writing of substitute modules. Each of these features requires understanding the current model, and being familiar with the default parameter values; these are described below.
Option c requires familiarity with the mathematics and terminology of exponential random graph models, and option d requires familiarity with the EpiModel API; an introduction to each of these can be found here: http://statnet.github.io/nme/
Advanced users have the option of creating new functions or variants of existing functions (described in more detail below). e.g. Someone wanting to specify that “versatile” men are more likely to use condoms, for example, could write a variant of our condom usage function that does this.
In this section we describe the assumptions and actions of the default modules.
Network structure and dynamics.
User-defined network parameters can be implemented (e.g., mean degree, age and other subgroup structure) based on the statnet and EpiModel packages. The default structure is random mixing of agents with a network mean degree of 0.7. Each agent can exist as an isolate (no partners) or have one or more sexual partners per timestep. The default mean partnership duration is 100 days.
Sex.
Sexual acts (coital acts) are determined among agents in a serodiscordant relationship at each daily time step. Among these partnerships, the number of sexual acts per partnership per daily time step is assigned according to a Poisson draw (mean = 0.43). Probability of sex can also be a declining function of age. Default condom use is determined for each sexual act with probability of 50% and default circumcision status is assigned to agents at model entry with 85% probability. When the infected partner is 47% past their expected time in AIDS, no sex occurs. For MSM models, agents are assigned one of three sexual roles: versatile, insertive, and receptive. Insertive agents only have sex with receptive agents and vice-versa. Versatile agents can have sex with any other agents. Intra-event versatility (when men switch roles and each engage in insertive and receptive anal intercourse (AI) during the same sexual contact) occurs with 40% probability when both partners are role versatile.
CD4 counts for individuals are recorded as ordinal variables with four categories; categories 1, 2, 3, and 4 represent CD4>500, 500>CD4>350, 350>CD4>200, 200>CD4>0, respectively. Category 4 also represents the AIDS stage.
At infection, an individual is probabilistically assigned an initial CD4 category (1, 2, or 3) where higher SPVL values increases the probability of assignment to categories 2 or 3. (Table 1). For each daily timestep, an infected agent in categories 1, 2, or 3 can move to the following CD4 category (representing lower CD4 counts) or remain in the current category based on the outcome of a Bernoulli trial with the probability of success (moving to the next category) equal to the inverse of the mean passage time (in days) for a given SPVL and CD4 category (Table 2). Duration in CD4 category 4 is fixed for each SPVL category; at the end of time in category 4, an individuals is categorized as having died of AIDS.
With commencement of ART, an individuals’s CD4 category is set to 1 and remains there until treatment stops or death. If treatment stops before death, the CD4 category is set equal to the value at the start of treatment.
HIV per-act transmission probabilities are calculated as a function of relevant risk factors according to characteristics of the sexual act and characteristics of the agents engaged in the sexual act. Following Hughes et al (2012), the probability of transmission is calculated for each sexual act that occurs in a serodiscordant relationship, as:
\[P(transmission)=1-(1-λ)^{eXβ}\] where λ is the baseline per-act infectivity (0.000247).
We have different transmission probabilities for heterosexual and MSM partners. For heterosexual partners,
\[Xβ=ln(2.89*(VL-4.0)+ln(RR_{circumcised})*circumcised+ln(RR_{condom})*condom+ln(RR_{age})*age_{base}+ln(RR_{STI})*STI.status.sus\] where circumcised is an indicator variable for the circumcision status of the male, STI (sexually transmitted infection) is an indicator variable for any STI, condom is an indicator variable for condom use for the male, VL is the log10 viral load of infected agent, and age_base is the number of decades over 35 the susceptible agent is: (age-35)/10; and RR_x is the risk factor.
For MSM partners,
\[Xβ=ln(RR_VL )*(VL-4.0)+ln(RR_{insertive})*insertive+ln(RR_{receptive})*receptive+ln(RR_{circumcised}))*circumcised+ln(RR_{condom})*condom+ln(RR_{sti})*sti.status.sus\] where insertive and receptive are indicator variables for role of susceptible agent and other variables are as for heterosexual partners.
Once the probability of transmission is calculated, a random uniform draw determines whether infection occurred.
The model allows users to specific an initial age distribution. The model accounts for births, natural mortality, death due to AIDS, and the potential for agents to age out of the sexually active population. Each agent ages 1/365 of a year each day. Depending on parameter choices, variety of age distributions, including (approximately) stable age distributions, can be achieved.