4. Simulation details¶
4.1. General flow of a simulation¶
As one might expect, a population consists of persons which can either be male or female. Persons can be introduced into the simulation in two ways:
- During the initialization of the simulation, in which case persons with certain ages (drawn from a distribution) are added to the simulation.
- When the simulation is running, and the birth of a new person occurs.
Once born, a person will become sexually active when a debut event is triggered. If the person is introduced into the population at the start of the simulation, and the age exceeds the debut age, this event is no longer scheduled. Every person always has a ‘normal’ mortality event scheduled, which corresponds to a cause of death other than AIDS.
To get the HIV epidemic started, an HIV seeding event can be scheduled. When this event is triggered, a number of people in the existing population will be marked as being HIV-infected. An infected person will go through a number of infection stages. Until a chronic stage event is triggered the person is in the acute HIV infection stage; afterwards he will be in the chronic stage. A specific amount of time before dying of AIDS, an AIDS stage event is triggered, marking the transition of the chronic HIV stage to the actual AIDS stage. Even closer to the AIDS related death, another AIDS stage event is triggered, after which the person is in the ‘final AIDS stage’, and will be too ill to e.g. form sexual relationships. When the person dies of AIDS, the AIDS mortality event is fired. Note that it is always possible that the person dies from other causes; in that case the ‘normal’ mortality event will get triggered sooner.
If two persons of opposite gender are sexually active, a relationship can be formed. If this is the case, a formation event will be triggered. When a relationship between two people exists, it is possible that conception takes place, in which case a conception event will be triggered. If this happens, a while later a birth event will be fired, and a new person will be introduced into the population. In case one of the partners in the relationship is HIV infected, transmission of the virus may occur. If so, a transmission event will fire, and the newly infected person will go through the different infection stages as described earlier. Of course, it is also possible that the relationship will cease to exist, in which case a dissolution event will be fired. Note that in the version at the time of writing, there is no mother-to-child-transmission (MTCT).
Starting treatment and dropping out of treatment is managed by another sequence of events. When a person gets infected, either by HIV seeding or by transmission, first a diagnosis event is scheduled. If this is triggered, the person is considered to feel bad enough to go to a doctor and get diagnosed as being infected with HIV. If this happens, an HIV monitoring event is scheduled to monitor the progression of the HIV infection. If the person is both eligible and willing to receive antiretroviral therapy, treatment is started; if not, a new monitoring event will be scheduled. In case treatment is started, no more monitoring events will be scheduled, but the person will have a chance to drop out of treatment, in which case a dropout event is triggered. When a person drops out of treatment, a new diagnosis event will be scheduled. The rationale is that when a person drops out, he may do so because he’s feeling better thanks to the treatment. After dropping out, the condition will worsen again, causing him to go to a doctor, get re-diagnosed and start treatment again.
4.2. Initialization of the simulation¶
During the initialization of the simulated population, the following steps will take place:
Create the initial population:
- A number of men (
population.nummen) and women (population.numwomen) are added to the population, of which the age is drawn from an age distribution file (population.agedistfile). Depending on the debut age, people may be marked as being ‘sexually active’.- The initial population size will be remembered for use in e.g. the formation hazard. During the simulation, this size can be synchronized using another event.
Schedule the initial events:
- For each person, a ‘normal’ mortality event will be scheduled, and if needed, a debut event will be scheduled.
- Get the HIV epidemic started at some point, by scheduling an HIV seeding event.
- If specified, schedule the next simulation intervention. This is a general way of changing simulation settings during the simulation.
- Schedule a periodic logging event if requested. This will log some statistics about the simulation at regular intervals.
- In case the population size is expected to vary much, one can request an event to synchronize the remembered population size for use in other events.
- For pairs of sexually active persons, depending on the ‘eyecap’ settings (
population.eyecap.fraction), schedule formation events
Once the simulation is started, it will run either until the number of years specified in
population.simtime have passed, or until the number of events specified in
population.maxevents have been executed.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
population.nummen(100):
The initial number of men when starting the simulation.
population.numwomen(100):
The initial number of women when starting the simulation.
population.simtime(15):
The maximum time that will be simulated, specified in years.
population.maxevents(-1):
If greater than zero, the simulation will stop when this number of events has been executed. This is not used if negative.
population.agedistfile( “sa_2003.csv” in the Simpact Cyan data directory):
This is a CSV file with three columns, named ‘Age’, ‘Percent Male’ and ‘Percent Female’. The values of the age are specified in years and should be increasing; the specified percentages are deemed valid until the next age. The default is the age distribution in South Africa from 2003.Note that when using the R or Python method to start simulations, you need to specify the age distribution as a parameter to the
runfunction, if you want to use any other distribution than the default. See the R section or Python section for more information.
4.3. Per person options¶
As explained before, a population is central to the Simpact Cyan simulation and such a population consists of persons, each of which can be a man or a woman. During the simulation, these persons have many properties: gender, age, the number of relationships, which partners, etc. Several properties of persons can be defined using configuration options, which are discussed in this section.
4.3.4. Various other settings¶
Here, we’ll discuss a few per-person settings which do not fall into the categories
above. The first one is called person.art.accept.threshold.dist.type and is related
to how willing a person is to start treatment when offered. When a person is introduced
into the population, a number is picked from the specified distribution. This number
is fixed for this person, and will no longer change during the simulation. Then, when
the person is offered treatment, a new random number between 0 and 1 is chosen uniformly.
If this number is below the threshold value that was determined earlier, treatment
will be accepted, otherwise it is rejected. By default, the person.art.accept.threshold.dist.type
setting always sets the threshold at 0.5, causing each person to have a 50% chance of
accepting treatment when offered.
When a person is added to the population, a location is chosen for this person from
the two dimensional distribution that is specified in person.geo.dist2d.type.
In the default Simpact Cyan simulation, this location is not yet used in any hazard,
and the default location is put to (0, 0) for everyone. Because the location is written
to the person log file, it can be (ab)used to test two dimensional
distributions, like we did in the example for the discrete two dimensional distribution.
By default, the survival time for a person after becoming HIV infected, is given by a simple relation based on the set-point viral load. Because an exact mapping from viral load to survival time is not that realistic, you can add some randomness to this relation using the distribution in person.survtime.logoffset.dist.type. When a person becomes infected, a random number is drawn from this distribution and will correspond to an offset in the survival time, as explained in the AIDS mortality event. The following IPython notebook illustrates the effect: survivaltimernd.ipynb.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
person.art.accept.threshold.dist.type(‘fixed’ with value 0.5):
This specifies the one dimensional distribution that is used to choose the ART acceptance threshold for each person, as explained earlier.person.geo.dist2d.type(‘fixed’ with value (0, 0)):
This two dimensional distribution is used to assign a geographic location to each person. In the main Simpact Cyan simulation, this is currently not used in any hazard.person.survtime.logoffset.dist.type(‘fixed’ with value 0): This one dimensional distribution can be used to add some randomness to the survival time until dying of AIDS related causes after becoming HIV infected.
4.4. Events¶
The simulation advances by figuring out which event should take place next, followed by executing code for that event. At the start, many initial events are typically scheduled, some set up to fire at a specific simulation time, some based on a hazard which may change during the simulation. During the simulation, new events will get scheduled, and some already scheduled events will be discarded (for example, in case someone dies, no other events involving this person will need to get executed anymore).
Below you can find an overview of the events that are currently used in the simulation. The relevant configuration options are mentioned as well.
4.4.1. AIDS mortality event¶
When a person gets infected with HIV, an HIV-based time of death is determined. This time of death is determined as the time of infection plus the survival time, which is given by the following formula (based on [Arnaout et al.]):
In this formula, \(C\) and \(k\) are parameters which can be configured using the settings
mortality.aids.survtime.C and mortality.aids.survtime.k respectively. The \(x\) parameter
is determined per person allowing some randomness in the formula: it
determines an offset on a logarithmic scale. By default, this value is zero however,
causing a very strict relationship between \(V_{\rm sp}\) and \(t_{\rm survival}\). The value of
\(V_{\rm sp}\) is the set-point viral load, first determined at the time of infection
and in general
different per person. The value of the set-point viral load can change when treatment is involved: when a
person is receiving treatment, the viral load will go down, causing him to live longer.
When a person drops out of treatment, the viral load goes up again and the expected
lifespan shrinks.
To illustrate how this is taken into account, consider a person that has an initial viral load that causes a survival time of 10 years. Suppose that after 1 year, treatment is started and that using the formula above the survival time would become 50 years. When treatment got started, 10% of the survival time had already passed and we take this into account. So after starting treatment, the AIDS related mortality would be scheduled after 45 years. If the person drops out of treatment 10 years later, 20% of the remaining survival time has passed, which translates to 2 years in terms of the original viral load. This means that still 7 years will remain until the AIDS based mortality event is fired. Note that using this approach, one will never encounter the situation where the time of death has already passed when increasing the viral load.
You can find an IPython notebook that illustrates this example here: aidsmortalityexample.ipynb
An AIDS based mortality event will be scheduled to fire at the specified time, which may still change as explained above. When it fires, the person is considered to have died from AIDS. Note that this does not influence the ‘normal’ mortality event, which can still get triggered sooner to allow for another cause of death.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
mortality.aids.survtime.C(1325.0):
The value of \(C\) in the formula for \(t_{\rm survival}\).mortality.aids.survtime.k(-0.49):
The value of \(k\) in the formula for \(t_{\rm survival}\).
4.4.2. AIDS stage event¶
When a person gets infected with HIV, he will first be in the acute phase of infection, then in the chronic stage, and after a while in the AIDS stage. The AIDS stage is actually split in two separate phases: an AIDS stage, and a final AIDS stage. In this last period, the person is deemed to be too ill to e.g. form sexual relationships.
The first AIDS stage gets scheduled when the chronic stage event fires,
and is scheduled to get triggered at a specific time (aidsstage.start) before the
AIDS related death takes place. When this event fires, another one
is scheduled to mark the transition to the final AIDS stage, also set to take place
a specific amount of time (aidsstage.final) before the AIDS based death. Because the
time of the AIDS related death can still change when treatment is involved, these fire times
can also still change.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
aidsstage.start(1.25):
The time before the AIDS related death a person will advance to the AIDS stage of infection. Defaults to 15 months.aidsstage.final(0.5):
The time before the AIDS related death a person will advance to the final AIDS stage of infection. Defaults to 6 months.
4.4.3. Birth event¶
After a conception event is triggered, a new birth event will be scheduled,
so that the woman in the relationship will give birth to a new person a specific time
(based on birth.pregnancyduration.dist.type) later. The gender is determined by the
birth.boygirlratio configuration setting.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
birth.boygirlratio(1.0/2.01):
The probability of the newly born person to be a man.birth.pregnancyduration.dist.type(defaults to ‘fixed’ with a value of 268/365):
With this parameter you can specify the distribution to be used when determining how long the pregnacy should be, before firing the birth event. By default, the fixed value of 268/365 is used, but other distributions and related parameters can be used as well.
4.4.4. Check stopping criterion event¶
This event allows you to terminate a simulation if a certain population size
(checkstop.max.popsize) or real-world elapsed time (checkstop.max.runtime)
is exceeded. To enable this, the checkstop.interval parameter must be
set to a positive value. If so, at regularly spaced times (simulation time)
this check will be performed.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
checkstop.interval(-1):
To enable this event, set the value to a positive value. If enabled, this event will fire at simulation times that are multiples of this interval, at which time checks on the population size and/or running time are performed.checkstop.max.runtime(inf):
When the event fires, the elapsed real-world time since the start of the simulation program will be compared to this value. If it exceeds it, the simulation will be aborted.checkstop.max.popsize(inf):
When the event fires, the population size will be compared to this value. If it exceeds it, the simulation will be aborted.
4.4.5. Chronic AIDS stage event¶
When a person becomes HIV infected, he starts out in the acute stage of the disease.
This ‘chronic stage’ event is then scheduled to mark the transition from the acute
stage to the chronic stage, which will
fire a specific amount of time (chronicstage.acutestagetime) later.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
chronicstage.acutestagetime(0.25):
This is the duration of the acute HIV stage, before transitioning to the chronic stage. The default is three months.
4.4.6. Conception event¶
When a formation event has fired (so a man and a woman are in a sexual relationship), a conception event will be scheduled unless the woman is already pregnant. This is a hazard-based event, and its hazard at time \(t\) is defined as:
which is a time-dependent hazard of type
By default, only the \(\alpha_{\rm base}\) value is used (conception.alpha_base), resulting in a constant
hazard, but other factors can be used as well: the age of the man and woman in the
relationship can be taken into account using conception.alpha_ageman and
conception.alpha_agewoman, the weekly sex frequency (WSF) using conception.alpha_wsf and the
‘age’ of the relationship using conception.beta (\(t_{\rm ref}\) is set to the time
the relationship started).
The value of \({\rm WSF}\) itself is currently chosen from the distribution specified
in conception.wsf.dist.type, at the time the event gets scheduled.
When a conception event fires, so when actual conception takes place, a birth event will be scheduled.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
conception.alpha_base(-3):
The value of \(\alpha_{\rm base}\) in the formula for the hazard.conception.alpha_ageman(0):
The value of \(\alpha_{\rm age,man}\) in the formula for the hazard, to be able to take the age of the man in the relationship into account.conception.alpha_agewoman(0):
The value of \(\alpha_{\rm age,woman}\) in the formula for the hazard, to be able to take the age of the woman in the relationship into account.conception.alpha_wsf(0):
The value of \(\alpha_{\rm wsf}\) in the formula to the hazard. This way you can take a value for the weekly sex frequency (WSF) into account.conception.beta(0):
The value of \(\beta\) in the hazard formula, allowing you to influence the hazard based on the ‘age’ of the relationship.conception.t_max(200):
As explained in the section about ‘time limited’ hazards, an exponential function needs some kind of threshold value (after which it stays constant) to be able to perform the necessary calculations. This configuration value is a measure of this threshold.conception.wsf.dist.type(‘fixed’, with value 0):
When the conception event is scheduled, a value for the weekly sex frequency (WSF) to use in the hazard formula is picked from a distribution. This configuration option specifies which distribution you would like to use, and depending on the value other parameters for the distribution can be configured as well.
4.4.7. Debut event¶
Persons who are not yet sexually active will have a debut event scheduled, which
will fire when a person has reached a specified age (debut.debutage). When
this event fires, the person becomes sexually active and relationship formation events
will get scheduled. The number of formation events that gets scheduled can
be controlled using the ‘eyecap’ setting.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
debut.debutage(15):
The age a person must have to become sexually active. This determines when the debut event for a particular person will get executed.
4.4.8. Diagnosis event¶
When a person gets infected with HIV, either by transmission of the virus or by seeding the population to get the epidemic started, a diagnosis event will get scheduled. When fired, the person is deemed to feel bad enough to go to a doctor and get diagnosed as being HIV-infected. Upon diagnosis, a monitoring event will be scheduled very shortly afterwards, to monitor the progression of the disease and to offer treatment if eligible.
This event is hazard-based, and the hazard is of the following form:
Note that this is again a time dependent exponential hazard of the form
In the formula, \(G\) is a value related to the gender of the person, 0 for a man and 1 for a woman. The number \(P\) represents the number of partners of the person that are both HIV infected and diagnosed. The value of \(D\) is an indication of whether the person was diagnosed previously: its value is 0 if this is the initial diagnosis event, or 1 if it’s a re-diagnosis (after dropping out of treatment).
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
diagnosis.baseline(0):
Controls the corresponding \({\rm baseline}\) value in the expression for the hazard.diagnosis.agefactor(0):
Controls the corresponding \({\rm agefactor}\) value in the expression for the hazard. This allows one to let the age of a person influence the hazard.diagnosis.genderfactor(0):
Controls the \({\rm genderfactor}\) parameter in the hazard. This allows you to have a different hazard depending on the gender of the person.diagnosis.diagpartnersfactor(0):
Corresponds to the value of \({\rm diagpartnersfactor}\) in the expression for the hazard. The idea is to allow the number of partners that have already been diagnosed to have an effect on a person’s diagnosis time: if a person is not feeling well and knows that some of the partners are infected with HIV, this can be an incentive to go to the doctor sooner.diagnosis.isdiagnosedfactor(0):
Using this \({\rm isdiagnosedfactor}\) value in the hazard, it is possible to have a different hazard if the person was diagnosed before. After dropping out of treatment, for example because a person is feeling better and no longer feels the need for treatment, a diagnosis event will be scheduled again. It is reasonable to think that a person may go to the doctor again sooner when he already knows about the HIV infection.diagnosis.beta(0):
Corresponds to the \({\beta}\) factor in the hazard expression, allowing one to take the time since infection into account.diagnosis.t_max(200):
As explained in the section about ‘time limited’ hazards, an exponential function needs some kind of threshold value (after which it stays constant) to be able to perform the necessary calculations. This configuration value is a measure of this threshold.
4.4.9. Dissolution event¶
As soon as a relationship is formed a dissolution event gets scheduled to allow for the possibility that the relationship terminates. The hazard for this event is the following:
Note that this is again a time dependent exponential hazard of the form
In this expression, \(P_{\rm man}\) and \(P_{\rm woman}\) are the number of partners the man and woman in the relationship have. The value \(D_{\rm pref}\) represents the preferred age difference between a man and a woman. The value of \(t_{\rm ref}\) is the time at which the relationship was formed.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
dissolution.alpha_0(0.1):
The value of \(\alpha_0\) in the expression for the hazard, allowing one to establish a baseline value.dissolution.alpha_1(0):
The value of \(\alpha_1\) in the hazard formula, corresponding to a weight for the number of relationships the man in the relationship has.dissolution.alpha_2(0):
The value of \(\alpha_2\) in the hazard formula, corresponding to a weight for the number of relationships the woman in the relationship has.dissolution.alpha_3(0):
The value of \(\alpha_3\) in the hazard expression, by which the influence of the difference in number of partners can be specified.dissolution.alpha_4(0):
The value of \(\alpha_4\) in the expression for the hazard, a weight for the average age of the partners.dissolution.alpha_5(0):
The factor \(\alpha_5\) controls the relative importance of how much the age gap between man and woman differs from the preferred age difference \(D_{\rm pref}\).dissolution.Dp(0):
This configures the preferred age difference \(D_{\rm pref}\) in the hazard expression. Note that to take this into account, \(\alpha_5\) should also be set to a non-zero value.dissolution.beta(0):
As can be seen in the expression for the hazard, using this value the ‘age’ of the relationship can be taken into account.dissolution.t_max(200):
As explained in the section about ‘time limited’ hazards, an exponential function needs some kind of threshold value (after which it stays constant) to be able to perform the necessary calculations. This configuration value is a measure of this threshold.
4.4.10. MSM Dissolution event¶
As soon as an MSM relationship is formed an MSM dissolution event gets scheduled to allow for the possibility that the relationship terminates. The hazard for this event is the following:
Note that this is again a time dependent exponential hazard of the form
In this expression, \(P_{\rm man1}\) and \(P_{\rm man2}\) are the number of partners the men in the relationship have. The value of \(t_{\rm ref}\) is the time at which the relationship was formed.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
dissolutionmsm.alpha_0(0.1):
The value of \(\alpha_0\) in the expression for the hazard, allowing one to establish a baseline value.dissolutionmsm.alpha_12(0):
The value of \(\alpha_{12}\) in the hazard formula, corresponding to a weight for the number of relationships the men in the relationship have.dissolutionmsm.alpha_3(0):
The value of \(\alpha_3\) in the hazard expression, by which the influence of the difference in number of partners can be specified.dissolutionmsm.alpha_4(0):
The value of \(\alpha_4\) in the expression for the hazard, a weight for the average age of the partners.dissolutionmsm.alpha_5(0):
The factor \(\alpha_5\) controls the relative importance of the age gap between the men in the relationship.dissolutionmsm.beta(0):
As can be seen in the expression for the hazard, using this value the ‘age’ of the relationship can be taken into account.dissolutionmsm.t_max(200):
As explained in the section about ‘time limited’ hazards, an exponential function needs some kind of threshold value (after which it stays constant) to be able to perform the necessary calculations. This configuration value is a measure of this threshold.
4.4.11. ART treatment dropout event¶
When a monitoring event gets triggered and the person is both eligible and willing to receive treatment, treatment is started causing the set-point viral load of the person to be lowered. When treatment starts, a dropout event is scheduled as well, to allow a person to drop out of treatment.
Currently, the dropout event is not hazard-based, instead a random number is
picked from a one dimensional probability distribution as specified in
dropout.interval.dist.type and related configuration options.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
dropout.interval.dist.type(‘uniform’ by default, with boundaries of 3 months and 10 years):
Using this configuration option you can specify the probability distribution to use when obtaining the time after which a person will drop out of treatment. By default, this is a uniform distribution with equal non-zero probability between 3 months and 10 years, and zero otherwise. Other distributions can be specified as well, as explained previously.
4.4.12. Formation event¶
Depending on the ‘eyecap’ setting, for a number of man/woman pairs, formation events will be scheduled. When such an event fires, a relationship between these two persons will be formed. Apart from scheduling a dissolution event, a conception event will get scheduled if the woman in the relationship is not yet pregnant, and in case just one of the partners is infected with HIV, a transmission event will be scheduled as well.
The formation event is hazard based, and there are currently three hazard types
that can be used by configuring formation.hazard.type. The first hazard type
is called the ‘simple’ hazard, and is nearly equal to the hazard of the
dissolution event.
The second hazard type, called ‘agegap’, is more advanced. Not only can the
preferred age gap differ from one person to the next, but there’s also an
age dependent component in this preferred age gap. The third hazard, ‘agegapry’
allows for the weight of the agegap terms to be age dependent. To make this possible,
the time dependency in the age gap part of the hazard is only approximate: times
will refer to a reference year (hence the ‘ry’ in the hazard name) which can be
set using the ‘synchronize reference year’ event.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
formation.hazard.type(agegap):
This parameter specifies which formation hazard will be used. Allowed values aresimple,agegapandagegapry.
4.4.12.1. The simple formation hazard¶
The hazard for the simple formation event is shown further on and is nearly identical
to the one of the dissolution event. Apart from a few extra terms
in the expression for the hazard, the most important difference
is the factor \(F\) in front.
This factor \(F\) is a normalization factor which takes the population size (or more accurately the size when viewed through the the ‘eyecaps’) into account. This is necessary because the number of formation events that get scheduled is proportional to the population size (for a fixed ‘eyecap’ fraction). So if no normalization factor would be used, a larger population would automatically mean that more relationships are formed. By roughly dividing the hazard by the population size, this increase in available possible relationships when the population size is larger, does not automatically result in more relationships anymore.
To be very accurate, each increase or decrease in the population size (by a birth or death of a person) should be taken into account, and to do so all formation event fire times would need to be recalculated according to the changed (because \(F\) changed) hazard. This would become a huge bottleneck, especially when the population size is large, and birth and mortality events occur frequently.
To work around this bottleneck, it is not the true population size that is used in this normalization factor, but the last known population size. This last known size can be updated by the event that synchronizes population statistics, at which time all formation event fire times will be recalculated. If the population size stays roughly constant, this is not necessary, but it will be if the population size grows or shrinks considerably during the simulation.
The hazard for this formation type is the following:
Note that this is again a time dependent exponential hazard of the form
In this expression, \(P_{\rm man}\) and \(P_{\rm woman}\) are the number of partners the man and woman in the relationship have. The value \(D_{\rm pref}\) represents the preferred age difference between a man and a woman, and \(E_{\rm man}\) and \(E_{\rm woman}\) are parameters that can be different for each person describing their eagerness of forming a relationship. The distance between the locations \(\vec{R}_{\rm man}\) and \(\vec{R}_{\rm woman}\) of the partners involved can be taken into account as well.
The value of \(t_{\rm ref}\) is the time at which the relationship between the two persons became possible. If no relationship existed between the two people earlier, this is the time at which the youngest person reached the debut age. On the other hand, if a relationship between these partners did exist before, it is the time at which that relationship got dissolved. The factor \(F\) is the normalization factor discussed earlier.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
formation.hazard.simple.alpha_0(0.1):
The value of \(\alpha_0\) in the expression for the hazard, allowing one to establish a baseline value.formation.hazard.simple.alpha_1(0):
The value of \(\alpha_1\) in the hazard formula, corresponding to a weight for the number of relationships the man in the relationship has.formation.hazard.simple.alpha_2(0):
The value of \(\alpha_2\) in the hazard formula, corresponding to a weight for the number of relationships the woman in the relationship has.formation.hazard.simple.alpha_3(0):
The value of \(\alpha_3\) in the hazard expression, by which the influence of the difference in number of partners can be specified.formation.hazard.simple.alpha_4(0):
The value of \(\alpha_4\) in the expression for the hazard, a weight for the average age of the partners.formation.hazard.simple.alpha_5(0):
The factor \(\alpha_5\) controls the relative importance of how much the age gap between man and woman differs from the preferred age difference \(D_{\rm pref}\).formation.hazard.simple.alpha_6(0):
Weight for the sum of the eagerness parameters of both partners.formation.hazard.simple.alpha_7(0):
Weight for the difference of the eagerness parameters of both partners.formation.hazard.simple.alpha_dist(0):
This configures the weight \(\alpha_{\rm dist}\) of the geographical distance between the partners.formation.hazard.simple.Dp(0):
This configures the preferred age difference \(D_{\rm pref}\) in the hazard expression. Note that to take this into account, \(\alpha_5\) should also be set to a non-zero value.formation.hazard.simple.beta(0):
Corresponds to \(\beta\) in the hazard expression and allows you to take the time since the relationship became possible into account.formation.hazard.simple.t_max(200):
As explained in the section about ‘time limited’ hazards, an exponential function needs some kind of threshold value (after which it stays constant) to be able to perform the necessary calculations. This configuration value is a measure of this threshold.
4.4.12.2. The agegap formation hazard¶
The agegap formation hazard is more complex than the previous hazard, providing
some additional functionality. With this hazard it’s possible to simulate the
previous simple hazard, but not the other way around. The general look of the
hazard is the same as before, but with some important differences:
In this equation the following notation is used for clarity:
i.e., \(A(t)\) represents the age of someone. As you can see from the expression, it is now possible to specify a preferred age difference on a per-person basis. This personal preferred age difference \(D_{p,{\rm man}}\) or \(D_{p,{\rm woman}}\) can be controlled by specifying a one dimensional probability distribution, as explained in the person settings. Apart from more variation in the age gap, the preferred age gap for a man or a woman can also vary in time, based on the age of one of the partners. The importance of such a change can be controlled using the \(\alpha_{\rm gap,agescale,man}\) and \(\alpha_{\rm gap,agescale,woman}\) parameters.
In front of the hazard, there is again a factor \(F\), just like with the simple
hazard. As explained there, it serves as a normalization factor
and for a population which can change much in size, an event that synchronizes population statistics
may be important to schedule regularly.
The values \(P_{\rm man}\) and \(P_{\rm woman}\) are the number of partners
the man and woman in the relationship have, and \(E_{\rm man}\) and
\(E_{\rm woman}\) are parameters that can be different for each person describing
their eagerness of forming a relationship.
The distance between
the locations \(\vec{R}_{\rm man}\) and \(\vec{R}_{\rm woman}\) of the partners
involved can be taken into account as well.
As with the simple hazard, the value of \(t_{\rm ref}\) is the time
at which the relationship between the two persons became possible. If no relationship
existed between the two people earlier, this is the time at which the youngest person
reached the debut age. On the other hand, if a relationship between
these partners did exist before, it is the time at which that relationship got
dissolved.
Calculating the mapping from internal time to real-world time for this hazard
can no longer be done using the exponential time dependent hazard we encountered
e.g. in the simple hazard. The reason is the time dependence that is now present
inside the terms with the absolute values. To see how the mapping is done in this
case, you can look at the calculations in this document:
age gap hazard calculations
The following IPython notebook provides some simple examples of this agegap
hazard: agegap_hazard_examples.ipynb.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
formation.hazard.agegap.baseline(0.1):
The value of \(\alpha_{\rm baseline}\) in the expression for the hazard, allowing one to establish a baseline value.formation.hazard.agegap.numrel_man(0):
The value of \(\alpha_{\rm numrel,man}\) in the hazard formula, corresponding to a weight for the number of relationships the man in the relationship has.formation.hazard.agegap.numrel_woman(0):
The value of \(\alpha_{\rm numrel,woman}\) in the hazard formula, corresponding to a weight for the number of relationships the woman in the relationship has.formation.hazard.agegap.numrel_diff(0):
The value of \(\alpha_{\rm numrel,diff}\) in the hazard expression, by which the influence of the difference in number of partners can be specified.formation.hazard.agegap.meanage(0):
The value of \(\alpha_{\rm meanage}\) in the expression for the hazard, a weight for the average age of the partners.formation.hazard.agegap.eagerness_sum(0):
Weight \(\alpha_{\rm eagerness,sum}\) for the sum of the eagerness parameters of both partners.formation.hazard.agegap.eagerness_diff(0):
Weight \(\alpha_{\rm eagerness,diff}\) for the difference of the eagerness parameters of both partners.formation.hazard.agegap.gap_factor_man(0):
With this setting you set \(\alpha_{\rm gap,factor,man}\), specifying the influence of the age gap from the man’s point of view.formation.hazard.agegap.gap_agescale_man(0):
This controls \(\alpha_{\rm gap,agescale,man}\), which allows you to vary the preferred age gap with the age of the man in the relationship.formation.hazard.agegap.gap_factor_woman(0):
With this setting you set \(\alpha_{\rm gap,factor,woman}\), specifying the influence of the age gap from the man’s point of view.formation.hazard.agegap.gap_agescale_woman(0):
This controls \(\alpha_{\rm gap,agescale,woman}\), which allows you to vary the preferred age gap with the age of the woman in the relationship.formation.hazard.agegap.distance(0):
This configures the weight \(\alpha_{\rm dist}\) of the geographical distance between the partners.formation.hazard.agegap.beta(0):
Corresponds to \(\beta\) in the hazard expression and allows you to take the time since the relationship became possible into account.formation.hazard.agegap.t_max(200):
Even though this hazard is no longer a simple time dependent exponential, it will still be necessary to provide some kind of cut-off, as explained in the section about ‘time limited’ hazards. This configuration value is a measure of this threshold.
4.4.12.3. The agegapry formation hazard¶
While the ‘agegap’ hazard already allows for a great deal of
flexibility, it is not possible to vary the importance of the age gap terms as
people get older. The following hazard is very similar to the agegap one,
but this does allow the importance of the age gap to change over time:
In this equation, the terms \(G_{\rm man}\) and \(G_{\rm woman}\) for the age gap between partners in a relationship is given by the following expressions:
where \(g_{\rm man}(t_{\rm ry})\) and \(g_{\rm woman}(t_{\rm ry})\) specify the preferred age gaps themselves, which can change over time:
In these equations again the following notation is used:
i.e., \(A(t)\) represents the age of someone.
Looking at these full age gap terms \(G_{\rm man}\) and \(G_{\rm woman}\), you can see
that they are similar to the ones from
the agegap hazard, but the prefactor is no longer a simple configurable constant.
By tuning several parameters, the importance of these age gap terms can now be made
age-dependent.
However, this age-dependence is in fact only approximate because \(t_{\rm ry}\) is used in these expressions instead of the simulation time \(t\): to reduce the complexity of the hazard and keep the performance up, inside the age gap terms, strict time depencency on \(t\) is replaced by approximate time dependency on a reference year \(t_{\rm ry}\). By only changing this reference time at certain intervals (see the reference year synchronization event), the time dependency of the hazard becomes much more straightforward. Note that certain terms still have a dependency on the simulation time \(t\), causing this hazard to be of the form \(\exp(A + Bt)\).
By setting \(\alpha_{\rm numrel,scale,man}\) or \(\alpha_{\rm numrel,scale,woman}\), using the same approximation the importance of the number of partners can be made dependent on the age gap. The meaning of the other quantities in the hazard is the same as in the ‘agegap’ hazard.
An IPython notebook that illustrates how a funnel-like distribution of the
formed relationships can be generated using this agegapry hazard, can be found
here: agegapry_hazard_funnel.ipynb.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
formation.hazard.agegapry.baseline(0.1):
The value of \(\alpha_{\rm baseline}\) in the expression for the hazard, allowing one to establish a baseline value.formation.hazard.agegapry.numrel_man(0):
The value of \(\alpha_{\rm numrel,man}\) in the hazard formula, corresponding to a weight for the number of relationships the man in the relationship has.formation.hazard.agegapry.numrel_scale_man(0):
The value of \(\alpha_{\rm numrel,scale,man}\) in the formula for the hazard.formation.hazard.agegapry.numrel_woman(0):
The value of \(\alpha_{\rm numrel,woman}\) in the hazard formula, corresponding to a weight for the number of relationships the woman in the relationship has.formation.hazard.agegapry.numrel_scale_woman(0):
The value of \(\alpha_{\rm numrel,scale,woman}\) in the formula for the hazard.formation.hazard.agegapry.numrel_diff(0):
The value of \(\alpha_{\rm numrel,diff}\) in the hazard expression, by which the influence of the difference in number of partners can be specified.formation.hazard.agegapry.meanage(0):
The value of \(\alpha_{\rm meanage}\) in the expression for the hazard, a weight for the average age of the partners.formation.hazard.agegapry.eagerness_sum(0):
Weight \(\alpha_{\rm eagerness,sum}\) for the sum of the eagerness parameters of both partners.formation.hazard.agegapry.eagerness_diff(0):
Weight \(\alpha_{\rm eagerness,diff}\) for the difference of the eagerness parameters of both partners.formation.hazard.agegapry.gap_factor_man_const(0):
The value of \(\alpha_{\rm gap,factor,man,const}\) in the age gap term \(G_{\rm man}(t_{\rm ry})\).formation.hazard.agegapry.gap_factor_man_exp(0):
The value of \(\alpha_{\rm gap,factor,man,exp}\) in the age gap term \(G_{\rm man}(t_{\rm ry})\).formation.hazard.agegapry.gap_factor_man_age(0):
The value of \(\alpha_{\rm gap,factor,man,age}\) in the age gap term \(G_{\rm man}(t_{\rm ry})\).formation.hazard.agegapry.gap_agescale_man(0):
This controls \(\alpha_{\rm gap,agescale,man}\), which allows you to vary the preferred age gap with the age of the man in the relationship.formation.hazard.agegapry.gap_factor_woman_const(0):
The value of \(\alpha_{\rm gap,factor,woman,const}\) in the age gap term \(G_{\rm woman}(t_{\rm ry})\).formation.hazard.agegapry.gap_factor_woman_age(0):
The value of \(\alpha_{\rm gap,factor,woman,age}\) in the age gap term \(G_{\rm woman}(t_{\rm ry})\).formation.hazard.agegapry.gap_factor_woman_exp(0):
The value of \(\alpha_{\rm gap,factor,woman,exp}\) in the age gap term \(G_{\rm woman}(t_{\rm ry})\).formation.hazard.agegapry.gap_agescale_woman(0):
This controls \(\alpha_{\rm gap,agescale,woman}\), which allows you to vary the preferred age gap with the age of the woman in the relationship.formation.hazard.agegapry.distance(0):
This configures the weight \(\alpha_{\rm dist}\) of the geographical distance between the partners.formation.hazard.agegapry.beta(0):
Corresponds to \(\beta\) in the hazard expression and allows you to take the time since the relationship became possible into account.formation.hazard.agegapry.t_max(200):
As explained in the section about ‘time limited’ hazards, an exponential function needs some kind of threshold value (after which it stays constant) to be able to perform the necessary calculations. This configuration value is a measure of this threshold.formation.hazard.agegapry.maxageref.diff(1):
As explained above, the age gap terms do not use the real time dependency \(t\), but refer to a reference time \(t_{\rm ry}\) that needs to be synchronized periodically using the synchronize reference year event. The program will abort if it detects that the last reference time synchronization was more than this amount of time ago, which by default is one year.
4.4.13. MSM Formation event¶
The MSM formation event is very similar to the heterosexual formation event. If MSM relationships are enabled in the simulation, depending on the ‘eyecap’ setting, MSM formation events will be scheduled for a number of man/man pairs. When such an event fires, a relationship between these two men will be formed. Apart from scheduling an MSM dissolution event, in case just one of the partners is infected with HIV, a transmission event will be scheduled as well.
Just like the heterosexual relationship formation event, this event is also hazard
based and uses the same hazard types, which can be configured using formationmsm.hazard.type:
there are the ‘simple’ hazard, the ‘agegap’ hazard
and the ‘agegapry’ hazard.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
formationmsm.hazard.type(agegap):
This parameter specifies which formation hazard will be used. Allowed values aresimple,agegapandagegapry.
4.4.13.1. The simple formation hazard (MSM version)¶
The hazard for the simple formation event is shown below and is nearly identical
to the one of the MSM dissolution event. Apart from a few extra terms
in the expression for the hazard, the most important difference
is the factor \(F\) in front, a normalization factor which has the same meaning as in
the corresponding hazard from the heterosexual relationship formation
event.
The hazard for this formation type is the following:
Note that this is again a time dependent exponential hazard of the form
In this expression, \(P_{\rm man1}\) and \(P_{\rm man2}\) are the number of partners of the men in the relationship, and \(E_{\rm man1}\) and \(E_{\rm man2}\) are parameters that can be different for each person describing their eagerness of forming a relationship. The distance between the locations \(\vec{R}_{\rm man1}\) and \(\vec{R}_{\rm man2}\) of the partners involved can be taken into account as well.
The value of \(t_{\rm ref}\) is the time at which the relationship between the two persons became possible. If no relationship existed between the two people earlier, this is the time at which the youngest person reached the debut age. On the other hand, if a relationship between these partners did exist before, it is the time at which that relationship got dissolved.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
formationmsm.hazard.simple.alpha_0(0.1):
The value of \(\alpha_0\) in the expression for the hazard, allowing one to establish a baseline value.formationmsm.hazard.simple.alpha_12(0):
The value of \(\alpha_{12}\) in the hazard formula, corresponding to a weight for the number of relationships the men in the relationship have.formationmsm.hazard.simple.alpha_3(0):
The value of \(\alpha_3\) in the hazard expression, by which the influence of the difference in number of partners can be specified.formationmsm.hazard.simple.alpha_4(0):
The value of \(\alpha_4\) in the expression for the hazard, a weight for the average age of the partners.formationmsm.hazard.simple.alpha_5(0):
The factor \(\alpha_5\) controls the relative importance of the age gap between the partners.formationmsm.hazard.simple.alpha_6(0):
Weight for the sum of the eagerness parameters of both partners.formationmsm.hazard.simple.alpha_7(0):
Weight for the difference of the eagerness parameters of both partners.formationmsm.hazard.simple.alpha_dist(0):
This configures the weight \(\alpha_{\rm dist}\) of the geographical distance between the partners.formationmsm.hazard.simple.beta(0):
Corresponds to \(\beta\) in the hazard expression and allows you to take the time since the relationship became possible into account.formationmsm.hazard.simple.t_max(200):
As explained in the section about ‘time limited’ hazards, an exponential function needs some kind of threshold value (after which it stays constant) to be able to perform the necessary calculations. This configuration value is a measure of this threshold.
4.4.13.2. The agegap formation hazard (MSM version)¶
The agegap formation hazard is again very similar to its heterosexual counterpart:
In this equation the following notation is used for clarity:
i.e., \(A(t)\) represents the age of someone. As you can see from the expression, it is now possible to specify a preferred age difference on a per-person basis. This personal preferred age difference \(D_{p,{\rm man1}}\) or \(D_{p,{\rm man2}}\) can be controlled by specifying a one dimensional probability distribution, as explained in the person settings. Note that the preferred age gaps are the MSM specific agegaps. Apart from more variation in these age gaps, the preferred age gap can also vary in time, based on the age of one of the partners. The importance of such a change can be controlled using the \(\alpha_{\rm gap,agescale}\) parameter.
In front of the hazard, there is again a factor \(F\), just like with the simple hazard. The values \(P_{\rm man1}\) and \(P_{\rm man2}\) are the number of partners the men in the relationship have, and \(E_{\rm man1}\) and \(E_{\rm man2}\) are parameters that can be different for each person describing their eagerness of forming a relationship. Note that the eagerness values used here are the MSM eagerness values. The distance between the locations \(\vec{R}_{\rm man1}\) and \(\vec{R}_{\rm man2}\) of the partners involved can be taken into account as well.
As with the simple hazard, the value of \(t_{\rm ref}\) is the time
at which the relationship between the two persons became possible. If no relationship
existed between the two people earlier, this is the time at which the youngest person
reached the debut age. On the other hand, if a relationship between
these partners did exist before, it is the time at which that relationship got
dissolved.
Calculating the mapping from internal time to real-world time for this hazard
can no longer be done using the exponential time dependent hazard we encountered
e.g. in the simple hazard. The reason is the time dependence that is now present
inside the terms with the absolute values. More information can be found in the
documentation for the heterosexual ‘agegap’ hazard
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
formationmsm.hazard.agegap.baseline(0.1):
The value of \(\alpha_{\rm baseline}\) in the expression for the hazard, allowing one to establish a baseline value.formationmsm.hazard.agegap.numrel_sum(0):
The value of \(\alpha_{\rm numrel,sum}\) in the hazard formula, corresponding to a weight for the number of relationships the men in the relationship have.formationmsm.hazard.agegap.numrel_diff(0):
The value of \(\alpha_{\rm numrel,diff}\) in the hazard expression, by which the influence of the difference in number of partners can be specified.formationmsm.hazard.agegap.meanage(0):
The value of \(\alpha_{\rm meanage}\) in the expression for the hazard, a weight for the average age of the partners.formationmsm.hazard.agegap.eagerness_sum(0):
Weight \(\alpha_{\rm eagerness,sum}\) for the sum of the eagerness parameters of both partners. Note that the relevant value here is the MSM eagerness.formationmsm.hazard.agegap.eagerness_diff(0):
Weight \(\alpha_{\rm eagerness,diff}\) for the difference of the eagerness parameters of both partners. Note that the relevant value here is the MSM eagerness.formationmsm.hazard.agegap.gap_factor(0):
This corresponds to \(\alpha_{\rm gap,factor}\), the weight for the age gap terms.formationmsm.hazard.agegap.gap_agescale(0):
This corresponds to \(\alpha_{\rm gap,agescale}\), by which you can control how the preferred age gap changes over time.formationmsm.hazard.agegap.distance(0):
This configures the weight \(\alpha_{\rm dist}\) of the geographical distance between the partners.formationmsm.hazard.agegap.beta(0):
Corresponds to \(\beta\) in the hazard expression and allows you to take the time since the relationship became possible into account.formationmsm.hazard.agegap.t_max(200):
Even though this hazard is no longer a simple time dependent exponential, it will still be necessary to provide some kind of cut-off, as explained in the section about ‘time limited’ hazards. This configuration value is a measure of this threshold.
4.4.13.3. The agegapry formation hazard (MSM version)¶
The agegapry formation hazard is again very similar to its heterosexual counterpart:
In this equation, the terms \(G_{\rm man1}\) and \(G_{\rm man2}\) for the age gap between partners in a relationship is given by the following expressions:
where \(g_{\rm man1}(t_{\rm ry})\) and \(g_{\rm man2}(t_{\rm ry})\) specify the preferred age gaps themselves, which can change over time:
In these equations again the following notation is used:
i.e., \(A(t)\) represents the age of someone. As with the heterosexual ‘agegapry’ hazard, the age gap prefactor is no longer a simple configurable constant: by tuning several parameters, the importance of these age gap terms can now be made age-dependent.
However, this age-dependence is again approximate because \(t_{\rm ry}\) is used in these expressions instead of the simulation time \(t\): see the documentation of its counterpart for more info. By setting \(\alpha_{\rm numrel,scale}\) using the same approximation the importance of the number of partners can be made dependent on the age gap. The meaning of the other quantities in the hazard is the same as in the ‘agegap’ hazard.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
formationmsm.hazard.agegapry.baseline(0.1):
The value of \(\alpha_{\rm baseline}\) in the expression for the hazard, allowing one to establish a baseline value.formationmsm.hazard.agegapry.numrel_sum(0):
The value of \(\alpha_{\rm numrel,sum}\) in the hazard formula, corresponding to a weight for the number of relationships the men in the relationship have.formationmsm.hazard.agegapry.numrel_scale(0):
The value of \(\alpha_{\rm numrel,scale}\) in the formula for the hazard.formationmsm.hazard.agegapry.numrel_diff(0):
The value of \(\alpha_{\rm numrel,diff}\) in the hazard expression, by which the influence of the difference in number of partners can be specified.formationmsm.hazard.agegapry.meanage(0):
The value of \(\alpha_{\rm meanage}\) in the expression for the hazard, a weight for the average age of the partners.formationmsm.hazard.agegapry.eagerness_sum(0):
Weight \(\alpha_{\rm eagerness,sum}\) for the sum of the eagerness parameters of both partners. Note that the relevant value here is the MSM eagerness.formationmsm.hazard.agegapry.eagerness_diff(0):
Weight \(\alpha_{\rm eagerness,diff}\) for the difference of the eagerness parameters of both partners. Note that the relevant value here is the MSM eagerness.formationmsm.hazard.agegapry.gap_factor_const(0):
The value of \(\alpha_{\rm gap,factor,const}\) in the age gap term \(G_{\rm manX}(t_{\rm ry})\).formationmsm.hazard.agegapry.gap_factor_exp(0):
The value of \(\alpha_{\rm gap,factor,exp}\) in the age gap term \(G_{\rm manX}(t_{\rm ry})\).formationmsm.hazard.agegapry.gap_factor_age(0):
The value of \(\alpha_{\rm gap,factor,age}\) in the age gap term \(G_{\rm manX}(t_{\rm ry})\).formationmsm.hazard.agegapry.gap_agescale(0):
This controls \(\alpha_{\rm gap,agescale}\), which allows you to vary the preferred age gap with the age of the men in the relationship.formationmsm.hazard.agegapry.distance(0):
This configures the weight \(\alpha_{\rm dist}\) of the geographical distance between the partners.formationmsm.hazard.agegapry.beta(0):
Corresponds to \(\beta\) in the hazard expression and allows you to take the time since the relationship became possible into account.formationmsm.hazard.agegapry.t_max(200):
As explained in the section about ‘time limited’ hazards, an exponential function needs some kind of threshold value (after which it stays constant) to be able to perform the necessary calculations. This configuration value is a measure of this threshold.formationmsm.hazard.agegapry.maxageref.diff(1):
As explained before, the age gap terms do not use the real time dependency \(t\), but refer to a reference time \(t_{\rm ry}\) that needs to be synchronized periodically using the synchronize reference year event. The program will abort if it detects that the last reference time synchronization was more than this amount of time ago, which by default is one year.
4.4.14. HIV seeding event¶
When introducing the initial population in the simulation, the persons are not
yet infected with HIV. To start the infection, an HIV seeding event is scheduled,
and when (controlled by hivseed.time) this is triggered, a certain amount of
people will be marked as HIV infected.
To do so, only the people that
have the right age (as specified by hivseed.age.min and hivseed.age.max)
and right gender (as specified by hivseed.gender)
will be possible ‘seeders’, and depending on the setting of hivseed.type
either a fixed number of people will be used, or each person will have a
certain probability of being a seeder. In case a fixed number is requested
but this number cannot be reached in the current simulation, the program
can be instructed to terminate depending on the hivseed.stop.short setting.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
hivseed.time(0):
This specifies the time at which the seeding event takes place; default is at the start of the simulation. Set to a negative value to disable HIV seeding.hivseed.type(‘fraction’):
This value specifies how the seeding will occur, eitherfractionto specify that each person in the possible seeders group will have a certain probability of being a seeder, oramountto specify that a fixed number of seeders should be chosen.hivseed.age.min(0):
People who are possible seeders must be at least this old.hivseed.age.max(1000):
People who are possible seeders must be at most this old.hivseed.gender(‘any’):
People who are possible seeders must have this gender. Can be eitherany(the default),maleorfemale.hivseed.fraction(0.2):
This is only used ifhivseed.typeis set tofraction, and specifies the probability each possible seeder has of actually becoming HIV infected.hivseed.amount(1):
Ifhivseed.typeisamount, this number of people will be chosen from the group of possible seeders and marked as being HIV infected.hivseed.stop.short(‘yes’):
In case a specific amount of seeders should be chosen but this amount is not available (e.g. due to a too restrictive allowed age range), the program will terminate if this is set toyes. It will continue despite not having the requested amount of seeders if set tono.
4.4.15. HSV2 seeding event¶
When introducing the initial population in the simulation, the persons are not
infected with HSV2. To start such an infection, an HSV2 seeding event is scheduled,
and when (controlled by hsv2seed.time) this is triggered, a certain amount of
people will be marked as HSV2 infected. They can then pass on their infection
status through the HSV2 transmission event.
If the event fires, only the people that
have the right age (as specified by hsv2seed.age.min and hsv2seed.age.max)
and right gender (as specified by hsv2seed.gender)
will be possible ‘seeders’, and depending on the setting of hsv2seed.type
either a fixed number of people will be used, or each person will have a
certain probability of being a seeder. In case a fixed number is requested
but this number cannot be reached in the current simulation, the program
can be instructed to terminate depending on the hsv2seed.stop.short setting.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
hsv2seed.time(-1):
This specifies the time at which the seeding event takes place; default is that HSV2 seeding is disabled.hsv2seed.type(‘fraction’):
This value specifies how the seeding will occur, eitherfractionto specify that each person in the possible seeders group will have a certain probability of being a seeder, oramountto specify that a fixed number of seeders should be chosen.hsv2seed.age.min(0):
People who are possible seeders must be at least this old.hsv2seed.age.max(1000):
People who are possible seeders must be at most this old.hsv2seed.gender(‘any’):
People who are possible seeders must have this gender. Can be eitherany(the default),maleorfemale.hsv2seed.fraction(0.2):
This is only used ifhsv2seed.typeis set tofraction, and specifies the probability each possible seeder has of actually becoming HSV2 infected.hsv2seed.amount(1):
Ifhsv2seed.typeisamount, this number of people will be chosen from the group of possible seeders and marked as being HSV2 infected.hsv2seed.stop.short(‘yes’):
In case a specific amount of seeders should be chosen but this amount is not available (e.g. due to a too restrictive allowed age range), the program will terminate if this is set toyes. It will continue despite not having the requested amount of seeders if set tono.
4.4.16. Simulation intervention event¶
It’s possible that you’d want certain configuration values to change during a simulation. For example, to lower the CD4 threshold that’s used to decide if a person will be offered antiretroviral treatment or not. Changing parameters in a very general way can be done using this simulation intervention event which, when triggered, reads files containing changed configuration settings and applies them.
Note that while the changed settings will certainly affect new events that are introduced into the simulation, it will depend on the particular event type whether events already scheduled in the system will be affected or not. If the event has a fixed time at which it will take place, this time will _not_ be changed due to the intervention event. However, if the event is hazard-based and parameters of the hazard were changed, then this will definitely have an effect on the event’s fire time.
Using this simulation intervention mechanism is easiest using R or Python, and this is described next. Manually specifying this in the configuration file is possible as well, as is described later.
4.4.16.1. Using R¶
To use simulation interventions in R, for each such intervention event you need to create a
list with configuration values that you’d like to change, just as when you
create the configuration settings that you pass to the simpact.run command.
Additionally, such a list should contain an entry called time, which
contains the simulation time at which the modified settings need to be
introduced. Additional interventions are of course allowed, so what you need
to pass to the simpact.run parameter called intervention, is a list
of these lists.
For example, suppose that we already have some configuration settings in cfg,
but that we’d like to set the CD4 threshold for treatment to 500 at simulation
time 5, and to 1000 at simulation time 10. We’d first create a list for the first
intervention event
iv1 <- list()
iv1["time"] <- 5
iv1["monitoring.cd4.threshold"] <- 500
and also a similar list for the second intervention:
iv2 <- list()
iv2["time"] <- 10
iv2["monitoring.cd4.threshold"] <- 1000
The full intervention configuration is then a list of these lists
iv <- list(iv1, iv2)
which is what we’ll pass to the simpact.run command:
res <- simpact.run(cfg, "/tmp/simpacttest", intervention=iv)
4.4.16.2. Using Python¶
To use simulation interventions in Python, for each such intervention event you need to create a
dictionary with configuration values that you’d like to change, just as when you
create the configuration settings that you pass to the PySimpactCyan run command.
Additionally, such a dictionary should contain an entry called time, which
contains the simulation time at which the modified settings need to be
introduced. Additional interventions are of course allowed, so what you need
to pass to the run parameter called interventionConfig, is a list
of these dictionaries.
For example, suppose that we already have some configuration settings in cfg,
but that we’d like to set the CD4 threshold for treatment to 500 at simulation
time 5, and to 1000 at simulation time 10. We’d first create a dictionary for the first
intervention event
iv1 = { }
iv1["time"] = 5
iv1["monitoring.cd4.threshold"] = 500
and also a similar dictionary for the second intervention:
iv2 = { }
iv2["time"] = 10
iv2["monitoring.cd4.threshold"] = 1000
The full intervention configuration is then a list of these dictionaries
iv = [iv1, iv2]
which is what we’ll pass to the run command (assuming our PySimpactCyan
object is called simpact):
res = simpact.run(cfg, "/tmp/simpacttest", interventionConfig=iv)
4.4.16.3. Manual configuration¶
In case you’re using the command line approach to run your
simulations and need to adjust simulation interventions manually, you can
enable this using the option intervention.enabled. Note that this setting
as well as other related settings are not used when the R or Python interface
is employed. In that case, use the relevant mechanism described above.
If this intervention mechanism is enabled, you’ll need to prepare one or more files which are similar to the full config file, but which only contain the settings that should be changed. For example, suppose that we’d like to set the CD4 threshold for treatment to 500 at simulation time 5, and to 1000 at simulation time 10. In that case we need two files, one with the line
monitoring.cd4.threshold = 500
and another file with the line
monitoring.cd4.threshold = 1000
Let’s call these files cd4_A.txt and cd4_B.txt respectively. In the
main config file, we need to make sure that the times for these intervention
events are mentioned using the intervention.times option, which should contain
a list of increasing times:
intervention.times = 5,10
To specify which file should be inspected at each time, we need to use the
intervention.baseconfigname and intervention.fileids settings. The first
one contains a template for the file name for each intervention, in which
the % sign is replaced by the corresponding string from intervention.fileids.
In our example, we could set
intervention.baseconfigname = cd4_%.txt
intervention.fileids = A,B
In case the last option is left blank, the % sign will be replaced by what
was specified in intervention.times, so the program would look for cd4_5.txt
and cd4_10.txt.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
intervention.enabled(‘no’):
Indicates if the simulation interventions should be used at certain times. Possible values areno(the default) andyes. The following options are only used in case this is set toyes.intervention.baseconfigname(no default):
This is only used ifintervention.enabledisyes, and contains a template for the filename that is used to store the modifications to the main config file in. In this template,%will be replaced by the relevant string fromintervention.fileids, or by the time inintervention.timesin case theintervention.fileidsoption is left empty.intervention.times(no default):
This is only used ifintervention.enabledisyes, and contains a comma separated list of times (positive and increasing) at which simulation interventions should be executed.intervention.fileids(no default):
This is only used ifintervention.enabledisyes, and should be either empty or a comma separated list with strings that should replace the%sign inintervention.baseconfigname. If empty, the time fromintervention.timeswill be used to replace%instead.
4.4.17. HIV infection monitoring event¶
When a person has been diagnosed as being infected with HIV,
monitoring events are scheduled to follow up on the progress of the disease
by inspecting the person’s CD4 count. If this CD4 count is
below the threshold set in monitoring.cd4.threshold, the person will be
offered antiretroviral treatment. Depending on the person’s
willingness to accept treatment, treatment will
then be started.
If treatment is started, the person’s set-point viral load value will be
lowered according to the setting in monitoring.fraction.log_viralload.
In this case no further monitoring events will be scheduled, but instead
the person will be at risk of dropping out of treatment and
the corresponding event will be scheduled.
On the other hand, if the person’s CD4 count was not below the threshold
or the person was not willing to start treatment,
a new monitoring event will be scheduled a while later. The precise interval
being used here, depends on the person’s CD4 count and the configuration
settings. In monitoring.interval.piecewise.cd4s and monitoring.interval.piecewise.times
you can specify comma separated lists of (increasing) CD4 values and their corresponding
intervals. If the CD4 value lies in between specified values, linear interpolation
will be used. If the CD4 count is less than the left-most value in this series,
the interval specified in monitoring.interval.piecewise.left will be used.
If it is larger than the right-most CD4 value, the interval from
monitoring.interval.piecewise.right is used instead.
After dropping out of treatment, a new diagnosis event will be scheduled which then leads to new monitoring events. If this is the case, the person will always be eligible for treatment, i.e. once a person has received treatment he’s always a candidate to start treatment again. Only the person’s willingness still matters then.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
monitoring.cd4.threshold(350.0):
This is the threshold value for a person’s CD4 count: if the count is below this value, treatment will be offered (which the person still can decline).monitoring.fraction.log_viralload(0.7):
If the person is eligible and willing to start treatment, ART will be started. The effect of this is that the person’s set-point viral load will be lowered by this fraction on a logarithmic scale. Calling this fraction \(f\), this corresponds to \(V_{\rm sp,new} = (V_{\rm sp})^f\).monitoring.interval.piecewise.cd4s(‘200,350’):
This is a comma separated list of increasing CD4 values, and is used when looking up the monitoring interval for a certain CD4 count.monitoring.interval.piecewise.times(‘0.25,0.25’):
This is a comma separated list of monitoring time intervals that correspond to the CD4 values specified inmonitoring.interval.piecewise.cd4s.monitoring.interval.piecewise.left(0.16666):
If the CD4 count is less than the left-most value specified inmonitoring.interval.piecewise.cd4s, then this interval is used (defaults to two months).monitoring.interval.piecewise.right(0.5):
If the CD4 count is more than the right-most value specified inmonitoring.interval.piecewise.cd4s, then this interval is used (defaults to six months).
4.4.18. Mortality event¶
To make sure that everyone in the simulation has a limited lifespan, regardless of being infected with HIV, there’s always a mortality event scheduled for each person. This time of death is based on a Weibull distribution and for a certain person, this is a fixed number that no longer changes during the simulation.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
mortality.normal.weibull.shape(4.0):
This specifies the shape parameter of the Weibull distribution.mortality.normal.weibull.scale(70.0):
This specifies a scale parameter to base the Weibull distribution on, but a difference between men and women still needs to be taken into account (see next option).mortality.normal.weibull.genderdiff(5.0):
For a woman, half this value is added to the scale parameter specified inmortality.normal.weibull.scale; for a man the same amount is subtracted.
4.4.19. Periodic logging event¶
In case you would like to keep track of how many people there are in the population
or how many were being treated, you can enable this event. The file specified in
periodiclogging.outfile.logperiodic will be used to write the following properties
to: the time the event fired, the size of the population and the number of people
receiving treatment at that time. The interval between such logging events is controlled
using the periodiclogging.interval setting. If periodiclogging.starttime is negative
(the default), the first event will take place after the first interval has passed.
Otherwise, the first event is scheduled to take place at the specified time.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
periodiclogging.interval(-1):
This setting specifies the interval that is used to schedule the periodic logging events. When one event fires, the next one is scheduled. If this is set to a negative value, no further events will be scheduled.periodiclogging.starttime(-1):
If negative, the first event will take place after the first interval has passed. If zero or positive, the first event will get executed at the corresponding time.periodiclogging.outfile.logperiodic(‘${SIMPACT_OUTPUT_PREFIX}periodiclog.csv’):
This specifies the file to which the logging occurs. By default, the value of the config variable or environment variableSIMPACT_OUTPUT_PREFIXwill be prepended toperiodiclog.csvto yield the complete filename.
4.4.20. Relocation event¶
In case a non-trivial 2D location is assigned to each person, and the formation hazard depends on the geographical distance between possible partners or if an ‘eyecap’ setting is used, a relocation event may become interesting. Such an event changes the 2D location that’s assigned to a person, and writes a log entry to be able to keep track of a person.
If enabled (see relocation.enabled), the hazard used is a time-dependent exponential
hazard:
Here, a baseline value \(a\) can be configured using the relocation.hazard.a
setting, and the age of the person can be taken into account using the value
of \(b\) (the relocation.hazard.b setting).
The effect of a relocation is slightly different depending on the ‘eyecap’ fraction used. In case this is one, and everyone can have a relationship with everyone else, this just changes the location of the person. By controlling the importance of the geographical distance between partners in the formation event hazards, this can still affect which precise relationships will be formed. When only a fraction of the population can be seen however, triggering of the relocation event will cause all existing scheduled formation events to get cancelled. After choosing a new location of the person, a new set of interests will be generated and formation events for these persons will get scheduled.
Note that existing, formed relationships are currently not affected by this relocation event.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
relocation.enabled(‘no’):
This controls if relocation events should be scheduled or not.relocation.hazard.a(no default):
Sets the value of \(a\) in the relocation hazard above.relocation.hazard.b(no default):
Sets the value of \(b\) in the relocation hazard above.relocation.hazard.t_max(200):
As explained in the section about ‘time limited’ hazards, an exponential function needs some kind of threshold value (after which it stays constant) to be able to perform the necessary calculations. This configuration value is a measure of this threshold.
4.4.21. Synchronize population statistics¶
As described in the formation event, it’s possible that an event needs to use the current population size in calculating its hazard. For a large population, there will also be many birth and mortality events, and recalculating hazards for every change in population size will slow the simulation down considerably.
If the population size does not change much during the simulation, it may be adequate to just use the population size at the beginning of the simulation. On the other hand, if the number of people in the simulation tends to grow or shrink considerably, this will be a poor approximation. In that case, this event can be useful, which allows you to resynchronize the stored population size. This is a global event, meaning that afterwards event fire times for _all_ scheduled events will be recalculated, so don’t use this more than necessary.
If this event is needed, the interval between such synchronization events can be specified
using the syncpopstats.interval configuration option. When one event fires, the next
is scheduled to go off the specified time later.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
syncpopstats.interval(-1):
This specifies the interval between these synchronization events. A negative value means that it’s disabled.
4.4.22. Synchronize reference year¶
With this event, a reference time can be saved in the simulation. This is used by the ‘agegapry’ formation hazard and HIV transmission hazard, to simplify the complexity of the hazards. Scheduling of the event can be disabled by setting it to a negative value (the default).
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
syncrefyear.interval(-1):
Specifies the time interval with which a reference simulation time should be saved. A negative value disables this.
4.4.23. HIV transmission event¶
When a relationship is formed between two people of which one is HIV infected, or when a relationship between two uninfected people exists and one of them gets infected, an HIV transmission event is scheduled. The hazard for this event is the following:
In this hazard, the value of \(V\) is the current viral load of the person, which can differ from the set-point viral load. The number of partners of the person who is already infected is specified by \(P_{\rm infected}\), while the number of partners of the person who will become infected when the event fires, is \(P_{\rm uninfected}\). The value of \({\rm W}\) is \(1\) if the uninfected person is a woman, and 0 otherwise. By configuring the weights \(f_1\) and \(f_2\), is becomes possible to change the susceptibility of a woman depending on her age. Note that this age is only specified approximately by using a reference time \(t_{\rm ry}\) instead of the actual time \(t\). This reference time can be updated using the reference year synchronization event. The values \(a\), \(b\), \(c\), \(d_1\), \(d_2\), \(f_1\) and \(f_2\) can be configured as specified below; the \(A_{\rm debut}\) parameter is the debut age.
The form of this hazard was originally inspired by the article of [Hargrove et al]. The default parameters that are mentioned below are based on a fit to the data from the [Fraser et al] article.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
hivtransmission.param.a(-1.3997):
This refers to the value of \(a\) in the expression for the hazard, providing a baseline value.hivtransmission.param.b(-12.0220):
This refers to the value of \(b\) in the expression for the hazard. Together with the value of \(c\), this specifies the influence of the current viral load of the infected person.hivtransmission.param.c(0.1649):
This refers to the value of \(c\) in the expression for the hazard. Together with the value of \(b\), this specifies the influence of the current viral load of the infected person.hivtransmission.param.d1(0):
This refers to the value of \(d_1\) in the expression for the hazard, providing a weight based on the number of partners of the infected person.hivtransmission.param.d2(0):
This refers to the value of \(d_2\) in the expression for the hazard, providing a weight based on the number of partners of the uninfected person.hivtransmission.param.f1(0):
This refers to the value of \(f_1\) in the expression of the hazard.hivtransmission.param.f2(0):
This refers to the value of \(f_2\) in the expression of the hazard.hivtransmission.maxageref.diff(1):
As explained above, the hazard does not use the real time dependency \(t\), but refers to a reference time \(t_{\rm ry}\) that needs to be synchronized periodically using the synchronize reference year event. The program will abort if it detects that the last reference time synchronization was more than this amount of time ago, which by default is one year.
4.4.24. HSV2 transmission event¶
When a person is HSV2 infected and and a relationship is formed, an HSV2 transmission event will be scheduled. A time dependent exponential hazard is used:
The value of \(a_i\) can be set using person.hsv2.a.dist.type from the
HSV2 related person settings. This value is taken from
the person that’s already infected. The \(b\) value can be configured using
hsv2transmission.hazard.b, and \(t_{\rm infected}\) is the time at which
the infected person acquired the HSV2 infection.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
hsv2transmission.hazard.b(0):
This configures the value of \(b\) in the hazard above.hsv2transmission.hazard.t_max(200):
As explained in the section about ‘time limited’ hazards, an exponential function needs some kind of threshold value (after which it stays constant) to be able to perform the necessary calculations. This configuration value is a measure of this threshold.