emodpy_hiv.utils.targeting_config module#

class emodpy_hiv.utils.targeting_config.AbstractTargetingConfig#

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_hiv.utils.targeting_config.BaseTargetingConfig#

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_hiv.utils.targeting_config.HasIP(ip_key_value)#

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_hiv.utils.targeting_config.HasIntervention(intervention_name)#

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_hiv.utils.targeting_config.IsPregnant#

Bases: BaseTargetingConfig

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

class emodpy_hiv.utils.targeting_config.YesNoNa(value)[source]#

Bases: Enum

This enum is used in the Targeting_Config logic to indicate if a particular attribute should be yes, no, or na (not applicable/don’t consider)

YES = 'YES'#
NO = 'NO'#
NA = 'NA'#
class emodpy_hiv.utils.targeting_config.MoreOrLess(value)[source]#

Bases: Enum

This enum is used in Targeting_Config logic to indicate if the check should be strictly less than, ‘<’, or strictly greater than, ‘>’. These are used when checking for the number of partners, months, etc.

LESS = 'LESS'#
MORE = 'MORE'#
class emodpy_hiv.utils.targeting_config.OfRelationshipType(value)[source]#

Bases: Enum

This enum is used in the Targeting_Config logic to indicate if the check should consider specific relationship types or not. If the user selects a specific type, then the rest of the checks will only be for those types of relationships. If the user selects ‘NA’, then relationships of all types will be considered.

NA = 'NA'#
TRANSITORY = 'TRANSITORY'#
INFORMAL = 'INFORMAL'#
MARITAL = 'MARITAL'#
COMMERCIAL = 'COMMERCIAL'#
class emodpy_hiv.utils.targeting_config.NumMonthsType(value)[source]#

Bases: Enum

This enum is used in the Targeting_Config logic to indicate the duration range to check how many partners a person has. These ranges are fixed in EMOD and the user cannot indicate a random range.

THREE_MONTHS = 'THREE_MONTHS'#
SIX_MONTHS = 'SIX_MONTHS'#
NINE_MONTHS = 'NINE_MONTHS'#
TWELVE_MONTHS = 'TWELVE_MONTHS'#
class emodpy_hiv.utils.targeting_config.RecentlyType(value)[source]#

Bases: Enum

This enum is used in the Targeting_Config logic to indicate if we only want to consider people who have a relationship that just started or just ended. This means we are interested in relationships that started or stopped during the current time step.

NA = 'NA'#
STARTED = 'STARTED'#
ENDED = 'ENDED'#
class emodpy_hiv.utils.targeting_config.RelationshipTerminationReasonType(value)[source]#

Bases: Enum

This enum is used in the Targeting_Config logic to indicate if we are interested in a person because of WHY a relationship recently ended. For example, if a person BROKE_UP and has not other partners, we might want them to stop using PrEP.

NA = 'NA'#

The relationship has not been terminated.

BROKE_UP = 'BROKEUP'#

The relationship ended due to the duration settings.

SELF_MIGRATING = 'SELF_MIGRATING'#

One of the partners in the relationship has decided to migrate and so the relationship is terminated. Note: The user can control what happens to a relationship when there is migration; it does not have to terminate.

PARTNER_DIED = 'PARTNER_DIED'#

One of the partners died so the relationship was terminated.

PARTNER_TERMINATED = 'PARTNER_TERMINATED'#

This happens when the couple is separated due to migration and one of the partners decides to terminate the relationship.

PARTNER_MIGRATING = 'PARTNER_MIGRATING'#

The relationship is being terminated because one of the partners has another partner that is migrating. For example, a married couple is moving because the wife got a new job. The husband must terminate his other relationships with “PARTNER_MIGRATING”.

class emodpy_hiv.utils.targeting_config.IsCircumcised[source]#

Bases: BaseTargetingConfig

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

class emodpy_hiv.utils.targeting_config.IsHivPositive(and_has_ever_been_tested: YesNoNa = YesNoNa.NA, and_has_ever_tested_positive: YesNoNa = YesNoNa.NA, and_has_received_positive_results: YesNoNa = YesNoNa.NA)[source]#

Bases: BaseTargetingConfig

Select the individual based on whether or not they have HIV. The “and_has_XXX” parameters extend this by being and’d with the check on whether or not the person has HIV. For example, if you want to select people that are:

  • HIV negative

  • AND have been tested

  • AND have never tested positive

you will create the following:

>>> targeting_config = ~IsHivPositive( and_has_ever_been_tested=YesNoNa.YES,
>>>                                    and_has_ever_tested_positive=YesNoNa.NO )

Notice that if the person being considered was HIV positive, the rest of the checks would not matter because the first check was false.

Also notice that when you invert IsHivPositive, you are only changing the whether or not you are looking for infected people. It does not impact the “and_has_XXX” checks.

Parameters:

  • and_has_ever_been_tested – If the user sets this Enum to ‘YES’, then the individual’s true infection status must equal to the inversion status and the person must have been tested at least once. Notice that this only tells if the has been tested, NOT that they tested positive. If set to ‘NA’ (default), then do not include this as part of the check.

  • and_has_ever_tested_positive – If the user sets this Enum to ‘YES’, then the individual’s true infection status must equal to the inversion status and the person must have tested POSITIVE at least once. Notice that this is different than just having been tested. However, it does not say the person received the results. If set to ‘NA’ (default), then do not include this as part of the check.

  • and_has_received_positive_results – If the user sets this Enum to ‘YES’, then the individual’s true infection status must equal to the inversion status and the last test result received was positive. If set to ‘NA’ (default), then do not include this as part of the check.

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_hiv.utils.targeting_config.IsOnART[source]#

Bases: BaseTargetingConfig

Select the individual based on whether or not they are actively on ART.

class emodpy_hiv.utils.targeting_config.IsPostDebut[source]#

Bases: BaseTargetingConfig

Select the individual based on whether or not they have reached sexual debut.

class emodpy_hiv.utils.targeting_config.HasBeenOnArtMoreOrLessThanNumMonths(num_months: float = 1500.0, more_or_less: MoreOrLess = MoreOrLess.LESS)[source]#

Bases: BaseTargetingConfig

Determine if the individual has been on ART for less than “num” months. It will be false if the individual is not on ART. The test will be strictly less than.

Parameters:

  • num_months – This is the number of months that will be used in the test. The individual’s duration on ART must be more or less than this value. NOTE: 1500 months is about 12 months / year * 125 years of max age

  • more_or_less – This is used to determine if the check should be less than or greater than.

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_hiv.utils.targeting_config.HasMoreOrLessThanNumPartners(num_partners: int = 0, more_or_less: MoreOrLess = MoreOrLess.LESS, of_relationship_type: OfRelationshipType = OfRelationshipType.NA)[source]#

Bases: BaseTargetingConfig

Determine if the individual has more or less than a specified number of active partners. This includes relationships that are paused due to migration. This test is strictly more or less than.

Parameters:

  • num_partners – This parameter allows the user to set the number of active partners/relationships that the individual must have more or less of. The value can range between 0 and 62.

  • more_or_less – This is used to determine if the check should be less than or greater than. The default value is ‘LESS’.

  • of_relationship_type – If the user sets this value to one of the four specific types (TRANSITORY, INFORMAL, MARITAL, COMMERCIAL), then the individual must have more or less relationships of this type. When the value is set to ‘NA’ (default), then it will count the relationships regardless of type.

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_hiv.utils.targeting_config.HasHadMultiplePartnersInLastNumMonths(num_month_type: NumMonthsType = NumMonthsType.THREE_MONTHS, of_relationship_type: OfRelationshipType = OfRelationshipType.NA)[source]#

Bases: BaseTargetingConfig

Determine if the individual has had more than one relationship in the last “Num” months. This could constitute as “high-risk” behavior. The goal is to target people that have had coital acts with more than one person during the last X months. This would count current relationships, relationships that started in the last X months, and relationships that have ended in the last X months. Basically, all the relationships that have been active at some point during the last X months.

NOTE: This only counts unique partners. Two relationships with the same person during the time period will count as one. For example, if you dated a person for three months, broke up, got back together after six months, and the time period was twelve months, then it would be considered one partner.

NOTE: Also note that one partner can count across multiple periods. For example, if the person has been in a MARITAL relationship for years, that partner will be counted in the last three months, last six months, last nine months, and last twelve months. If the person started a relationship last month, it will only be counted within the last three months.

Parameters:

  • num_month_type – This parameter allows the user to set the maximum number of months from the current day to consider if the individual had multiple relationships.

  • of_relationship_type – If the user sets this value to one of the four specific types (TRANSITORY, INFORMAL, MARITAL, COMMERCIAL), then the individual must have had more than one relationship of this type. When the value is set to ‘NA’ (default), then it just matters if the person had more than one relationship, regardless of type.

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_hiv.utils.targeting_config.HasCd4BetweenMinAndMax(min_cd4: float = 0, max_cd4: float = 2000)[source]#

Bases: BaseTargetingConfig

Determine if the individual has a CD4 count that is between “min” and “max”. The test is inclusive for “min” and exclusive for “max”.

Parameters:

  • min_cd4 – The minimum value of the test range. The individuals CD4 can be equal to this value to be considered “between”. The value can range from 0 to 1999 and must be less than ‘max_cd4’.

  • max_cd4 – The maximum value of the test range. The individual’s CD4 must be strictly less than this value to be considered “between”. The value can range from 0 to 2000 and must be greater than ‘min_cd4’.

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_hiv.utils.targeting_config.HasRelationship(of_relationship_type: OfRelationshipType = OfRelationshipType.NA, that_recently: RecentlyType = RecentlyType.NA, that_recently_ended_due_to: RelationshipTerminationReasonType = RelationshipTerminationReasonType.NA, with_partner_who: AbstractTargetingConfig | None = None)[source]#

Bases: BaseTargetingConfig

This is used to select people who have a partner/relationship that meets certain qualifications.

Parameters:

  • of_relationship_type – If the user sets this value to one of the four specific types (TRANSITORY, INFORMAL, MARITAL, COMMERCIAL), then the individual must have at least one relationships of this type.(default). The other constraints will be on these relationships. If NA is selected, then all of the individual’s relationships will be considered.

  • that_recently –

    This parameter is used if the relationship being considered must have recently been started or ended. Possible values are:

    • NA (Default) - Do no consider That_Recently in the selection process.

    • STARTED - Only consider relationships that have started within one time-step.

      One should note that the relationships you see will depend on whether you are using NodeLevelHealthTriggeredIV (NLHTIV) [add_intervention_triggered()] or an event coordinator [add_intervention_scheduled()]. NLHTIV and the individuals will be updated after new relationships have been created so with this feature, NLHTIV will see relationships in the previous time step as well as the current time step. An event coordinator executes BEFORE new relationships are formed so it will only see the relationships created in the previous time step.

    • ENDED - Check the status of the relationship that just ended. Note: This can only

      be used with NodeLevelHealthTriggeredIV listening for the ‘ExitedRelationship’ event.

  • that_recently_ended_due_to –

    If That_Recently is set to ‘ENDED’, this is used to look at the reason the relationship ended. Possible values are:

    • NA (Default) - The relationship has not been terminated.

    • BROKE_UP - The relationship ended due to the duration settings.

    • SELF_MIGRATING - One of the partners in the relationship has decided to migrate and so

      the relationship is terminated. Note: the user can control what happens to a relationship when there is migration; it does not have to terminate.

    • PARTNER_MIGRATING - The relationship is being terminated because one of the partners

      has another partner that is migrating. For example, a married couple is moving because the wife got a new job. The husband must terminate his other relationships with ‘PARTNER_MIGRATING’.

    • PARTNER_DIED - One of the partners died so the relationship was terminated.

    • PARTNER_TERMINATED - This happens when the couple is separated due to migration and one

      of the partners decides to terminate the relationship.

  • with_partner_who – Given that the parameters about the relationship are true, this parameter is used to look at the partner of the relationship. It is a Targeting_Config so one uses the same classes to query the partner. For example, to find out if person has a partner with HIV, you could use IsHivPositive.

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.