emodpy.utils.targeting_config module#

The following classes can be used to enhance the selection of people when distributing interventions. Most event coordinators and node-level interventions that distribute interventions to people have a parameter called Targeting_Config. This allows you to not only target individuals based on their gender, age, and IndividualProperties (See NodeProperties and IndividualProperties parameters for more information), but also on things such as whether or not they have a particular intervention or are in a relationship.

Below is the JSON for a simple example where we want to distribute a vaccine to 20% of the people that do not already have the vaccine on the 100th day of the simulation.

>>> {
>>>     "class": "CampaignEvent",
>>>     "Start_Day": 100,
>>>     "Nodeset_Config": {
>>>         "class": "NodeSetAll"
>>>     },
>>>     "Event_Coordinator_Config": {
>>>         "class": "StandardInterventionDistributionEventCoordinator",
>>>         "Target_Demographic": "Everyone",
>>>         "Demographic_Coverage": 0.2,
>>>         "Targeting_Config": {
>>>             "class": "HasIntervention",
>>>             "Is_Equal_To": 0,
>>>             "Intervention_Name": "MyVaccine"
>>>         },
>>>         "Intervention_Config": {
>>>             "class": "SimpleVaccine",
>>>             "Intervention_Name" : "MyVaccine",
>>>             "Cost_To_Consumer": 1,
>>>             "Vaccine_Take": 1,
>>>             "Vaccine_Type": "AcquisitionBlocking",
>>>             "Waning_Config": {
>>>                 "class": "WaningEffectConstant",
>>>                 "Initial_Effect" : 1.0
>>>             }
>>>         }
>>>     }
>>> }

Below is a slightly more complicated example where we want to distribute a diagnostic to people that are either high risk or have not been vaccinated.

>>> {
>>>     "class": "CampaignEvent",
>>>     "Start_Day": 100,
>>>     "Nodeset_Config": {
>>>         "class": "NodeSetAll"
>>>     },
>>>     "Event_Coordinator_Config": {
>>>         "class": "StandardInterventionDistributionEventCoordinator",
>>>         "Target_Demographic": "Everyone",
>>>         "Demographic_Coverage": 0.2,
>>>         "Targeting_Config": {
>>>             "class" : "TargetingLogic",
>>>             "Logic" : [
>>>                 [
>>>                     {
>>>                         "class": "HasIntervention",
>>>                         "Is_Equal_To": 0,
>>>                         "Intervention_Name": "MyVaccine"
>>>                     }
>>>                 ],
>>>                 [
>>>                     {
>>>                         "class": "HasIP",
>>>                         "Is_Equal_To": 1,
>>>                         "IP_Key_Value": "Risk:HIGH"
>>>                     }
>>>                 ]
>>>             ]
>>>         },
>>>         "Intervention_Config": {
>>>             "class": "SimpleDiagnostic",
>>>             "Treatment_Fraction": 1.0,
>>>             "Base_Sensitivity": 1.0,
>>>             "Base_Specificity": 1.0,
>>>             "Event_Or_Config": "Event",
>>>             "Positive_Diagnosis_Event": "TestedPositive"
>>>         }
>>>     }
>>> }

The classes of emodpy are intended to make it easier for users to create complex logic and reduce the burden of trying to create this complex logic in JSON. Below is the python configuration logic for the two examples above:

>>> # Example 1: Does not have MyVaccine
>>> targeting_config = ~HasIntervention( intervention_name="MyVaccine" )
>>>
>>> # Example 2: Does not have MyVaccine OR is high risk
>>> targeting_config = ~HasIntervention( intervention_name="MyVaccine" ) | HasIP( ip_key_value="Risk:HIGH" )

Notice that this logic uses the bitwise operators instead of the logical operators. Python does not allow you to override the logical operators so the bitwise operators were the next best thing to allow simple notation. The bitwise operators are:

‘~’ - use instead of “not” to logically invert the logical check

‘&’ - use instead of “and” to logically AND two logical checks

‘|’ - use instead of “or” to logically OR two logical checks

‘^’ - XOR - NOT SUPPORTED

‘<<’ - Left Shift - NOT SUPPORTED

‘>>’ - Right Shift - NOT SUPPORTED

The order of operations for bitwise operators is the same as for logical operators. For the operators we support, the following order of operations is followed:

Parentheses

‘~’ - NOT

‘&’ - AND

‘|’ - OR

Please note that the bitwise operations should not change objects directly. You expect them to return a new object with the operation. For example, if you have A_prime = ~A, then you expect A_prime to be the inverse of A but you don’t expect A to have changed.

class emodpy.utils.targeting_config.AbstractTargetingConfig[source]#

Bases: ABC

The AbstractTargetingConfig is defines the interface that all targeting config classes must implement. This class is needed to tie the TargetingLogic and BaseTargetingConfig classes together.

Parameters:

class_name – The subclass is responsible for setting the name of the EMOD class. This name does not need to be the same as the python class, but it must match what is used in EMOD.
is_equal_to – This is a parameter in all of EMOD’s Targeting_Config classes. The check performed by the class is compared with the value of this parameter. For example, if using HasIP with ip_key_value = “Risk:HIGH” and is_equal_to = 0, individuals who do NOT have Risk = HIGH will be selected. If is_equal_to = 1, then individuals who DO have Risk = HIGH will be selected.

to_schema_dict(campaign)[source]#

Create the ReadOnlyDict object representation of this Targeting_Config logic. This is the dictionary used to generate the JSON for EMOD.

Parameters:: campaign – The campaign module that has the path to the schema
Returns:: A ReadOnlyDict object created by schema_to_class

to_simple_dict(campaign)[source]#

Return a plain/simple dictionary of the expected JSON for EMOD. The main purpose of this is for validation in testing. We need the ability to see that the logic written in python is translated to the JSON correctly.

Parameters:: campaign – The campaign module that has the path to the schema
Returns:: A simple dictionary containing the data for EMOD.

class emodpy.utils.targeting_config.BaseTargetingConfig[source]#

Bases: AbstractTargetingConfig

The BaseTargetingConfig class should used as the base class for all of the Targeting_Config classes. The main job of the subclasses is to maintain the extra data needed by the class in EMOD to perform the check. For example, HasIP needs to know the IP key:value so that in EMOD the class can check if the individual has the given IP. HasIP is responsible for making sure it is translated in the EMOD configuration.

class emodpy.utils.targeting_config.HasIP(ip_key_value)[source]#

Bases: BaseTargetingConfig

This determines if the person has a particular value of a particular IndividualProperties (IP). This is especially needed when determining if a partner has a particular IP (see emodpy-hiv.utils.targeting_config.HasRelationship).

ip_key_value: An IndividualProperties Key:Value pair where the key/property name and one of its: values is separated by a colon (‘:’). This cannot be an empty string.

to_schema_dict(campaign)[source]#

Create the ReadOnlyDict object representation of this Targeting_Config logic. This is the dictionary used to generate the JSON for EMOD.

Parameters:: campaign – The campaign module that has the path to the schema
Returns:: A ReadOnlyDict object created by schema_to_class

class emodpy.utils.targeting_config.HasIntervention(intervention_name)[source]#

Bases: BaseTargetingConfig

This check determines whether or not the individual has an intervention with the given name. This will only work for interventions that persist like SimpleVaccine and DelayedIntervention. It will not work for interventions like BroadcastEvent since it does not persist.

intervention_name: The name of the intervention the person should have. This cannot be an empty: string but should be either the name of the intervention class or the name given to the intervention of interest. EMOD does not verify that this name exists or is used in your campaign.

to_schema_dict(campaign)[source]#

Create the ReadOnlyDict object representation of this Targeting_Config logic. This is the dictionary used to generate the JSON for EMOD.

Parameters:: campaign – The campaign module that has the path to the schema
Returns:: A ReadOnlyDict object created by schema_to_class

class emodpy.utils.targeting_config.IsPregnant[source]#

Bases: BaseTargetingConfig

Select the individual based on whether or not they are pregnant.