SurveillanceEventCoordinator
The SurveillanceEventCoordinator extends the IncidenceEventCoordinator by adding start/stop trigger events, a configurable duration, and periodic counting. It monitors for coordinator-level start events, begins counting individual, node, or coordinator events using a periodic Incidence_Counter, and responds via a Responder when counting periods complete.
The coordinator remains dormant until it receives a start trigger event from the Start_Trigger_Condition_List. Once started, it operates in a periodic count-respond cycle:
- The Incidence_Counter counts events of the type specified by Counter_Event_Type (individual, node, or coordinator) during each Counter_Period (in days). Only events matching the Trigger_Condition_List and demographic/property restrictions are counted.
- At the end of each counter period, the Responder calculates the incidence value as a raw count, percentage, or percentage of events (based on Threshold_Type).
- The responder selects the action from Action_List whose Threshold is the highest value that is still less than or equal to the calculated incidence.
- The selected action's Event_To_Broadcast event is broadcast. If Responded_Event is set, it is also broadcast as a coordinator event after the action event.
- The counter resets and begins the next period, continuing until a stop event is received or the Duration expires.
The coordinator can be stopped by an event in Stop_Trigger_Condition_List and restarted by a subsequent start trigger event. The coordinator does not expire until its Duration has elapsed.
This coordinator is typically used with other classes such as BroadcastCoordinatorEvent, TriggeredEventCoordinator, and DelayEventCoordinator.
At a glance:
- Distributed to: Nodes
- Serialized: No, it needs to be redistributed when starting from a serialized file.
Note
Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of "NA" indicate that those values are not applicable for that parameter.
EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.
JSON format does not permit comments, but you can add "dummy" parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.
The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.
| Parameter | Type | Min | Max | Default | Description |
|---|---|---|---|---|---|
| Action_List | array of json objects | NA | NA | [] | An array specifying a list of possible actions (JSON objects with parameters Threshold, Event_Type, Event_To_Broadcast) to take if a particular threshold is met. An action is taken when the specified threshold value is less than or equal to the incidence value. If there are multiple actions listed, then the action with the highest threshold value that is still less than or equal to the incidence value is selected. The list cannot be empty. See example. Located within Responder. |
| Coordinator_Name | string | NA | NA | SurveillanceEventCoordinator | The name of the event coordinator, which is useful in output reports such as ReportCoordinatorEventRecorder.csv and ReportSurveillanceEventRecorder.csv. EMOD does not ensure that this name is unique. It is up to the user. |
| Count_Events_For_Num_Timesteps | integer | 1 | 2147480000 | 1 | The number of simulation timesteps over which to count events before notifying the Responder with the accumulated count. Located within Incidence_Counter. |
| Counter_Event_Type | enum | NA | NA | INDIVIDUAL | Type of events that can be included in Trigger_Condition_List. Possible values are: INDIVIDUAL -- individual-level events from Custom_Individual_Events or built-in events NODE -- node-level events from Custom_Node_Events COORDINATOR -- coordinator-level events from Custom_Coordinator_Events Located within Incidence_Counter*. |
| Counter_Period | float | 1 | 1000 | 1 | When Counter_Type is set to PERIODIC, this is the counting period in days. At the end of each period, the accumulated count is passed to the Responder and counting restarts for the next period. Located within Incidence_Counter. |
| Counter_Type | enum | NA | NA | PERIODIC | Counter type used for surveillance of events. The counter is triggered by events in Start_Trigger_Condition_List and stops when it receives an event in Stop_Trigger_Condition_List or the listening duration expires. The only currently supported value is: PERIODIC -- Once triggered, events are counted during each period (in days) as set in Counter_Period. At the end of the period, the counter notifies Responder with accumulated data and then starts counting again. This continues until stopped or the Duration expires. For example, if Duration is 45 days, Counter_Period is 30, and the counter is triggered on day 20, it will never complete the counter period and trigger the responder. Located within Incidence_Counter*. |
| Demographic_Coverage | float | 0 | 1 | 1 | The fraction of individuals in the target demographic whose events are counted. Located within Incidence_Counter. |
| Duration | float | -1 | 3.40282e+38 | -1 | The number of days from when the coordinator was created by the campaign event. Once the number of days has passed, the coordinator will unregister for events and expire. A value of -1 (the default) keeps the coordinator running indefinitely. |
| Event_Type | enum | NA | NA | INDIVIDUAL | The type of event to be broadcast when an action is selected. Possible values are: INDIVIDUAL -- broadcast to individuals in the nodes NODE -- broadcast as a node-level event COORDINATOR -- broadcast as a coordinator-level event Located within each object in Action_List*. |
| Incidence_Counter | json object | NA | NA | NA | A JSON object specifying the conditions and parameters for counting incidence. Uses the IncidenceCounterSurveillance type which adds periodic counting to the base IncidenceCounter. Contains: Counter_Type, Counter_Period, Counter_Event_Type, Count_Events_For_Num_Timesteps, Trigger_Condition_List, Demographic_Coverage, Target_Demographic, Target_Age_Min, Target_Age_Max, Target_Gender, Target_Residents_Only, Targeting_Config, Node_Property_Restrictions, Property_Restrictions, Property_Restrictions_Within_Node. See example. |
| Node_Property_Restrictions | array of json objects | NA | NA | [] | A list of the NodeProperty key:value pairs, as defined in the demographics file, that the node in which the individual is currently located must have in order to be targeted. See IndividualProperties and NodeProperties parameters for more information. You can specify AND and OR combinations of key:value pairs with this parameter. See example. Located within Incidence_Counter. |
| Percentage_Events_To_Count | array of strings | NA | NA | [] | When Threshold_Type is set to PERCENTAGE_EVENTS, this lists the events counted for the denominator. The numerator comes from the events in Trigger_Condition_List. The event types must match the Counter_Event_Type of the counter. See example. Located within Responder. |
| Property_Restrictions | array of strings | NA | NA | [] | A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be counted. See IndividualProperties and NodeProperties parameters for more information. To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same counter. See example. Located within Incidence_Counter. |
| Property_Restrictions_Within_Node | array of json objects | NA | NA | [] | A list of JSON objects where each object has Individual Property (IP) Keys as JSON keys and IP Values as JSON values (like 'Risk' : 'HIGH'). The values in the object are AND'd together while the objects are OR'd together. An individual's IP values must meet the logic in order to be counted. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both. See example. Located within Incidence_Counter. |
| Responded_Event | string | NA | NA | "" | A coordinator event, defined in Custom_Coordinator_Events, that is broadcast if the Responder takes an action. At the completion of a counting period, if an action is selected, the action events are broadcast first and then the Responded_Event is also broadcast. This allows other event coordinators to react to the action events being broadcast. Located within Responder. |
| Responder | json object | NA | NA | NA | A JSON object specifying the actions to take when a counting period completes. Uses the ResponderSurveillance type which adds Responded_Event and Percentage_Events_To_Count to the base Responder. Contains: Threshold_Type, Action_List (with Threshold, Event_To_Broadcast, Event_Type), Responded_Event, Percentage_Events_To_Count. See example. |
| Start_Trigger_Condition_List | array of strings | NA | NA | [] | A list of coordinator events that when one is heard will start the Incidence_Counter counting events. The coordinator will keep counting and responding until it receives a stop event from Stop_Trigger_Condition_List or the Duration expires. The list cannot be empty. The events must be defined in Custom_Coordinator_Events in the simulation configuration. See example. |
| Stop_Trigger_Condition_List | array of strings | NA | NA | [] | A list of coordinator events that when one is heard will stop the Incidence_Counter from counting events. The coordinator can start counting again if it receives a new start trigger event. The coordinator does not expire until the Duration has elapsed. The list can be empty. The events must be defined in Custom_Coordinator_Events in the simulation configuration. See example. |
| Target_Age_Max | float | 0 | 9.3228e+35 | 9.3228e+35 | The age, in years, of an individual being considered must be less than or equal to this value in order to be counted. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender. Located within Incidence_Counter. |
| Target_Age_Min | float | 0 | 9.3228e+35 | 0 | The age, in years, of an individual being considered must be greater than or equal to this value in order to be counted. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender. Located within Incidence_Counter. |
| Target_Demographic | enum | NA | NA | Everyone | The target demographic group. Possible values are: Everyone ExplicitAgeRanges ExplicitAgeRangesAndGender ExplicitGender ExplicitDiseaseState Located within Incidence_Counter*. |
| Target_Gender | enum | NA | NA | All | Specifies the gender restriction for counting. Possible values are: All Male Female Located within Incidence_Counter*. |
| Target_Residents_Only | boolean | 0 | 1 | 0 | When set to true (1), only events from individuals that currently reside in their 'home' node will be counted. The 'home' node is either the one they began the simulation in or the one set by the MigrateIndividuals or MigrateFamily interventions. Located within Incidence_Counter. |
| Targeting_Config | json object | NA | NA | NA | Be more selective of individuals by using the Targeting_Config classes. See example. Located within Incidence_Counter. |
| Threshold | float | 0 | 3.40282e+38 | 0 | The COUNT, PERCENTAGE, or PERCENTAGE_EVENTS threshold value (as configured with Threshold_Type) that must be met before the action will be considered. The incidence value must be greater than or equal to this value and less than the next higher threshold in order for this action to be selected. Once selected, it broadcasts the Event_To_Broadcast event. Located within each object in Action_List. |
| Threshold_Type | enum | NA | NA | COUNT | The threshold type indicates how Responder handles the counting of events from Incidence_Counter and the thresholds in Action_List. Possible values are: COUNT -- A raw count of events. Setting the x_Base_Population configuration parameter can indirectly affect the count by changing the population. PERCENTAGE -- Counts the number of individuals that meet the restrictions and divides the total number of events by this number. Note that it is possible for an individual to emit an event that might not be counted in the denominator if their demographic restriction attributes changed between the time of the emitted event and the time the denominator was counted. PERCENTAGE_EVENTS -- Percentage_Events_To_Count lists the events counted for the denominator, which is then used with Trigger_Condition_List for the numerator. Located within Responder*. |
| Trigger_Condition_List | array of strings | NA | NA | [] | The list of events to count. The list cannot be empty. The type of events in the list is determined by Counter_Event_Type. Depending on the type, events must be built-in (see Event list) or defined in one of the following configuration parameters: Custom_Individual_Events, Custom_Node_Events, or Custom_Coordinator_Events. See example. Located within Incidence_Counter. |
{
"Use_Defaults": 1,
"Events": [
{
"comment": "Broadcast Event to start Surveillance",
"class": "CampaignEvent",
"Start_Day": 2,
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Event_Coordinator_Config": {
"class": "BroadcastCoordinatorEvent",
"Coordinator_Name": "Coordinator_1",
"Broadcast_Event": "Start_ACF"
}
},
{
"comment": "Triggered by Broadcast_Event, stops itself by broadcasting Start_SIA_X Event",
"class": "CampaignEvent",
"Start_Day": 1,
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Event_Coordinator_Config": {
"class": "SurveillanceEventCoordinator",
"Coordinator_Name": "ACF_Counter",
"Duration": 30,
"Start_Trigger_Condition_List": [
"Start_ACF"
],
"Stop_Trigger_Condition_List": [
"Start_SIA_2",
"Start_SIA_4"
],
"Incidence_Counter": {
"Counter_Type": "PERIODIC",
"Counter_Period": 14,
"Counter_Event_Type": "NODE",
"Trigger_Condition_List": [
"Node_Event_1",
"Node_Event_2"
],
"Target_Demographic": "Everyone",
"Demographic_Coverage": 1.0
},
"Responder": {
"Responded_Event": "Respond_To_Surveillance",
"Threshold_Type": "COUNT",
"Action_List": [
{
"Threshold": 2,
"Event_Type": "COORDINATOR",
"Event_To_Broadcast": "Start_SIA_4"
},
{
"Threshold": 5,
"Event_Type": "COORDINATOR",
"Event_To_Broadcast": "Start_SIA_2"
}
]
}
}
},
{
"class": "CampaignEvent",
"Start_Day": 3,
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Event_Coordinator_Config": {
"class": "StandardInterventionDistributionEventCoordinator",
"Intervention_Config": {
"class": "BroadcastNodeEvent",
"Cost_To_Consumer": 25,
"Broadcast_Event": "Node_Event_1"
}
}
},
{
"class": "CampaignEvent",
"Start_Day": 3,
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Event_Coordinator_Config": {
"class": "StandardInterventionDistributionEventCoordinator",
"Intervention_Config": {
"class": "BroadcastNodeEvent",
"Cost_To_Consumer": 25,
"Broadcast_Event": "Node_Event_1"
}
}
},
{
"class": "CampaignEvent",
"Start_Day": 4,
"Nodeset_Config": {
"class": "NodeSetAll"
},
"Event_Coordinator_Config": {
"class": "StandardInterventionDistributionEventCoordinator",
"Intervention_Config": {
"class": "BroadcastNodeEvent",
"Cost_To_Consumer": 25,
"Broadcast_Event": "Node_Event_2"
}
}
}
]
}