NChooserEventCoordinatorHIV#

The NChooserEventCoordinatorHIV coordinator class distributes an individual-level intervention to exactly N people of a targeted demographic in HIV simulations. This contrasts with other event coordinators that distribute an intervention to a percentage of the population, not to an exact count. This event coordinator is similar to the NChooserEventCoordinator for other simulation types, but replaces start and end days with start and end years and includes HIV-specific restrictions that individuals must have in order to qualify for the intervention.

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

Data type

Minimum

Maximum

Default

Description

Example

Age_Ranges_Years

array of json objects

NA

NA

NA

A list of age ranges that individuals must be in to qualify for an intervention. Each age range is a JSON object with a minimum and a maximum property. An individual is considered in range if their age is greater than or equal to the minimum age and less than the maximum age, in floating point years of age. It must have the same number of objects as Num_Targeted_XXX has elements.

{
  "Age_Ranges_Years": [
    {
      "Min": 10,
      "Max": 19
    },
    {
      "Min": 30,
      "Max": 39
    },
    {
      "Min": 50,
      "Max": 59
    }
  ],
  "Num_Targeted_Males": [
    600000,
    400000,
    200000
  ],
  "Num_Targeted_Females": [
    500000,
    300000,
    100000
  ]
}

Distributions

array of json objects

NA

NA

[]

The ordered list of elements defining when, to whom, and how many interventions to distribute.

{
  "Distributions": [
    {
      "Start_Year": 1981,
      "End_Year": 1993.5,
      "Property_Restrictions_Within_Node": [],
      "Age_Ranges_Years": [
        {
          "Min": 10,
          "Max": 19
        },
        {
          "Min": 40,
          "Max": 49
        }
      ],
      "Num_Targeted": [
        100,
        300
      ]
    }
  ]
}

End_Year

float

1900

2200

2200

The year to stop distributing the intervention. Defines the time period to distribute the intervention along with Start_Year. The intervention is evenly distributed between each time step in the time period.

{
  "Start_Year": 1963,
  "End_Year": 1963.5
}

Intervention_Config

json object

NA

NA

NA

The nested JSON of the actual intervention to be distributed by this event coordinator.

{
  "Intervention_Config": {
    "class": "OutbreakIndividual",
    "Antigen": 0,
    "Genome": 0,
    "Outbreak_Source": "PrevalenceIncrease",
    "Incubation_Period_Override": 1
  }
}

Num_Targeted

array of integers

0

2147480000

0

The number of individuals to target with the intervention. Note that this value will be scaled up by the population scaling factor equal to Base_Population_Scale_Factor. If using this parameter, Num_Targeted_Males and Num_Targeted_Females must be empty.

{
  "Age_Ranges_Years": [
    {
      "Min": 10,
      "Max": 19
    },
    {
      "Min": 40,
      "Max": 49
    }
  ],
  "Num_Targeted": [
    100,
    300
  ]
}

Num_Targeted_Females

array of integers

0

2147480000

0

The number of female individuals to distribute interventions to during this time period. If using this parameter with Num_Targeted_Males to target specific genders, they both must be the same length, and Num_Targeted must be empty.

{
  "Age_Ranges_Years": [
    {
      "Min": 10,
      "Max": 19
    },
    {
      "Min": 30,
      "Max": 39
    },
    {
      "Min": 50,
      "Max": 59
    }
  ],
  "Num_Targeted_Males": [
    600000,
    400000,
    200000
  ],
  "Num_Targeted_Females": [
    500000,
    300000,
    100000
  ]
}

Num_Targeted_Males

array of integers

0

2147480000

0

The number of male individuals to distribute interventions to during this time period. If using this parameter with Num_Targeted_Females to target specific genders, they both must be the same length, and Num_Targeted must be empty.

{
  "Age_Ranges_Years": [
    {
      "Min": 10,
      "Max": 19
    },
    {
      "Min": 30,
      "Max": 39
    },
    {
      "Min": 50,
      "Max": 59
    }
  ],
  "Num_Targeted_Males": [
    600000,
    400000,
    200000
  ],
  "Num_Targeted_Females": [
    500000,
    300000,
    100000
  ]
}

Property_Restrictions_Within_Node

array of json objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
  "Property_Restrictions_Within_Node": [
    {
      "Risk": "HIGH",
      "Geographic": "URBAN"
    },
    {
      "Risk": "MEDIUM",
      "Geographic": "URBAN"
    }
  ]
}

Start_Year

float

1900

2200

1900

The year to start distributing the intervention. Defines the time period to distribute the intervention along with End_Year. The intervention is evenly distributed between each time step in the time period. To have the intervention applied other than at the beginning of the year, you must enter a decimal value after the year. For example, 2010.5 would have the intervention applied halfway through the year 2010.

{
  "Start_Year": 1963,
  "End_Year": 1963.5
}

Target_Disease_State

array of strings

NA

NA

NA

A two-dimensional array of particular disease states. To qualify for the intervention, an individual must have only one of the targeted disease states. An individual must have all of the disease states in the inner array. Possible values are:

  • HIV_Positive

  • HIV_Negative

  • Tested_Positive

  • Tested_Negative

  • Male_Circumcision_Positive

  • Male_Circumcision_Negative

  • Has_Intervention

  • Not_have_Intervention

{
  "Target_Disease_State": [
    [
      "HIV_Negative",
      "Not_Have_Intervention"
    ]
  ],
  "Target_Disease_State_Has_Intervention_Name": "Vaccine48"
}

Target_Disease_State_Has_Intervention_Name

string

NA

NA

NA

The name of the intervention to look for in an individual when using Has_Intervention or Not_have_Intervention in Target_Disease_State.

{
  "Target_Disease_State": [
    [
      "HIV_Negative",
      "Not_Have_Intervention"
    ]
  ],
  "Target_Disease_State_Has_Intervention_Name": "Vaccine48"
}
{
    "Use_Defaults": 1,
    "Events": [{
        "class": "CampaignEvent",
        "Start_Day": 1,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "NChooserEventCoordinatorHIV",
            "Distributions": [{
                    "Start_Year": 1961,
                    "End_Year": 1961.25,
                    "Target_Disease_State": [
                        ["HIV_Negative", "Not_Have_Intervention"]
                    ],
                    "Target_Disease_State_Has_Intervention_Name": "Vaccine48",
                    "Property_Restrictions_Within_Node": [],
                    "Age_Ranges_Years": [{
                        "Min": 10,
                        "Max": 19
                    }, {
                        "Min": 40,
                        "Max": 49
                    }],
                    "Num_Targeted": [600000, 300000]
                },
                {
                    "Start_Year": 1963,
                    "End_Year": 1963.5,
                    "Target_Disease_State": [
                        ["HIV_Negative", "Not_Have_Intervention"]
                    ],
                    "Target_Disease_State_Has_Intervention_Name": "Vaccine48",
                    "Property_Restrictions_Within_Node": [],
                    "Age_Ranges_Years": [{
                        "Min": 20,
                        "Max": 29
                    }, {
                        "Min": 50,
                        "Max": 59
                    }],
                    "Num_Targeted_Males": [400000, 200000],
                    "Num_Targeted_Females": [300000, 100000]
                },
                {
                    "Start_Year": 1965,
                    "End_Year": 1965.25,
                    "Target_Disease_State": [
                        ["HIV_Negative", "Not_Have_Intervention"]
                    ],
                    "Target_Disease_State_Has_Intervention_Name": "Vaccine48",
                    "Property_Restrictions_Within_Node": [],
                    "Age_Ranges_Years": [{
                        "Min": 10,
                        "Max": 19
                    }, {
                        "Min": 30,
                        "Max": 39
                    }, {
                        "Min": 50,
                        "Max": 59
                    }],
                    "Num_Targeted_Males": [600000, 400000, 200000],
                    "Num_Targeted_Females": [500000, 300000, 100000]
                }
            ],
            "Intervention_Config": {
                "class": "ControlledVaccine",
                "Intervention_Name": "Vaccine48",
                "Vaccine_Type": "AcquisitionBlocking",
                "Vaccine_Take": 1.0,
                "Waning_Config": {
                    "class": "WaningEffectMapLinear",
                    "Initial_Effect": 1.0,
                    "Expire_At_Durability_Map_End": 1,
                    "Durability_Map": {
                        "Times": [0, 120, 240, 360],
                        "Values": [0.7, 0.8, 1.0, 0.0]
                    }
                },
                "Distributed_Event_Trigger": "Vaccinated",
                "Expired_Event_Trigger": "VaccineExpired",
                "Duration_To_Wait_Before_Revaccination": 240,
                "Cost_To_Consumer": 10
            }
        }
    }]
}