By default, several log files are used, but they can be disabled by assigning an empty string to the configuration property. If you're using the R or Python interface, the full paths of these log files will be stored in the object returned by simpact.run
or the PySimpactCyan
method run
.
Here is an overview of the relevant configuration options, their defaults (between parentheses), and their meaning:
logsystem.outfile.logevents
('${SIMPACT_OUTPUT_PREFIX}eventlog.csv'): Here, all events that take place are logged. See the section about theconfiguration file <configfile>
for additional information regarding theSIMPACT_OUTPUT_PREFIX
variable.logsystem.outfile.logpersons
('${SIMPACT_OUTPUT_PREFIX}personlog.csv'): In this file, information about every person in the simulation is stored. See the section about theconfiguration file <configfile>
for additional information regarding theSIMPACT_OUTPUT_PREFIX
variable.logsystem.outfile.logrelations
('${SIMPACT_OUTPUT_PREFIX}relationlog.csv'): Here, all relationships are logged. See the section about theconfiguration file <configfile>
for additional information regarding theSIMPACT_OUTPUT_PREFIX
variable.logsystem.outfile.logtreatments
('${SIMPACT_OUTPUT_PREFIX}treatmentlog.csv'): This file records information regarding treatments. See the section about theconfiguration file <configfile>
for additional information regarding theSIMPACT_OUTPUT_PREFIX
variable.logsystem.outfile.logviralloadhiv
('${SIMPACT_OUTPUT_PREFIX}hivviralloadlog.csv'): In this file the HIV viral load changes can be seen for different individuals. See the section about theconfiguration file <configfile>
for additional information regarding theSIMPACT_OUTPUT_PREFIX
variable.logsystem.outfile.logsettings
('${SIMPACT_OUTPUT_PREFIX}settingslog.csv'): This file records the settings that were used at the start of the program and after eachsimulation intervention <simulationintervention>
.logsystem.outfile.loglocation
('${SIMPACT_OUTPUT_PREFIX}locationlog.csv'): This file records the geographical locations that were assigned to a person. In case a non-trivialgeographical distribution <geodist>
is used andrelocations <relocation>
are enabled, this allows persons to be tracked throughout the simulation.
The event log is a CSV-like file, in which each line contains at least ten entries:
- The simulation time at which the event took place
- A short description of the event
- The name of the first person involved in the event, or
(none)
- The person ID of the first person involved, or -1
- The gender (0 for a man, 1 for a woman) of the first person involved in the event, or -1
- The age of the first person involved in the event, or -1
- The name of the second person involved in the event, or
(none)
- The person ID of the second person involved, or -1
- The gender (0 for a man, 1 for a woman) of the second person involved in the event, or -1
- The age of the second person involved in the event, or -1
On a specific line, more entries may be present. In that case, the number of extra entries will be a multiple of two, with the first entry of a pair being a short description and the second the actual value.
Some event descriptions are within parentheses, like (childborn)
or (relationshipended)
. These aren't actual events themselves, but a kind of pseudo-event: they are log entries for certain actions that are triggered by a real mNRM-event. For example, a birth event <birth>
will trigger the (childborn)
pseudo-event, to be able to have a log entry for the new person that is introduced into the population. The (relationshipended)
pseudo-event is triggered both by the dissolution of a relationship <dissolution>
and the death of a person, either by AIDS related causes <aidsmortality>
or due to a 'normal' mortality event <mortality>
.
The person log file is a CSV file with entries for each person in the simulation, both for persons who are deceased and who are still alive when the simulation finished. At the moment, the following columns are defined:
ID
: The ID of the person that this line is about.Gender
: The gender (0 for a man, 1 for a woman) of the person that this line is about.TOB
: The time of birth of this person.TOD
: The time of death of this person, orinf
(infinity) if the person is still alive when the simulation ends.IDF
: The ID of the father of this person, or -1 if the person is part of the initial population created at the start of the simulation.IDM
: The ID of the mother of this person, or -1 if the person is part of the initial population created at the start of the simulation.TODebut
: The simulation time at which the person became sexually active. If this is zero, it means that the person was already old enough at the start of the simulation, otherwise it's the time at which thedebut event <debut>
for this person took place (orinf
if debut did not take place yet).FormEag
: The value of theformation eagerness <eagerness>
parameter for this person for forming heterosexual relationships, which can be used in theformation event <formation>
.FormEagMSM
: The value of theformation eagerness <eagerness>
parameter for this person for MSM relationships, which can be used in theMSM formation event <formationmsm>
.InfectTime
: The time at which this person became HIV-infected, orinf
if the person was not infected. Will be the time at which either anHIV seeding event <hivseeding>
took place, or at which atransmission event <transmission>
took place.InfectOrigID
: The ID of the person that infected the current person, or -1 if the current person was not infected or infected by aseeding event <hivseeding>
.InfectType
: This will be -1 if the person was not infected, 0 if the person got infected due to aseeding event <hivseeding>
and 1 if due to atransmission event <transmission>
.log10SPVL
: If infected, this contains the logarithm (base 10) of the set-point viral load of this person that was first chosen (so _not affected by treatment). If not infected, this will be-inf
.TreatTime
: The time at which this person last received treatment, orinf
if no treatment was received.XCoord
: Each person is assigneda geographic location <geodist>
, of which this is the x-coordinate. In caserelocations <relocation>
are possible, the value in this log file will be the last one in the simulation. For more detailed information thelocation log file <locationlog>
can be used.YCoord
: Each person is assigneda geographic location <geodist>
, of which this is the y-coordinate. In caserelocations <relocation>
are possible, the value in this log file will be the last one in the simulation. For more detailed information thelocation log file <locationlog>
can be used.AIDSDeath
: Indicates what the cause of death for this person was. Is -1 in case the person is still alive at the end of the simulation, 0 if the person died from non-AIDS related causes, and +1 in case the person's death was caused by AIDS.HSV2InfectTime
: This is the time at which this person became HSV2 infected, orinf
in case the person is not infected.HSV2InfectOriginID
: The ID of the person that's the origin of the HSV2 infection, or -1 if there is none (no infection or seeded).CD4atInfection
: As explained inthe CD4 count <cd4count>
related documentation, the CD4 values at start of infection and at time of death are currently chosen from a distribution. This column will contain the first of these values when the person is infected, or -1 otherwise.CD4atDeath
: Similar to the previous column, but will contain the CD4 value at the time of (AIDS related) death.
In the relationship log, information about all dissolved relationships is logged, as well as information about relationships that still exist when the simulation ends. The file is a CSV file, currently with five columns:
ID1
: The ID of the first person in the relationship.ID2
: The ID of the second person in the relationship.FormTime
: The time the relationship between these two people got formed.DisTime
: The time at which the relationship between these two people dissolved, orinf
(infinity) if the relationship still existed when the simulation ended.AgeGap
: the age difference between the man and the woman in the relationship. A positive value means that the man is older than the woman.MSM
: If 1, then the relationship is an MSM relation, if 0 it's a heterosexual relationship.
This CSV file contains information about all antiretroviral treatments that took place during the simulation, both for treatments that are ongoing when the simulation ended and for treatments that were ended during the simulation (due to the person dropping out <dropout>
or dying). The file currently has five columns:
ID
: the ID of the person that received treatmentGender
: The gender (0 for a man, 1 for a woman) of the person that got treatedTStart
: The time at which the treatment startedTEnd
: The time at which the treatment ended (by dropping out or because the person died). In case treatment was still going on when the simulation ended, this isinf
(infinity).DiedNow
: If the treatment got stopped because the person died, this flag will be 1. Otherwise it will be 0.CD4atARTstart
: The value of the CD4 count of this person right before the treatment started.
This CSV log file describes the changes in the HIV viral load of different individuals. As described in the section about HIV viral load related options <viralload>
, each person has a set-point viral load, which is the observed viral load in the chronic stage (see also the section about the general flow of the simulation <generalflow>
). In the acute stage and AIDS stages, the observed viral load is derived from this set-point value.
The file currently has five columns:
Time
: the time at which the viral load for a person was changedID
: the ID of the person for whom the viral load was changed
Desc
: a description of the cause of the change, which can be one of the following:
Infection by seeding
: a person became infected due to theHIV seeding event<hivseeding>
.Infection by transmission
: a person became infected bytransmission <transmission>
of the virus.Chronic stage
: a person entered thechronic stage <chronicstage>
.AIDS stage
: anAIDS stage event <aidsstage>
got triggered, advancing the person from the chronic stage to the AIDS stage.Final AIDS stage
: anAIDS stage event <aidsstage>
got triggered, advancing the person from the AIDS stage to the final AIDS stage.Started ART
: the viral load was lowered thanks to starting ART during amonitoring event <monitoring>
.Dropped out of ART
: the viral load was increased because the persondropped out <dropout>
of treatment.Log10SPVL
: this is the set-point viral load of the person, on a logarithmic scale. This value is the base value that's used to calculate the actual, observed viral load from.Log10VL
: the observed viral load of the person, on a logarithmic scale.
The settings log file contains the settings used throughout the simulation. The names of the columns describe the configuration options being logged, and there will be a row with values of these configuration options each time the settings got changed. The time at which they were applied is also recorded in the log file in the first column. The first row in the log file will describe the names of the columns and at least one other row will be present, describing the settings used when the simulation was initialized. In case simulation intervention events <simulationintervention>
are used, additional rows will be present.
This means that the structure of the settings log will look like the one below in case a simulation intervention event was used to change a parameter of the 'agegap' formation hazard <agegaphazard>
after ten years in the simulation:
"t","aidsstage.final", ..., "formation.hazard.agegap.baseline", ...
0 , 0.5 , ..., 0.1 , ...
10 , 0.5 , ..., 0.2 , ...
The person log file <personlog>
records the geographical location <geodist>
of a person, but this is only the last known location. By default, the location of a person is set to (0, 0), but if a non-trivial geographical distribution is used instead, relocation events <relocation>
may be of interest. In this case however, a person can have multiple locations throughout the simulation, and a single entry in the person log file <personlog>
will no longer suffice.
For this reason, each time a person is assigned a 2D location, an entry is written to a location log file. The columns in this file are:
Time
: the time at which the person was assigned the specified location.ID
: the identifier of the person this location applies to.XCoord
: the x-coordinate of the location of the person.YCoord
: the y-coordinate of the location of the person.