targeting_config

HasBeenOnArtMoreOrLessThanNumMonths

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:

Name	Type	Description	Default
num_months	float	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	1500.0
more_or_less	MoreOrLess	This is used to determine if the check should be less than or greater than.	LESS

Source code in emodpy_hiv/utils/targeting_config.py

class HasBeenOnArtMoreOrLessThanNumMonths(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.

    Args:
        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.
    """
    def __init__(self,
                 num_months: float = 1500.0,
                 more_or_less: MoreOrLess = MoreOrLess.LESS):
        super().__init__()
        self.class_name = "HasBeenOnArtMoreOrLessThanNumMonths"
        # TODO: use Ye's validate range check on num_months
        self.num_months = num_months
        self.more_or_less = more_or_less

    def to_schema_dict(self, campaign):
        """
        Create the ReadOnlyDict object representation of this Targeting_Config logic.
        This is the dictionary used to generate the JSON for EMOD.

        Args:
            campaign (emod_api.campaign): The campaign module that has the path to the schema

        Returns:
            (ReadOnlyDict): Schema for object.
        """
        tc_obj = super().to_schema_dict(campaign)
        tc_obj.Num_Months   = self.num_months          # noqa: E221
        tc_obj.More_Or_Less = self.more_or_less.value
        return tc_obj

to_schema_dict(campaign)

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

Parameters:

Name	Type	Description	Default
campaign	campaign	The campaign module that has the path to the schema	required

Returns:

Type	Description
ReadOnlyDict	Schema for object.

Source code in emodpy_hiv/utils/targeting_config.py

def to_schema_dict(self, campaign):
    """
    Create the ReadOnlyDict object representation of this Targeting_Config logic.
    This is the dictionary used to generate the JSON for EMOD.

    Args:
        campaign (emod_api.campaign): The campaign module that has the path to the schema

    Returns:
        (ReadOnlyDict): Schema for object.
    """
    tc_obj = super().to_schema_dict(campaign)
    tc_obj.Num_Months   = self.num_months          # noqa: E221
    tc_obj.More_Or_Less = self.more_or_less.value
    return tc_obj

HasCd4BetweenMinAndMax

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:

Name	Type	Description	Default
min_cd4	float	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'.	0
max_cd4	float	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'.	2000

Source code in emodpy_hiv/utils/targeting_config.py

class HasCd4BetweenMinAndMax(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".

    Args:
        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'.
    """
    def __init__(self, min_cd4: float = 0, max_cd4: float = 2000):
        super().__init__()
        self.class_name = "HasCd4BetweenMinAndMax"

        # TODO: Use Ye's validate value range method
        if min_cd4 >= max_cd4:
            msg = f"Invalid 'min_cd4'={min_cd4} and 'max_cd4'={max_cd4}.\n"
            msg += "min_cd4' must be strictly less than 'max_cd4'."
            raise ValueError(msg)

        self.min_cd4 = min_cd4
        self.max_cd4 = max_cd4

    def to_schema_dict(self, campaign):
        """
        Create the ReadOnlyDict object representation of this Targeting_Config logic.
        This is the dictionary used to generate the JSON for EMOD.

        Args:
            campaign (emod_api.campaign): The campaign module that has the path to the schema

        Returns:
            (ReadOnlyDict): Schema for object.
        """
        tc_obj = super().to_schema_dict(campaign)
        tc_obj.Min_CD4 = self.min_cd4
        tc_obj.Max_CD4 = self.max_cd4
        return tc_obj

to_schema_dict(campaign)

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

Parameters:

Name	Type	Description	Default
campaign	campaign	The campaign module that has the path to the schema	required

Returns:

Type	Description
ReadOnlyDict	Schema for object.

Source code in emodpy_hiv/utils/targeting_config.py

def to_schema_dict(self, campaign):
    """
    Create the ReadOnlyDict object representation of this Targeting_Config logic.
    This is the dictionary used to generate the JSON for EMOD.

    Args:
        campaign (emod_api.campaign): The campaign module that has the path to the schema

    Returns:
        (ReadOnlyDict): Schema for object.
    """
    tc_obj = super().to_schema_dict(campaign)
    tc_obj.Min_CD4 = self.min_cd4
    tc_obj.Max_CD4 = self.max_cd4
    return tc_obj

HasHadMultiplePartnersInLastNumMonths

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:

Name	Type	Description	Default
num_month_type	NumMonthsType	This parameter allows the user to set the maximum number of months from the current day to consider if the individual had multiple relationships.	THREE_MONTHS
of_relationship_type	OfRelationshipType	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.	NA

Source code in emodpy_hiv/utils/targeting_config.py

class HasHadMultiplePartnersInLastNumMonths(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.

    Args:
        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.
    """
    def __init__(self,
                 num_month_type: NumMonthsType = NumMonthsType.THREE_MONTHS,
                 of_relationship_type: OfRelationshipType = OfRelationshipType.NA):
        super().__init__()
        self.class_name = "HasHadMultiplePartnersInLastNumMonths"
        self.num_month_type = num_month_type
        self.of_relationship_type = of_relationship_type

    def to_schema_dict(self, campaign):
        """
        Create the ReadOnlyDict object representation of this Targeting_Config logic.
        This is the dictionary used to generate the JSON for EMOD.

        Args:
            campaign (emod_api.campaign): The campaign module that has the path to the schema

        Returns:
            (ReadOnlyDict): Schema for object.
        """
        tc_obj = super().to_schema_dict(campaign)
        tc_obj.Num_Months_Type      = self.num_month_type.value       # noqa: E221
        tc_obj.Of_Relationship_Type = self.of_relationship_type.value
        return tc_obj

to_schema_dict(campaign)

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

Parameters:

Name	Type	Description	Default
campaign	campaign	The campaign module that has the path to the schema	required

Returns:

Type	Description
ReadOnlyDict	Schema for object.

Source code in emodpy_hiv/utils/targeting_config.py

def to_schema_dict(self, campaign):
    """
    Create the ReadOnlyDict object representation of this Targeting_Config logic.
    This is the dictionary used to generate the JSON for EMOD.

    Args:
        campaign (emod_api.campaign): The campaign module that has the path to the schema

    Returns:
        (ReadOnlyDict): Schema for object.
    """
    tc_obj = super().to_schema_dict(campaign)
    tc_obj.Num_Months_Type      = self.num_month_type.value       # noqa: E221
    tc_obj.Of_Relationship_Type = self.of_relationship_type.value
    return tc_obj

HasMoreOrLessThanNumPartners

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:

Name	Type	Description	Default
num_partners	int	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.	0
more_or_less	MoreOrLess	This is used to determine if the check should be less than or greater than. The default value is 'LESS'.	LESS
of_relationship_type	OfRelationshipType	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.	NA

Source code in emodpy_hiv/utils/targeting_config.py

class HasMoreOrLessThanNumPartners(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.

    Args:
        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.
    """
    def __init__(self,
                 num_partners: int = 0,
                 more_or_less: MoreOrLess = MoreOrLess.LESS,
                 of_relationship_type: OfRelationshipType = OfRelationshipType.NA):
        super().__init__()
        self.class_name = "HasMoreOrLessThanNumPartners"

        # TODO: use Ye's validate range method on num_partners
        self.num_partners = num_partners
        self.more_or_less = more_or_less
        self.of_relationship_type = of_relationship_type

    def to_schema_dict(self, campaign):
        """
        Create the ReadOnlyDict object representation of this Targeting_Config logic.
        This is the dictionary used to generate the JSON for EMOD.

        Args:
            campaign (emod_api.campaign): The campaign module that has the path to the schema

        Returns:
            (ReadOnlyDict): Schema for object.
        """
        tc_obj = super().to_schema_dict(campaign)
        tc_obj.Num_Partners         = self.num_partners               # noqa: E221
        tc_obj.More_Or_Less         = self.more_or_less.value         # noqa: E221
        tc_obj.Of_Relationship_Type = self.of_relationship_type.value
        return tc_obj

to_schema_dict(campaign)

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

Parameters:

Name	Type	Description	Default
campaign	campaign	The campaign module that has the path to the schema	required

Returns:

Type	Description
ReadOnlyDict	Schema for object.

Source code in emodpy_hiv/utils/targeting_config.py

def to_schema_dict(self, campaign):
    """
    Create the ReadOnlyDict object representation of this Targeting_Config logic.
    This is the dictionary used to generate the JSON for EMOD.

    Args:
        campaign (emod_api.campaign): The campaign module that has the path to the schema

    Returns:
        (ReadOnlyDict): Schema for object.
    """
    tc_obj = super().to_schema_dict(campaign)
    tc_obj.Num_Partners         = self.num_partners               # noqa: E221
    tc_obj.More_Or_Less         = self.more_or_less.value         # noqa: E221
    tc_obj.Of_Relationship_Type = self.of_relationship_type.value
    return tc_obj

HasRelationship

Bases: BaseTargetingConfig

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

Parameters:

Name	Type	Description	Default
of_relationship_type	OfRelationshipType	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.	NA
that_recently	RecentlyType	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.	NA
that_recently_ended_due_to	RelationshipTerminationReasonType	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.	NA
with_partner_who	AbstractTargetingConfig	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.	None

Source code in emodpy_hiv/utils/targeting_config.py

class HasRelationship(BaseTargetingConfig):
    """
    This is used to select people who have a partner/relationship that meets certain
    qualifications.

    Args:
        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.
    """
    def __init__(self,
                 of_relationship_type:       OfRelationshipType                = OfRelationshipType.NA,                 # noqa: E221, E241
                 that_recently:              RecentlyType                      = RecentlyType.NA,                       # noqa: E221, E241
                 that_recently_ended_due_to: RelationshipTerminationReasonType = RelationshipTerminationReasonType.NA,
                 with_partner_who:           AbstractTargetingConfig           = None):                                 # noqa: E221, E241
        super().__init__()
        self.class_name = "HasRelationship"

        if (of_relationship_type == OfRelationshipType.NA) and\
           (that_recently        == RecentlyType.NA      ) and\
           (with_partner_who     is None                 ):      # noqa: E202, E272, E221
            msg = "No parameters were configured so no relationships would be targeted.\n"
            msg += "'HasRelationship' requires that you define at least one parameter."
            raise ValueError(msg)

        self.of_relationship_type       = of_relationship_type       # noqa: E221
        self.that_recently              = that_recently              # noqa: E221
        self.that_recently_ended_due_to = that_recently_ended_due_to
        self.with_partner_who           = with_partner_who           # noqa: E221

    def to_schema_dict(self, campaign):
        """
        Create the ReadOnlyDict object representation of this Targeting_Config logic.
        This is the dictionary used to generate the JSON for EMOD.

        Args:
            campaign (emod_api.campaign): The campaign module that has the path to the schema

        Returns:
            (ReadOnlyDict): Schema for object.
        """
        tc_obj = super().to_schema_dict(campaign)
        tc_obj.Of_Relationship_Type       = self.of_relationship_type.value        # noqa: E221
        tc_obj.That_Recently              = self.that_recently.value               # noqa: E221
        tc_obj.That_Recently_Ended_Due_To = self.that_recently_ended_due_to.value

        if self.with_partner_who:
            tc_obj.With_Partner_Who = self.with_partner_who.to_schema_dict(campaign)

        return tc_obj

    def to_simple_dict(self, campaign):
        """
        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.

        Args:
            campaign (emod_api.campaign): The campaign module that has the path to the schema

        Returns:
            (dict): Campagin object as a dictionary.
        """
        tc_dict = super().to_simple_dict(campaign)
        if self.with_partner_who:
            # we need to convert this object here because it is easier to ensure the object
            # is converted to the simple dictionary.
            tc_dict["With_Partner_Who"] = self.with_partner_who.to_simple_dict(campaign)
        else:
            # This gets rid of the default stuff put into the dictionary
            del tc_dict["With_Partner_Who"]
        return tc_dict

to_schema_dict(campaign)

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

Parameters:

Name	Type	Description	Default
campaign	campaign	The campaign module that has the path to the schema	required

Returns:

Type	Description
ReadOnlyDict	Schema for object.

Source code in emodpy_hiv/utils/targeting_config.py

def to_schema_dict(self, campaign):
    """
    Create the ReadOnlyDict object representation of this Targeting_Config logic.
    This is the dictionary used to generate the JSON for EMOD.

    Args:
        campaign (emod_api.campaign): The campaign module that has the path to the schema

    Returns:
        (ReadOnlyDict): Schema for object.
    """
    tc_obj = super().to_schema_dict(campaign)
    tc_obj.Of_Relationship_Type       = self.of_relationship_type.value        # noqa: E221
    tc_obj.That_Recently              = self.that_recently.value               # noqa: E221
    tc_obj.That_Recently_Ended_Due_To = self.that_recently_ended_due_to.value

    if self.with_partner_who:
        tc_obj.With_Partner_Who = self.with_partner_who.to_schema_dict(campaign)

    return tc_obj

to_simple_dict(campaign)

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:

Name	Type	Description	Default
campaign	campaign	The campaign module that has the path to the schema	required

Returns:

Type	Description
dict	Campagin object as a dictionary.

Source code in emodpy_hiv/utils/targeting_config.py

def to_simple_dict(self, campaign):
    """
    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.

    Args:
        campaign (emod_api.campaign): The campaign module that has the path to the schema

    Returns:
        (dict): Campagin object as a dictionary.
    """
    tc_dict = super().to_simple_dict(campaign)
    if self.with_partner_who:
        # we need to convert this object here because it is easier to ensure the object
        # is converted to the simple dictionary.
        tc_dict["With_Partner_Who"] = self.with_partner_who.to_simple_dict(campaign)
    else:
        # This gets rid of the default stuff put into the dictionary
        del tc_dict["With_Partner_Who"]
    return tc_dict

IsCircumcised

Bases: BaseTargetingConfig

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

Source code in emodpy_hiv/utils/targeting_config.py

class IsCircumcised(BaseTargetingConfig):
    """
    Select the individual based on whether or not they are circumcised.
    """
    def __init__(self):
        super().__init__()
        self.class_name = "IsCircumcised"

IsHivPositive

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:

Name	Type	Description	Default
and_has_ever_been_tested	YesNoNa	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.	NA
and_has_ever_tested_positive	YesNoNa	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.	NA
and_has_received_positive_results	YesNoNa	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.	NA

Source code in emodpy_hiv/utils/targeting_config.py

class IsHivPositive(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.

    Args:
        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.
    """
    def __init__(self,
                 and_has_ever_been_tested:          YesNoNa = YesNoNa.NA,   # noqa: E241
                 and_has_ever_tested_positive:      YesNoNa = YesNoNa.NA,   # noqa: E241
                 and_has_received_positive_results: YesNoNa = YesNoNa.NA):
        super().__init__()
        self.class_name = "IsHivPositive"
        self.been_tested = and_has_ever_been_tested
        self.tested_positive = and_has_ever_tested_positive
        self.received_positive_results = and_has_received_positive_results

    def to_schema_dict(self, campaign):
        """
        Create the ReadOnlyDict object representation of this Targeting_Config logic.
        This is the dictionary used to generate the JSON for EMOD.

        Args:
            campaign (emod_api.campaign): The campaign module that has the path to the schema

        Returns:
            (ReadOnlyDict): Schema for object.
        """
        tc_obj = super().to_schema_dict(campaign)
        tc_obj.And_Has_Ever_Been_Tested          = self.been_tested.value                # noqa: E221
        tc_obj.And_Has_Ever_Tested_Positive      = self.tested_positive.value            # noqa: E221
        tc_obj.And_Has_Received_Positive_Results = self.received_positive_results.value
        return tc_obj

to_schema_dict(campaign)

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

Parameters:

Name	Type	Description	Default
campaign	campaign	The campaign module that has the path to the schema	required

Returns:

Type	Description
ReadOnlyDict	Schema for object.

Source code in emodpy_hiv/utils/targeting_config.py

def to_schema_dict(self, campaign):
    """
    Create the ReadOnlyDict object representation of this Targeting_Config logic.
    This is the dictionary used to generate the JSON for EMOD.

    Args:
        campaign (emod_api.campaign): The campaign module that has the path to the schema

    Returns:
        (ReadOnlyDict): Schema for object.
    """
    tc_obj = super().to_schema_dict(campaign)
    tc_obj.And_Has_Ever_Been_Tested          = self.been_tested.value                # noqa: E221
    tc_obj.And_Has_Ever_Tested_Positive      = self.tested_positive.value            # noqa: E221
    tc_obj.And_Has_Received_Positive_Results = self.received_positive_results.value
    return tc_obj

IsOnART

Bases: BaseTargetingConfig

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

Source code in emodpy_hiv/utils/targeting_config.py

class IsOnART(BaseTargetingConfig):
    """
    Select the individual based on whether or not they are actively on ART.
    """
    def __init__(self):
        super().__init__()
        self.class_name = "IsOnART"

IsPostDebut

Bases: BaseTargetingConfig

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

Source code in emodpy_hiv/utils/targeting_config.py

class IsPostDebut(BaseTargetingConfig):
    """
    Select the individual based on whether or not they have reached sexual debut.
    """
    def __init__(self):
        super().__init__()
        self.class_name = "IsPostDebut"

MoreOrLess

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.

Source code in emodpy_hiv/utils/targeting_config.py

class MoreOrLess(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" # less than '<'
    MORE = "MORE" # greater than '>'

NumMonthsType

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.

Source code in emodpy_hiv/utils/targeting_config.py

class NumMonthsType(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"   # noqa: E221
    SIX_MONTHS    = "SIX_MONTHS"     # noqa: E221
    NINE_MONTHS   = "NINE_MONTHS"    # noqa: E221
    TWELVE_MONTHS = "TWELVE_MONTHS"

OfRelationshipType

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.

Source code in emodpy_hiv/utils/targeting_config.py

class OfRelationshipType(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"           # noqa: E221
    TRANSITORY = "TRANSITORY"
    INFORMAL   = "INFORMAL"     # noqa: E221
    MARITAL    = "MARITAL"      # noqa: E221
    COMMERCIAL = "COMMERCIAL"

RecentlyType

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.

Source code in emodpy_hiv/utils/targeting_config.py

class RecentlyType(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"       # noqa: E221
    STARTED = "STARTED"
    ENDED   = "ENDED"    # noqa: E221

RelationshipTerminationReasonType

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.

Source code in emodpy_hiv/utils/targeting_config.py

class RelationshipTerminationReasonType(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" # EMOD does not have the underscore
    """
    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".
    """

BROKE_UP = 'BROKEUP' class-attribute instance-attribute

The relationship ended due to the duration settings.

NA = 'NA' class-attribute instance-attribute

The relationship has not been terminated.

PARTNER_DIED = 'PARTNER_DIED' class-attribute instance-attribute

One of the partners died so the relationship was terminated.

PARTNER_MIGRATING = 'PARTNER_MIGRATING' class-attribute instance-attribute

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_TERMINATED = 'PARTNER_TERMINATED' class-attribute instance-attribute

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

SELF_MIGRATING = 'SELF_MIGRATING' class-attribute instance-attribute

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.

YesNoNa

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)

Source code in emodpy_hiv/utils/targeting_config.py

class YesNoNa(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"    # noqa: E221
    NA  = "NA"    # noqa: E221