ReportEventRecorder

The health events and interventions report (ReportEventRecorder.csv) provides information on each individual’s demographics and health status at the time of an event. Additionally, it is possible to see the value of specific IndividualProperties, as assigned in the demographics file (see NodeProperties and IndividualProperties for more information).

This report is highly customizable; see the Configuration section, below, for details and instructions. Disease-specific information and examples are provided at the end of page.

Configuration

To generate this report, the following parameters must be configured in the config.json file (applies to all simulation types):

Parameter name

Data type

Min

Max

Default

Description

Report_Event_Recorder

boolean

0

1

0

Set to 1 to generate the report.

Report_Event_Recorder_Events

array of strings

NA

NA

[]

The list of events to include or exclude in the 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. Custom_Individual_Events may also be included. Warning: If the list is empty and Report_Event_Recorder_Ignore_Events_In_List is set to 0, no events will be returned.

Report_Event_Recorder_Ignore_Events_In_List

boolean

0

1

0

If set to false (0), only the events listed in Report_Event_Recorder_Events will be included in the output report. If set to true (1), only the events listed in Report_Event_Recorder_Events will be excluded, and all other events will be included. To return all events from the simulation, set this value to 1 and leave the the Report_Event_Recorder_Events array empty.

Report_Event_Recorder_Individual_Properties

array of strings

NA

NA

[]

An array of optional individual property (IP) keys to be added to the report. One column will be added for each IP Key listed, indicating the individual’s value for that IP Key at the time of the event. See Individual and node properties for details on setting individual properties.

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. Leave the array empty (default value) to collect data on all nodes.

Report_Event_Recorder_PropertyChange_IP_Key_Of_Interest

string

NA

NA

""

If the string is not empty, then the recorder will add the PropertyChange event to the list of events that the report is listening to. However, it will only record the events where the property changed the value of the given key.

Report_Event_Recorder_Min_Age_Years

float

0

9.3228e+35

0

Minimum age in years of people to collect data on.

Report_Event_Recorder_Max_Age_Years

float

0

9.3228e+35

9.3228e+35

Maximum age in years of people to collect data on.

Report_Event_Recorder_Must_Have_IP_Key_Value

string

NA

NA

""

An individual property (IP) Key:Value pair that an individual must have in order to be included in the report. Leave the string empty (default value) to not include IPs in the selection criteria. See Individual and node properties for more information.

Report_Event_Recorder_Must_Have_Intervention

string

NA

NA

""

The name of the intervention that the individual must have in order to be included in the report. Leave the string empty (default value) to not include interventions in the selection criteria. See Individual-level interventions for more information.

 
{
    "Report_Event_Recorder": 1,
    "Report_Event_Recorder_Events": [],
    "Report_Event_Recorder_Ignore_Events_In_List": 1,
    "Report_Event_Recorder_Individual_Properties": ["Risk"],
    "Report_Event_Recorder_Start_Day": 1,
    "Report_Event_Recorder_End_Day": 300,
    "Report_Event_Recorder_Node_IDs_Of_Interest": [ 1, 2, 3 ],
    "Report_Event_Recorder_PropertyChange_IP_Key_Of_Interest": "",
    "Report_Event_Recorder_Min_Age_Years": 20,
    "Report_Event_Recorder_Max_Age_Years": 60,
    "Report_Event_Recorder_Must_Have_IP_Key_Value": "Risk:HIGH",
    "Report_Event_Recorder_Must_Have_Intervention": "",
}

Output file data

The report contains the following data channels for all simulation types.

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

character

The gender of the individual: “M” for male, or “F” for female.

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.

<IP Key>

string

An additional column will be added to the report for each IP Key listed in Report_Event_Recorder_Individual_Properties. The values shown in each column will be the value for the indicated key, for that individual, at the time of the event.

HIV additional channels

When running HIV simulations, the report contains the following additional channels.

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.

Infectiousness

float

The probability of HIV transmission per coital act, including intrahost factors like disease stage and ART, but excluding condoms. (Channel is included in all simulations, but definition varies by disease.)

HasHIV

character

Indicates whether or not the individual is infected with HIV: “N” if not infected, “Y” if infected.

OnART

character

Indicates whether or not the individual is on ART: “N” if not on ART, “Y” if the individual is on ART.

CD4

float

The individual’s 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.

HIV_Stage

enum

Indicates the individual’s HIV stage. Possible values are: NOT_INFECTED, ACUTE, LATENT, AIDS, ON_ART.

InterventionStatus

string

The value of the individual’s InterventionStatus individual property at the time of the event. If InterventionStatus has not been configured, then the value will be “None.”

Example

The following is an example of a ReportEventRecorder.csv report from an HIV simulation:

Time

Year

Node_ID

Event_Name

Individual_ID

Age

Gender

Infected

Infectiousness

HasHIV

OnART

CD4

WHO_Stage

HIV_Stage

InterventionStatus

1

1995

1

NewlySymptomatic

119

1114.49

M

1

0.026

Y

N

538.063

1.004

ACUTE

None

1

1995

1

TestingOnSymptomatic1

119

1114.49

M

1

0.026

Y

N

538.063

1.004

ACUTE

TestingOnSymptomatic

1

1995

1

ARTStaging0

119

1114.49

M

1

0.026

Y

N

538.063

1.004

ACUTE

TestingOnSymptomatic

1

1995

1

NewlySymptomatic

169

16666.3

F

1

0.026

Y

N

539.601

1.00142

ACUTE

None

1

1995

1

TestingOnSymptomatic1

169

16666.3

F

1

0.026

Y

N

539.601

1.00142

ACUTE

TestingOnSymptomatic

1

1995

1

ARTStaging0

169

16666.3

F

1

0.026

Y

N

539.601

1.00142

ACUTE

TestingOnSymptomatic

2

1995.01

1

LinkingToART0

53

322.219

F

1

0.026

Y

N

527.811

1.03261

ACUTE

ARTStaging

2

1995.01

1

LinkingToART0

89

2525.18

F

1

0.026

Y

N

535.089

2.082

ACUTE

ARTStaging

2

1995.01

1

LinkingToART0

95

2329.52

M

1

0.026

Y

N

469.703

3.00982

ACUTE

ARTStaging

9

1995.02

1

LinkingToPreART0

2

3930.41

F

1

0.026

Y

N

510.138

1.05865

ACUTE

ARTStaging

9

1995.02

1

LinkingToPreART0

6

3333.92

F

1

0.026

Y

N

519.006

1.17656

ACUTE

ARTStaging

9

1995.02

1

LinkingToPreART0

21

1608.53

F

1

0.026

Y

N

476.802

1.11907

ACUTE

ARTStaging

15

1995.04

1

SixWeeksOld

40

42.2201

M

0

0

N

N

1.00E+06

-1

NOT_INFECTED

None

16

1995.04

1

OnPreART0

169

16681.3

F

1

0.026

Y

N

525.459

1.02264

ACUTE

LinkingToPreART

66

1995.18

1

TwelveWeeksPregnant

18

8926.42

F

1

0.026

Y

N

527.546

1.11365

ACUTE

None

66

1995.18

1

TestingOnANC1

18

8926.42

F

1

0.026

Y

N

527.546

1.11365

ACUTE

None

72

1995.2

1

ARTStaging0

18

8932.42

F

1

0.026

Y

N

526.372

1.12398

ACUTE

TestingOnANC

80

1995.22

1

LinkingToPreART0

18

8940.42

F

1

0.026

Y

N

524.808

1.13776

ACUTE

ARTStaging

81

1995.22

1

TwelveWeeksPregnant

125

9696.05

F

1

0.026

Y

N

511.301

1.12313

ACUTE

None

81

1995.22

1

TestingOnANC1

125

9696.05

F

1

0.026

Y

N

511.301

1.12313

ACUTE

None

87

1995.24

1

OnPreART0

18

8947.42

F

1

0.026

Y

N

523.442

1.14981

ACUTE

LinkingToPreART

92

1995.25

1

TwelveWeeksPregnant

30

6603.43

F

0

0

N

N

1.00E+06

-1

NOT_INFECTED

None

92

1995.25

1

TestingOnANC1

30

6603.43

F

0

0

N

N

1.00E+06

-1

NOT_INFECTED

None

96

1995.26

1

NewlySymptomatic

117

20214.4

M

1

0.026

Y

N

482.367

1.29881

LATENT

None

96

1995.26

1

TestingOnSymptomatic1

117

20214.4

M

1

0.026

Y

N

482.367

1.29881

LATENT

TestingOnSymptomatic

96

1995.26

1

ARTStaging0

117

20214.4

M

1

0.026

Y

N

482.367

1.29881

LATENT

TestingOnSymptomatic

104

1995.28

1

LinkingToPreART0

117

20222.4

M

1

0.026

Y

N

477.668

1.32371

LATENT

ARTStaging