ReportEventRecorder¶
The health events and interventions report (ReportEventRecorder.csv) is a CSV-formatted output file which provides information on each individual’s demographics and health states as well as events and interventions, such as Birth, Pregnant, DiseaseDeath, and other channels (including user-specified channels). Additionally, it is possible to list whether an individual has been assigned IndividualProperties (which are configured in the demographics file; see NodeProperties and IndividualProperties for more information). To do so, add the name of the property to the array for the configuration parameter Report_Event_Recorder_Individual_Properties.
To generate the report, set the configuration parameter Report_Event_Recorder to 1. Note that this file is modifiable; to see the list of parameters that will add new data channels to the report, see Output settings.
With this report, it is possible to customize which events are reported. You may list the specific events to record, or you may record all events EXCEPT those listed. Use the configuration parameter Report_Event_Recorder_Events to list events. If the configuration parameter Report_Event_Recorder_Ignore_Events_In_List is set to 0, then only the events listed in Report_Event_Recorder_Events will be reported. If it is set to 1, then all events EXCEPT those listed will be reported.
Configuration¶
To generate the report, set the configuration parameter Report_Event_Recorder to 1. The following table are the list of parameters in the configuration file used to control the report.
Parameter name |
Data type |
Min |
Max |
Default |
Description |
|---|---|---|---|---|---|
Report_Event_Recorder |
boolean |
0 |
1 |
0 |
Set to true (1) to enable or to false (0) to disable the ReportEventRecorder.csv output report that lists individual events in the simulation. See Event list for a list of all possible built-in events that will be recorded in the output when enabled. |
Report_Event_Recorder_Events |
array of strings |
NA |
NA |
[][-p |
The list of events to include or exclude in the ReportEventRecorder.csv output report, based on how Report_Event_Recorder_Ignore_Events_In_List is set. See Event list for a list of all possible built-in events. You can also define events in Custom_Individual_Events. The list cannot be empty. |
Report_Event_Recorder_Ignore_Events_In_List |
boolean |
0 |
1 |
0 |
If set to false (0), only the events listed in the Report_Event_Recorder_Events array will be included in the ReportEventRecorder.csv output report. If set to true (1), only the events listed in the array will be excluded, and all other events will be included. If you want to return all events from the simulation, leave the events array empty. |
Report_Event_Recorder_Individual_Properties |
array of strings |
NA |
NA |
[] |
Specifies an array of (optional) individual property keys, as defined in IndividualProperties in the demographics file, to be added as additional columns to the output report. Individual’s IP value will be added to the (key) column at the time of the event. |
Report_Event_Recorder_Start_Day |
float |
0 |
3.40282e+38 |
0 |
The day of the simulation to start collecting data. |
Report_Event_Recorder_End_Day |
float |
0 |
3.40282e+38 |
3.40282e+38 |
The day of the simulation to stop collecting data. |
Report_Event_Recorder_Node_IDs_Of_Interest |
array of integers |
0 |
2.14748e+09 |
[] |
Data will be collected for the nodes in this list. |
Report_Event_Recorder_Min_Age_Years |
float |
0 |
|
0 |
Minimum age in years of people to collect data on. |
Report_Event_Recorder_Max_Age_Years |
float |
0 |
|
|
Maximum age in years of people to collect data on. |
Report_Event_Recorder_Must_Have_IP_Key_Value |
string |
NA |
NA |
(empty string) |
A Key:Value pair that the individual must have in order to be included. Empty string means to not include IPs in the selection criteria. |
Report_Event_Recorder_Must_Have_Intervention |
string |
NA |
NA |
(empty string) |
The name of the intervention that the person must have in order to be included. Empty string means to not include interventions in the selection criteria. |
Report structure and data channel descriptions¶
The file contains the following data channels. Note that this report is used in multiple simulation types, and some data channels will be specific to that type.
Data channel |
Data type |
Description |
|---|---|---|
Time |
float |
The time of the event, in days. |
Node_ID |
integer |
The identification number of the node. |
Event_Name |
string |
The event being logged. If Report_Event_Recorder_Ignore_Events_In_List is set to 0, then the event name will be one of the ones listed under Report_Event_Recorder_Events. Otherwise, it will be the name of any other event that occurs and is not listed under Report_Event_Recorder_Events. |
Individual_ID |
integer |
The individual’s unique identifying number |
Age |
integer |
The age of the individual in units of days. Divide by 365 to obtain age in years. |
Gender |
boolean |
Identifies the individual’s gender; 0 is assigned to males, 1 is assigned to females. |
Infected |
boolean |
Describes whether the individual is infected or not; 0 when not infected, 1 for infected. |
Infectiousness |
float |
A value ranging from 0 to 1 that indicates how infectious an individual is, with 0 = not infectious and 1 = very infectious. HIV and malaria simulation types have specific definitions listed below. |
<custom channels> |
string |
If any IndividualProperties are listed under the config.json array Report_Event_Recorder_Individual_Properties, they will appear as additional columns following the Infectiousness column of the CSV file. |
Additional data channels used in HIV simulations:
Data channel |
Data type |
Description |
|---|---|---|
Year |
float |
The time of the event in units of calendar year, including fractions of years up to two decimal places. This channel replaces the Time data channel. |
HasHIV |
string |
This column is included for HIV simulations only. N if the individual is not infected, Y if the individual is infected with HIV. |
Infectiousness |
float |
The per-act probability of transmission, including intrahost factors like disease stage and ART, but excluding condoms. |
OnART |
string |
This column is included for HIV simulations only. N if the individual is not on ART, Y if the individual is on ART. |
CD4 |
float |
The current CD4 count, regardless of when CD4 testing was performed. |
WHO_Stage |
float |
The individual’s WHO stage, linearly interpolated between integer values. Round down to obtain the integer value for the WHO clinical stage. Uninfected individuals will be assigned a value of -1. |
Intervention_Status |
string |
The individual’s intervention status. |
For all sim types, in addition to the default channels listed above, it is possible to list whether an individual has been assigned IndividualProperties (which are configured in the demographics file; see NodeProperties and IndividualProperties for more information). To do so, add the name of the property to the array for the configuration parameter Report_Event_Recorder_Individual_Properties. If no individual properties are being specified, this parameter should be set to an empty list to avoid an error.
Example¶
The following is an example of a ReportEventRecorder.csv report from an HIV simulation:
Year |
Node_ID |
Event_Name |
Individual_ID |
Age |
Gender |
Infected |
Infectiousness |
HasHIV |
OnART |
CD4 |
WHO_Stage |
InterventionStatus |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
1960 |
1 |
Births |
8699 |
0 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8700 |
0 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8701 |
0 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8702 |
0 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8703 |
0 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8704 |
0 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8705 |
0 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8706 |
0 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8707 |
0 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8708 |
0 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8709 |
0 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8710 |
0 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8712 |
0 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8732 |
0 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8733 |
0 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8734 |
0 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8735 |
0 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960 |
1 |
Births |
8736 |
0 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960.08 |
1 |
Loop_Entry_InitialPopulation |
1 |
17179.7 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960.08 |
1 |
Loop_Entry_InitialPopulation |
2 |
1509.3 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960.08 |
1 |
Loop_Entry_InitialPopulation |
3 |
550.404 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960.08 |
1 |
Loop_Entry_InitialPopulation |
4 |
13136.9 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960.08 |
1 |
Loop_Entry_InitialPopulation |
5 |
2716.6 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960.08 |
1 |
Loop_Entry_InitialPopulation |
6 |
14578.1 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960.08 |
1 |
Loop_Entry_InitialPopulation |
7 |
24638.7 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960.08 |
1 |
Loop_Entry_InitialPopulation |
8 |
4697.56 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960.08 |
1 |
Loop_Entry_InitialPopulation |
9 |
2899.98 |
M |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960.08 |
1 |
Loop_Entry_InitialPopulation |
10 |
17541.3 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960.08 |
1 |
Loop_Entry_InitialPopulation |
11 |
3843.27 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |
1960.08 |
1 |
Loop_Entry_InitialPopulation |
12 |
29140.1 |
F |
0 |
0 |
N |
N |
1.00E+06 |
-1 |
None |