IncidenceEventCoordinator

The IncidenceEventCoordinator monitors for individual-level events within a simulation and responds by broadcasting events when configurable thresholds are met. It does not distribute interventions directly; instead, it counts specified events using an Incidence_Counter and evaluates the accumulated count or percentage against thresholds defined in a Responder. The responder then broadcasts the appropriate event, which can trigger other campaign events or event coordinators.

The coordinator operates in a count-respond cycle:

1. The Incidence_Counter listens for individual events specified in Trigger_Condition_List and counts them over a configurable number of timesteps (Count_Events_For_Num_Timesteps). Only events from individuals matching the demographic and property restrictions are counted.
2. When the counting period ends, the Responder calculates the incidence value as a raw count or percentage (based on Threshold_Type).
3. 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.
4. The selected action's Event_To_Broadcast event is broadcast as an individual, node, or coordinator event (based on Event_Type).
5. If configured with repetitions, the cycle repeats after Timesteps_Between_Repetitions.

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 the number of incidents counted. If there are multiple actions listed, then the action with the highest threshold value, that is also less than the number of incidents counted, is selected. The list cannot be empty. See example.
Coordinator_Name	string	NA	NA	""	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.
Demographic_Coverage	float	0	1	1	The fraction of individuals in the target demographic whose events are counted. Located within Incidence_Counter.
Event_To_Broadcast	string	NA	NA	""	The action event to broadcast when the specified Threshold is met. At least one action must define an Event_To_Broadcast. Can be a built-in event (see Event list) or a custom event defined in Custom_Individual_Events, Custom_Node_Events, or Custom_Coordinator_Events depending on Event_Type. Located within each object in Action_List.
Event_Type	enum	NA	NA	INDIVIDUAL	The type of event to be broadcast. 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 that must be met for an incidence to be counted. Contains the following parameters: Count_Events_For_Num_Timesteps, Demographic_Coverage, Trigger_Condition_List, Node_Property_Restrictions, Property_Restrictions, Property_Restrictions_Within_Node, Target_Demographic, Target_Age_Min, Target_Age_Max, Target_Gender, Target_Residents_Only, Targeting_Config. 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 for the intervention. 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.
Number_Repetitions	integer	-1	10000	1	The number of times the count-respond cycle repeats, used with Timesteps_Between_Repetitions. A value of -1 implies an infinite number of repetitions.
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 by the Incidence_Counter. 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.
Responder	json object	NA	NA	NA	A JSON object specifying the actions to take when the counting period completes. Contains the following parameters: Threshold_Type, Action_List (which in turn contains Threshold, Event_To_Broadcast, Event_Type). 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 or PERCENTAGE threshold value that must be met before the action will be considered. The sampled value must be greater than or equal to this value and less than the action whose threshold is greater in order for the action to be selected. Once selected, it will broadcast 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 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. Located within Responder.
Timesteps_Between_Repetitions	integer	-1	10000	-1	The number of time steps (not days) between repetitions. If Simulation_Timestep is set to 30 days and Timesteps_Between_Repetitions is set to 4, then there will be 120 days between repetitions. A value of -1 means the next repetition starts immediately after the previous one completes.
Trigger_Condition_List	array of strings	NA	NA	[]	A list of individual events that when broadcast by an individual will be counted by the Incidence_Counter if the individual is in the targeted group. The events can be built-in events (see Event list for possible events) or custom events defined in Custom_Individual_Events in the simulation configuration file. See example. Located within Incidence_Counter.

{
    "Use_Defaults": 1,
    "Events": [
        {
            "class": "CampaignEvent",
            "Start_Day": 1,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "IncidenceEventCoordinator",
                "Coordinator_Name": "MDA_Trigger",
                "Number_Repetitions": -1,
                "Timesteps_Between_Repetitions": 30,
                "Incidence_Counter": {
                    "Count_Events_For_Num_Timesteps": 7,
                    "Demographic_Coverage": 1.0,
                    "Target_Demographic": "Everyone",
                    "Trigger_Condition_List": [
                        "NewClinicalCase"
                    ]
                },
                "Responder": {
                    "Threshold_Type": "COUNT",
                    "Action_List": [
                        {
                            "Threshold": 0,
                            "Event_To_Broadcast": "NoResponse",
                            "Event_Type": "COORDINATOR"
                        },
                        {
                            "Threshold": 50,
                            "Event_To_Broadcast": "MDA_Campaign_Start",
                            "Event_Type": "COORDINATOR"
                        }
                    ]
                }
            }
        }
    ]
}