Output file formats

Results reports

Whenever the _report is executed, it writes output in CSV format either to the standard output device (default) or an output file as specified by the results_file key in the configuration. This output is meant to be post-processed by you either in a spreadsheet, or using a scripting language like R or Python.

Note

The _report event prints out quite basic information. If you feel comfortable writing C code, you can enhance it in the fsti_userdefs.h file by defining the FSTI_HOOK_REPORT macro. See the FSTI_REPORT macro in fsti-defaults.h.

Here is an example output from a set of simulations:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
   name;sim;num;date;description;value
   Simulation_0;0;0;2018-01-01;MIN_AGE_ALIVE;15.000000
   Simulation_0;0;0;2018-01-01;MAX_AGE_ALIVE;49.000000
   Simulation_0;0;0;2018-01-01;MEAN_AGE_ALIVE;23.000000
   Simulation_0;0;0;2018-01-01;MEDIAN_AGE_ALIVE;18.000000
   Simulation_0;0;0;2018-01-01;INFECT_RATE_ALIVE;0.077900
   Simulation_0;0;0;2018-01-01;POP_ALIVE;20000
   Simulation_0;0;0;2018-01-01;NUM_PARTNERS;3573
   Simulation_0;0;0;2018-01-01;MIN_AGE_DEAD;nan
   Simulation_0;0;0;2018-01-01;MAX_AGE_DEAD;nan
   Simulation_0;0;0;2018-01-01;MEAN_AGE_DEAD;nan
   Simulation_0;0;0;2018-01-01;INFECT_RATE_DEAD;-nan
   Simulation_0;0;0;2018-01-01;POP_DEAD;0
   Simulation_0;0;0;2018-01-01;INITIAL_INFECTIONS;1558
   Simulation_0;0;0;2018-01-01;SIMULATION_INFECTIONS;0
   Simulation_0;0;0;2018-01-01;INITIAL_MATCHES;3573
   Simulation_0;0;0;2018-01-01;SIMULATION_MATCHES;0
   Simulation_0;0;0;2018-01-01;BREAKUPS;0
   Simulation_0;0;0;2018-01-01;TIME_TAKEN;1
   Simulation_0;0;0;2028-01-01;MIN_AGE_ALIVE;15.000000
   Simulation_0;0;0;2028-01-01;MAX_AGE_ALIVE;59.000000
   Simulation_0;0;0;2028-01-01;MEAN_AGE_ALIVE;30.000000
   Simulation_0;0;0;2028-01-01;MEDIAN_AGE_ALIVE;26.000000
   Simulation_0;0;0;2028-01-01;INFECT_RATE_ALIVE;0.142421
   Simulation_0;0;0;2028-01-01;POP_ALIVE;23592
   Simulation_0;0;0;2028-01-01;NUM_PARTNERS;8442
   Simulation_0;0;0;2028-01-01;MIN_AGE_DEAD;15.000000
   Simulation_0;0;0;2028-01-01;MAX_AGE_DEAD;58.000000
   Simulation_0;0;0;2028-01-01;MEAN_AGE_DEAD;31.000000
   Simulation_0;0;0;2028-01-01;INFECT_RATE_DEAD;0.738192
   Simulation_0;0;0;2028-01-01;POP_DEAD;741
   Simulation_0;0;0;2028-01-01;INITIAL_INFECTIONS;1558
   Simulation_0;0;0;2028-01-01;SIMULATION_INFECTIONS;2349
   Simulation_0;0;0;2028-01-01;INITIAL_MATCHES;3573
   Simulation_0;0;0;2028-01-01;SIMULATION_MATCHES;145574
   Simulation_0;0;0;2028-01-01;BREAKUPS;140193
   Simulation_0;0;0;2028-01-01;TIME_TAKEN;6
   Simulation_0;1;1;2018-01-01;MIN_AGE_ALIVE;15.000000
   Simulation_0;1;1;2018-01-01;MAX_AGE_ALIVE;49.000000
   Simulation_0;1;1;2018-01-01;MEAN_AGE_ALIVE;23.000000
   Simulation_0;1;1;2018-01-01;MEDIAN_AGE_ALIVE;18.000000
   Simulation_0;1;1;2018-01-01;INFECT_RATE_ALIVE;0.080300
   Simulation_0;1;1;2018-01-01;POP_ALIVE;20000
   Simulation_0;1;1;2018-01-01;NUM_PARTNERS;3601
   Simulation_0;1;1;2018-01-01;MIN_AGE_DEAD;nan
   Simulation_0;1;1;2018-01-01;MAX_AGE_DEAD;nan
   Simulation_0;1;1;2018-01-01;MEAN_AGE_DEAD;nan
   Simulation_0;1;1;2018-01-01;INFECT_RATE_DEAD;-nan
   Simulation_0;1;1;2018-01-01;POP_DEAD;0
   Simulation_0;1;1;2018-01-01;INITIAL_INFECTIONS;1606
   Simulation_0;1;1;2018-01-01;SIMULATION_INFECTIONS;0
   Simulation_0;1;1;2018-01-01;INITIAL_MATCHES;3601
   Simulation_0;1;1;2018-01-01;SIMULATION_MATCHES;0
   Simulation_0;1;1;2018-01-01;BREAKUPS;0
   Simulation_0;1;1;2018-01-01;TIME_TAKEN;6
   Simulation_0;1;1;2028-01-01;MIN_AGE_ALIVE;15.000000
   Simulation_0;1;1;2028-01-01;MAX_AGE_ALIVE;59.000000
   Simulation_0;1;1;2028-01-01;MEAN_AGE_ALIVE;30.000000
   Simulation_0;1;1;2028-01-01;MEDIAN_AGE_ALIVE;26.000000
   Simulation_0;1;1;2028-01-01;INFECT_RATE_ALIVE;0.142754
   Simulation_0;1;1;2028-01-01;POP_ALIVE;23516
   Simulation_0;1;1;2028-01-01;NUM_PARTNERS;8432
   Simulation_0;1;1;2028-01-01;MIN_AGE_DEAD;15.000000
   Simulation_0;1;1;2028-01-01;MAX_AGE_DEAD;55.000000
   Simulation_0;1;1;2028-01-01;MEAN_AGE_DEAD;31.000000
   Simulation_0;1;1;2028-01-01;INFECT_RATE_DEAD;0.768553
   Simulation_0;1;1;2028-01-01;POP_DEAD;795
   Simulation_0;1;1;2028-01-01;INITIAL_INFECTIONS;1606
   Simulation_0;1;1;2028-01-01;SIMULATION_INFECTIONS;2362
   Simulation_0;1;1;2028-01-01;INITIAL_MATCHES;3601
   Simulation_0;1;1;2028-01-01;SIMULATION_MATCHES;146416
   Simulation_0;1;1;2028-01-01;BREAKUPS;141010
   Simulation_0;1;1;2028-01-01;TIME_TAKEN;11
   Simulation_1;2;0;2018-01-01;MIN_AGE_ALIVE;15.000000
   Simulation_1;2;0;2018-01-01;MAX_AGE_ALIVE;49.000000
   Simulation_1;2;0;2018-01-01;MEAN_AGE_ALIVE;23.000000
   Simulation_1;2;0;2018-01-01;MEDIAN_AGE_ALIVE;18.000000
   Simulation_1;2;0;2018-01-01;INFECT_RATE_ALIVE;0.080600
   Simulation_1;2;0;2018-01-01;POP_ALIVE;20000
   Simulation_1;2;0;2018-01-01;NUM_PARTNERS;3569
   Simulation_1;2;0;2018-01-01;MIN_AGE_DEAD;nan
   Simulation_1;2;0;2018-01-01;MAX_AGE_DEAD;nan
   Simulation_1;2;0;2018-01-01;MEAN_AGE_DEAD;nan
   Simulation_1;2;0;2018-01-01;INFECT_RATE_DEAD;-nan
   Simulation_1;2;0;2018-01-01;POP_DEAD;0
   Simulation_1;2;0;2018-01-01;INITIAL_INFECTIONS;1612
   Simulation_1;2;0;2018-01-01;SIMULATION_INFECTIONS;0
   Simulation_1;2;0;2018-01-01;INITIAL_MATCHES;3569
   Simulation_1;2;0;2018-01-01;SIMULATION_MATCHES;0
   Simulation_1;2;0;2018-01-01;BREAKUPS;0
   Simulation_1;2;0;2018-01-01;TIME_TAKEN;5
   Simulation_1;2;0;2028-01-01;MIN_AGE_ALIVE;15.000000
   Simulation_1;2;0;2028-01-01;MAX_AGE_ALIVE;59.000000
   Simulation_1;2;0;2028-01-01;MEAN_AGE_ALIVE;30.000000
   Simulation_1;2;0;2028-01-01;MEDIAN_AGE_ALIVE;26.000000
   Simulation_1;2;0;2028-01-01;INFECT_RATE_ALIVE;0.136983
   Simulation_1;2;0;2028-01-01;POP_ALIVE;23638
   Simulation_1;2;0;2028-01-01;NUM_PARTNERS;8423
   Simulation_1;2;0;2028-01-01;MIN_AGE_DEAD;15.000000
   Simulation_1;2;0;2028-01-01;MAX_AGE_DEAD;59.000000
   Simulation_1;2;0;2028-01-01;MEAN_AGE_DEAD;32.000000
   Simulation_1;2;0;2028-01-01;INFECT_RATE_DEAD;0.717507
   Simulation_1;2;0;2028-01-01;POP_DEAD;754
   Simulation_1;2;0;2028-01-01;INITIAL_INFECTIONS;1612
   Simulation_1;2;0;2028-01-01;SIMULATION_INFECTIONS;2167
   Simulation_1;2;0;2028-01-01;INITIAL_MATCHES;3569
   Simulation_1;2;0;2028-01-01;SIMULATION_MATCHES;145976
   Simulation_1;2;0;2028-01-01;BREAKUPS;140568
   Simulation_1;2;0;2028-01-01;TIME_TAKEN;10
   Simulation_1;3;1;2018-01-01;MIN_AGE_ALIVE;15.000000
   Simulation_1;3;1;2018-01-01;MAX_AGE_ALIVE;49.000000
   Simulation_1;3;1;2018-01-01;MEAN_AGE_ALIVE;23.000000
   Simulation_1;3;1;2018-01-01;MEDIAN_AGE_ALIVE;18.000000
   Simulation_1;3;1;2018-01-01;INFECT_RATE_ALIVE;0.083850
   Simulation_1;3;1;2018-01-01;POP_ALIVE;20000
   Simulation_1;3;1;2018-01-01;NUM_PARTNERS;3550
   Simulation_1;3;1;2018-01-01;MIN_AGE_DEAD;nan
   Simulation_1;3;1;2018-01-01;MAX_AGE_DEAD;nan
   Simulation_1;3;1;2018-01-01;MEAN_AGE_DEAD;nan
   Simulation_1;3;1;2018-01-01;INFECT_RATE_DEAD;-nan
   Simulation_1;3;1;2018-01-01;POP_DEAD;0
   Simulation_1;3;1;2018-01-01;INITIAL_INFECTIONS;1677
   Simulation_1;3;1;2018-01-01;SIMULATION_INFECTIONS;0
   Simulation_1;3;1;2018-01-01;INITIAL_MATCHES;3550
   Simulation_1;3;1;2018-01-01;SIMULATION_MATCHES;0
   Simulation_1;3;1;2018-01-01;BREAKUPS;0
   Simulation_1;3;1;2018-01-01;TIME_TAKEN;5
   Simulation_1;3;1;2028-01-01;MIN_AGE_ALIVE;15.000000
   Simulation_1;3;1;2028-01-01;MAX_AGE_ALIVE;59.000000
   Simulation_1;3;1;2028-01-01;MEAN_AGE_ALIVE;30.000000
   Simulation_1;3;1;2028-01-01;MEDIAN_AGE_ALIVE;26.000000
   Simulation_1;3;1;2028-01-01;INFECT_RATE_ALIVE;0.139352
   Simulation_1;3;1;2028-01-01;POP_ALIVE;23595
   Simulation_1;3;1;2028-01-01;NUM_PARTNERS;8456
   Simulation_1;3;1;2028-01-01;MIN_AGE_DEAD;15.000000
   Simulation_1;3;1;2028-01-01;MAX_AGE_DEAD;58.000000
   Simulation_1;3;1;2028-01-01;MEAN_AGE_DEAD;31.000000
   Simulation_1;3;1;2028-01-01;INFECT_RATE_DEAD;0.728205
   Simulation_1;3;1;2028-01-01;POP_DEAD;780
   Simulation_1;3;1;2028-01-01;INITIAL_INFECTIONS;1677
   Simulation_1;3;1;2028-01-01;SIMULATION_INFECTIONS;2179
   Simulation_1;3;1;2028-01-01;INITIAL_MATCHES;3550
   Simulation_1;3;1;2028-01-01;SIMULATION_MATCHES;146061
   Simulation_1;3;1;2028-01-01;BREAKUPS;140609
   Simulation_1;3;1;2028-01-01;TIME_TAKEN;10
  • The first column (name) is the simulation group name as specified in the configuration file.
  • The second column (sim) is the unique simulation number. In every execution of FastSTI, each simulation will have its own unique id, starting from 0.
  • The third column (num) is the number of the simulation within the simulation group. Here each of the two simulation groups (Simulation_0 and Simulation_1) executed two simulations each, numbered 0 and 1.
  • The fourth column is the date within the simulation that this snapshot report is for. In these simulations, the start date was 1 January 2018, and the end date was 1 January 2028. The _report event ran before and after the simulation (it can run as often as you like during the simulation as well).
  • The fifth column is the description of what’s being reported. These are described below.
  • The sixth column is the value of what’s being reported. E.g. 10 for TIME_TAKEN means the simulation ran in 10 seconds up to that point.

Warning

The output in the example above is all in chronological order. This is because it was a single-threaded sequential execution. Normally you will do a multithreaded execution and the report lines will likely not come out in order. When analysing them in a spreadsheet, R or Python, remember to sort the output by the first four columns.

What the descriptions mean

MIN_AGE_ALIVE
is the youngest age, in years, of a currently living agent
MAX_AGE_ALIVE
is the oldest age, in years of a currently living agent
MEAN_AGE_ALIVE
is the mean age, in years, of the living population
MEDIAN_AGE_ALIVE
is the median age, in years, of the living population
INFECT_RATE_ALIVE
is the infection rate of the living population
POP_ALIVE
is the number of living agents
NUM_PARTNERS
is the number of agents in relationships
MIN_AGE_DEAD
is the age of the youngest agent who has died
MAX_AGE_DEAD
is the age of the oldest agent who has died
INFECT_RATE_DEAD
is the infection rate in the dead population
POP_DEAD
is the number of dead agents
INITIAL_INFECTIONS
is the number of infected agents at the start of the simulation
SIMULATION_INFECTIONS
is the number of agents who became infected during the simulation
INITIAL_MATCHES
is the number of pairs of agents in relationships at the start of the simulation
SIMULATION_MATCHES
is the number of pairs of agents made during the simulation
BREAKUPS
is the number of pairs that broke up during the simulation
TIME_TAKEN
is the time taken by the simulation in seconds

Agent output

The _write_agents_csv_header prints out the header line in an output agent csv file. The _write_agents_csv event actually writes out all the agents (living and dead), and the _write_living_agents_csv and _write_dead_agents_csv write the living and dead agents respectively.

Here is an extract from sample output of the _write_agents_csv_header and _write_agents_csv events.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
   sim;date;id;age;sex;sex_preferred;infected;treated;resistant;date_death;partner;change_date
   1;2028-01-01;1547;25;0;1;0;0;0;0000-00-00;515;2035-10-24
   1;2028-01-01;1548;41;0;1;4;0;0;2023-10-11;-1;2025-10-30
   1;2028-01-01;1549;28;0;1;0;0;0;0000-00-00;6620;2028-04-22
   1;2028-01-01;1550;25;1;0;0;0;0;0000-00-00;3910;2029-09-04
   1;2028-01-01;1551;31;1;0;1;1;0;0000-00-00;22910;2028-01-13
   1;2028-01-01;1552;30;1;0;0;0;0;0000-00-00;18055;2028-01-03
   1;2028-01-01;1553;36;1;0;0;0;0;0000-00-00;7448;2028-10-14
   1;2028-01-01;1554;33;1;0;0;0;0;0000-00-00;694;2028-04-25
   1;2028-01-01;1555;28;0;0;0;0;0;0000-00-00;984;2028-03-23
   1;2028-01-01;1556;28;0;1;0;0;0;0000-00-00;4467;2030-03-27
   1;2028-01-01;1557;45;0;1;0;0;0;0000-00-00;15614;2035-01-22
   1;2028-01-01;1558;27;1;0;0;0;0;0000-00-00;3367;2030-02-17
   1;2028-01-01;1559;29;0;1;0;0;0;0000-00-00;10884;2030-01-10
   1;2028-01-01;1560;52;1;0;0;0;0;0000-00-00;19043;2028-05-24
   1;2028-01-01;1561;58;1;0;0;0;0;0000-00-00;13638;2028-07-01
   1;2028-01-01;1562;30;1;0;0;0;0;0000-00-00;14842;2030-02-19
   1;2028-01-01;1563;57;0;1;0;0;0;0000-00-00;17535;2029-03-13
   1;2028-01-01;1564;37;1;0;1;1;1;0000-00-00;15586;2031-10-26
   1;2028-01-01;1565;29;1;0;0;4;0;2026-11-30;-1;2027-08-30
   1;2028-01-01;1566;46;1;0;0;0;0;0000-00-00;-1;2030-03-21
   1;2028-01-01;1567;26;1;0;0;0;0;0000-00-00;16097;2029-03-04

The first column is the simulation number. The second column is the current simulation date. The third column is the unique agent id. The fourth to ninth columns are the agent’s sex, preferred sex, infection stage, treatment regimen, and resistance status respectively. The tenth column is 0000-00-00 if the agent is alive, else the date the agent died. The eleventh column is the unique id of the agent’s partner (-1 if the agent is single). The last column is the date the agent’s relationship status will change, either to single if it’s in a relationship, or to a relationship if it’s single.

Note

FastSTI’s agent output event assumes an agent has at most one partner. You can extend it if you’re implementing concurrency.

Note

If you feel comfortable writing C code, you can modify or extend the output of the _write_agents_csv, _write_living_agents_csv and _write_dead_agents_csv events by redefining the FSTI_AGENT_PRINT_CSV_HEADER and FSTI_AGENT_PRINT_CSV macros. Put your redefinition in src/fsti-userdefs.h. The default implementation is in src/fsti-defaults.h.