individual_intervention

ARTDropout

Bases: IndividualIntervention

The ARTDropout intervention class removes an individual from antiretroviral therapy (ART) and interrupts their progress through the cascade of care. The individual's infectiousness will return to a non-suppressed level, and a new prognosis will be assigned.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class ARTDropout(IndividualIntervention):
    """
    The **ARTDropout** intervention class removes an individual from antiretroviral therapy (ART) and
    interrupts their progress through the cascade of care. The individual's infectiousness will
    return to a non-suppressed level, and a new prognosis will be assigned.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'ARTDropout', common_intervention_parameters)

ARTMortalityTable

Bases: IndividualIntervention

The ARTMortalityTable intervention class allows the user to modify an individual's life expectancy based on different levels of ART adherence; the user defines parameters for age, CD4 count, and time on ART in a multidimensional table which is then used to determine mortality rate. Note: If you have different adherence levels for each gender, then you will need to configure your campaign to distribute an ARTMortalityTable for each gender and adherence level.

Additional considerations when using this intervention

• The model will not allow someone who is HIV negative to be put on ART.
• A person who has not previously been on ART is considered to be 'starting ART' at the time this intervention is applied; the model will track this start time/duration.
• If a person is already on ART from another intervention, receiving a second ART intervention will have no effect.
• If a person is on already ART and receives the ARTMortalityTable intervention, the original ART start time will be used to calculate the duration from enrollment to ART AIDS Death. The duration since starting ART will not change; it will continue to increase.
• If a person is on ART and receives the ARTDropout intervention, the person will go off ART and the duration will be reset; if receiving a new ART intervention, this new start time/duration will be used in any calculations.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
mortality_table	(list[list[list[float]]], required)	Three-dimensional array of mortality rates used to determine the number of days until AIDS death. Dimensioned by the values specified in art_duration_days_bins, age_years_bins, and cd4_count_bins.	required
art_duration_days_bins	(list[float], required)	An array of bins representing the person's duration on ART, in days (greater than or equal to the value of the bin, but less than the value of the next bin). Each value represents the outer dimension of the mortality_table. Must be in ascending order.	required
age_years_bins	(list[float], required)	An array of bins representing the age of the person, in years, at the time they received the intervention (greater than or equal to the value of the bin, but less than the value of the next bin). If they are new to ART, then it is the age that they started ART. If they are changing their adherence, then it is the age at that time. This bin is used to select the second dimension of the mortality_table. Must be in ascending order.	required
cd4_count_bins	(list[float], required)	An array of bins representing a person's CD4 count at the time they received the intervention (started ART or changed adherence). For each value in the array, there will be one value in the associated row in the mortality_table. A mortality rate will be selected from the table as follows: * Person's CD4 is less than first value in array: Use first mortality rate * Person's CD4 is greater than the last value in the array: Use the last mortality rate * Person's CD4 is between two values: Use linear interpolation to find the mortality rate associated with the person's CD4 Must be in ascending order.	required
days_to_achieve_viral_suppression	float	The number of days after ART initiation over which infectiousness declines linearly until the art_multiplier_on_transmission_prob_per_act takes full effect. Minimum value: 0 Maximum value: 3.40282e+38 Default value: 183	183
art_multiplier_on_transmission_prob_per_act	float	Multiplier acting on Base_Infectivity to determine the per-act transmission probability of a virally suppressed HIV+ individual. Minimum value: 0 Maximum value: 1 Default value: 0.08	0.08
art_is_active_against_mortality_and_transmission	bool	If set to true (1), ART will suppress viral load and extend prognosis. Default value: True	True
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Example

Creating an ARTMortalityTable intervention with comprehensive mortality data: - 5 ART duration bins (0-6mo, 6-12mo, 12-24mo, 24-36mo, 36+mo) - 2 age groups (under 40, 40 and over) - 7 CD4 count bins reflecting different immune system states - Higher mortality rates for early ART duration and lower CD4 counts - Reduced mortality over time as patients stabilize on treatment

>>> from emodpy_hiv.campaign.individual_intervention import ARTMortalityTable
>>> from emodpy_hiv.campaign.common import CommonInterventionParameters
>>> import emodpy_hiv.campaign as api_campaign
>>>
>>> art_duration_days_bins=[0, 183, 365, 730, 1095]                    # 0, 6mo, 1yr, 2yr, 3yr in days
>>> age_years_bins=[0, 40]                                             # Under 40, 40+
>>> cd4_count_bins=[0, 25, 74.5, 149.5, 274.5, 424.5, 624.5]           # CD4 count thresholds
>>> # Define mortality table: 5 duration bins x 2 age bins x 7 CD4 bins
>>> mortality_table = [
>>>     [  # Duration bin 0 (0-6 months)
>>>         [0.2015, 0.2015, 0.1128, 0.0625, 0.0312, 0.0206, 0.0162],  # Age 0-40
>>>         [0.0875, 0.0875, 0.0490, 0.0271, 0.0136, 0.0062, 0.0041]   # Age 40+
>>>     ],
>>>     [  # Duration bin 1 (6-12 months)
>>>         [0.0271, 0.0271, 0.0184, 0.0149, 0.0074, 0.0048, 0.0048],
>>>         [0.0171, 0.0171, 0.0116, 0.0094, 0.0047, 0.0030, 0.0030]
>>>     ],
>>>     [  # Duration bin 2 (12-24 months)
>>>         [0.0095, 0.0095, 0.0065, 0.0052, 0.0026, 0.0026, 0.0026],
>>>         [0.0095, 0.0095, 0.0065, 0.0052, 0.0026, 0.0026, 0.0026]
>>>     ],
>>>     [  # Duration bin 3 (24-36 months)
>>>         [0.0075, 0.0075, 0.0051, 0.0041, 0.0021, 0.0021, 0.0021],
>>>         [0.0075, 0.0075, 0.0051, 0.0041, 0.0021, 0.0021, 0.0021]
>>>     ],
>>>     [  # Duration bin 4 (36+ months)
>>>         [0.0060, 0.0060, 0.0041, 0.0033, 0.0017, 0.0017, 0.0017],
>>>         [0.0060, 0.0060, 0.0041, 0.0033, 0.0017, 0.0017, 0.0017]
>>>     ]
>>>   ]
>>>
>>> # Create the intervention
>>> art_intervention = ARTMortalityTable(campaign=api_campaign,
>>>                                      mortality_table=mortality_table,
>>>                                      art_duration_days_bins=art_duration_days_bins,
>>>                                      age_years_bins=age_years_bins,
>>>                                      cd4_count_bins=cd4_count_bins,
>>>                                      days_to_achieve_viral_suppression=183.0,
>>>                                      art_multiplier_on_transmission_prob_per_act=0.08,
>>>                                      art_is_active_against_mortality_and_transmission=True,
>>>                                      common_intervention_parameters=CommonInterventionParameters(cost=1)
>>> )

Source code in emodpy_hiv/campaign/individual_intervention.py

class ARTMortalityTable(IndividualIntervention):
    """
    The **ARTMortalityTable** intervention class allows the user to modify an individual's life expectancy
    based on different levels of ART adherence; the user defines parameters for age, CD4 count, and time
    on ART in a multidimensional table which is then used to determine mortality rate. Note: If you
    have different adherence levels for each gender, then you will need to configure your campaign to
    distribute an ARTMortalityTable for each gender and adherence level.

    Additional considerations when using this intervention:
        - The model will not allow someone who is HIV negative to be put on ART.
        - A person who has not previously been on ART is considered to be 'starting ART' at the time
          this intervention is applied; the model will track this start time/duration.
        - If a person is already on ART from another intervention, receiving a second ART intervention
          will have no effect.
        - If a person is on already ART and receives the **ARTMortalityTable** intervention, the original ART
          start time will be used to calculate the duration from enrollment to ART AIDS Death. The duration
          since starting ART will not change; it will continue to increase.
        - If a person is on ART and receives the **ARTDropout** intervention, the person will go off ART and
          the duration will be reset; if receiving a new ART intervention, this new start time/duration
          will be used in any calculations.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        mortality_table(list[list[list[float]]], required):
            Three-dimensional array of mortality rates used to determine the number of days until AIDS death.
            Dimensioned by the values specified in **art_duration_days_bins**, **age_years_bins**, and
            **cd4_count_bins**.

        art_duration_days_bins(list[float], required):
            An array of bins representing the person's duration on ART, in days (greater than or equal to the
            value of the bin, but less than the value of the next bin). Each value represents the outer
            dimension of the **mortality_table**. Must be in ascending order.

        age_years_bins(list[float], required):
            An array of bins representing the age of the person, in years, at the time they received the
            intervention (greater than or equal to the value of the bin, but less than the value of the next
            bin). If they are new to ART, then it is the age that they started ART. If they are changing their
            adherence, then it is the age at that time. This bin is used to select the second dimension of the
            **mortality_table**. Must be in ascending order.

        cd4_count_bins(list[float], required):
            An array of bins representing a person's CD4 count at the time they received the intervention
            (started ART or changed adherence). For each value in the array, there will be one value in the
            associated row in the **mortality_table**.  A mortality rate will be selected from the table as
            follows:
            * Person's CD4 is less than first value in array: Use first mortality rate
            * Person's CD4 is greater than the last value in the array: Use the last mortality rate
            * Person's CD4 is between two values: Use linear interpolation to find the mortality rate
            associated with the person's CD4
            Must be in ascending order.

        days_to_achieve_viral_suppression(float, optional):
            The number of days after ART initiation over which infectiousness declines linearly until the
            **art_multiplier_on_transmission_prob_per_act** takes full effect.
            Minimum value: 0
            Maximum value: 3.40282e+38
            Default value: 183

        art_multiplier_on_transmission_prob_per_act(float, optional):
            Multiplier acting on Base_Infectivity to determine the per-act transmission probability of a
            virally suppressed HIV+ individual.
            Minimum value: 0
            Maximum value: 1
            Default value: 0.08

        art_is_active_against_mortality_and_transmission(bool, optional):
            If set to true (1), ART will suppress viral load and extend prognosis.
            Default value: True

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None

    Example:
        Creating an ARTMortalityTable intervention with comprehensive mortality data:
            - 5 ART duration bins (0-6mo, 6-12mo, 12-24mo, 24-36mo, 36+mo)
            - 2 age groups (under 40, 40 and over)
            - 7 CD4 count bins reflecting different immune system states
            - Higher mortality rates for early ART duration and lower CD4 counts
            - Reduced mortality over time as patients stabilize on treatment

            >>> from emodpy_hiv.campaign.individual_intervention import ARTMortalityTable
            >>> from emodpy_hiv.campaign.common import CommonInterventionParameters
            >>> import emodpy_hiv.campaign as api_campaign
            >>>
            >>> art_duration_days_bins=[0, 183, 365, 730, 1095]                    # 0, 6mo, 1yr, 2yr, 3yr in days
            >>> age_years_bins=[0, 40]                                             # Under 40, 40+
            >>> cd4_count_bins=[0, 25, 74.5, 149.5, 274.5, 424.5, 624.5]           # CD4 count thresholds
            >>> # Define mortality table: 5 duration bins x 2 age bins x 7 CD4 bins
            >>> mortality_table = [
            >>>     [  # Duration bin 0 (0-6 months)
            >>>         [0.2015, 0.2015, 0.1128, 0.0625, 0.0312, 0.0206, 0.0162],  # Age 0-40
            >>>         [0.0875, 0.0875, 0.0490, 0.0271, 0.0136, 0.0062, 0.0041]   # Age 40+
            >>>     ],
            >>>     [  # Duration bin 1 (6-12 months)
            >>>         [0.0271, 0.0271, 0.0184, 0.0149, 0.0074, 0.0048, 0.0048],
            >>>         [0.0171, 0.0171, 0.0116, 0.0094, 0.0047, 0.0030, 0.0030]
            >>>     ],
            >>>     [  # Duration bin 2 (12-24 months)
            >>>         [0.0095, 0.0095, 0.0065, 0.0052, 0.0026, 0.0026, 0.0026],
            >>>         [0.0095, 0.0095, 0.0065, 0.0052, 0.0026, 0.0026, 0.0026]
            >>>     ],
            >>>     [  # Duration bin 3 (24-36 months)
            >>>         [0.0075, 0.0075, 0.0051, 0.0041, 0.0021, 0.0021, 0.0021],
            >>>         [0.0075, 0.0075, 0.0051, 0.0041, 0.0021, 0.0021, 0.0021]
            >>>     ],
            >>>     [  # Duration bin 4 (36+ months)
            >>>         [0.0060, 0.0060, 0.0041, 0.0033, 0.0017, 0.0017, 0.0017],
            >>>         [0.0060, 0.0060, 0.0041, 0.0033, 0.0017, 0.0017, 0.0017]
            >>>     ]
            >>>   ]
            >>>
            >>> # Create the intervention
            >>> art_intervention = ARTMortalityTable(campaign=api_campaign,
            >>>                                      mortality_table=mortality_table,
            >>>                                      art_duration_days_bins=art_duration_days_bins,
            >>>                                      age_years_bins=age_years_bins,
            >>>                                      cd4_count_bins=cd4_count_bins,
            >>>                                      days_to_achieve_viral_suppression=183.0,
            >>>                                      art_multiplier_on_transmission_prob_per_act=0.08,
            >>>                                      art_is_active_against_mortality_and_transmission=True,
            >>>                                      common_intervention_parameters=CommonInterventionParameters(cost=1)
            >>> )
    """

    def __init__(self,
                 campaign: api_campaign,
                 mortality_table: list[list[list[float]]],
                 art_duration_days_bins: list[float],
                 age_years_bins: list[float],
                 cd4_count_bins: list[float],
                 days_to_achieve_viral_suppression: float = 183,
                 art_multiplier_on_transmission_prob_per_act: float = 0.08,
                 art_is_active_against_mortality_and_transmission: bool = True,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'ARTMortalityTable', common_intervention_parameters)

        self._validate_mortality_table_inputs(mortality_table, art_duration_days_bins, age_years_bins, cd4_count_bins)

        self._intervention.MortalityTable = mortality_table
        self._intervention.Days_To_Achieve_Viral_Suppression = validate_value_range(days_to_achieve_viral_suppression, 'days_to_achieve_viral_suppression', 0, 3.40282e+38, float)
        self._intervention.CD4_Count_Bins = cd4_count_bins
        self._intervention.Age_Years_Bins = age_years_bins
        self._intervention.ART_Multiplier_On_Transmission_Prob_Per_Act = validate_value_range(art_multiplier_on_transmission_prob_per_act, 'art_multiplier_on_transmission_prob_per_act', 0, 1, float)
        self._intervention.ART_Is_Active_Against_Mortality_And_Transmission = art_is_active_against_mortality_and_transmission
        self._intervention.ART_Duration_Days_Bins = art_duration_days_bins

    def _validate_mortality_table_inputs(self, mortality_table, art_duration_days_bins, age_years_bins, cd4_count_bins):
        """
        Validate that mortality table and associated bins are consistent and properly formatted.

        Args:
            mortality_table: 3D list of mortality rates (required)
            art_duration_days_bins: List of ART duration bins (required)
            age_years_bins: List of age bins (required)
            cd4_count_bins: List of CD4 count bins (required)
        """
        self._validate_bin_parameters(art_duration_days_bins, age_years_bins, cd4_count_bins)
        self._validate_mortality_table_structure_and_dimensions(mortality_table, art_duration_days_bins, age_years_bins, cd4_count_bins)

    def _validate_mortality_table_structure_and_dimensions(self, mortality_table, art_duration_days_bins, age_years_bins, cd4_count_bins):
        """
        Validate the 3D structure, values, and dimensions of the mortality table in a single pass.

        Args:
            mortality_table: 3D list of mortality rates
            art_duration_days_bins: List of ART duration bins
            age_years_bins: List of age bins
            cd4_count_bins: List of CD4 count bins
        """
        if not isinstance(mortality_table, list):
            raise TypeError("mortality_table must be a list")

        # Check first dimension (duration bins)
        if len(mortality_table) != len(art_duration_days_bins):
            raise ValueError(f"mortality_table first dimension ({len(mortality_table)}) must match art_duration_days_bins length ({len(art_duration_days_bins)})")

        # Validate each dimension and check dimensional consistency
        expected_age_bins = len(age_years_bins)
        expected_cd4_bins = len(cd4_count_bins)

        for i, outer_list in enumerate(mortality_table):
            if not isinstance(outer_list, list):
                raise TypeError(f"mortality_table[{i}] must be a list")

            # Check second dimension (age bins)
            if len(outer_list) != expected_age_bins:
                raise ValueError(f"mortality_table[{i}] length ({len(outer_list)}) must match age_years_bins length ({expected_age_bins})")

            for j, inner_list in enumerate(outer_list):
                if not isinstance(inner_list, list):
                    raise TypeError(f"mortality_table[{i}][{j}] must be a list")

                # Check third dimension (CD4 bins)
                if len(inner_list) != expected_cd4_bins:
                    raise ValueError(f"mortality_table[{i}][{j}] length ({len(inner_list)}) must match cd4_count_bins length ({expected_cd4_bins})")

                # Validate all values are numeric and within valid range
                for k, value in enumerate(inner_list):
                    if not isinstance(value, (int, float)):
                        raise TypeError(f"mortality_table[{i}][{j}][{k}] must be a number, got {type(value)}")
                    if value < 0 or value > 1:
                        raise ValueError(f"mortality_table[{i}][{j}][{k}] must between 0 and 1, got {value}")

    def _validate_bin_parameters(self, art_duration_days_bins, age_years_bins, cd4_count_bins):
        """
        Validate the bin parameter arrays.

        Args:
            art_duration_days_bins: List of ART duration bins
            age_years_bins: List of age bins
            cd4_count_bins: List of CD4 count bins
        """
        for bin_name, bin_values, max_value in [('art_duration_days_bins', art_duration_days_bins, None),
                                                ('age_years_bins', age_years_bins, 125),
                                                ('cd4_count_bins', cd4_count_bins, 1000)]:
            if not isinstance(bin_values, list):
                raise TypeError(f"{bin_name} must be a list")
            if len(bin_values) == 0:
                raise ValueError(f"{bin_name} cannot be empty")

            # Validate all values are numeric and non-negative
            for i, value in enumerate(bin_values):
                if not isinstance(value, (int, float)):
                    raise TypeError(f"{bin_name}[{i}] must be a number, got {type(value)}")
                if value < 0:
                    raise ValueError(f"{bin_name}[{i}] must be non-negative, got {value}")
                if max_value and value > max_value:
                    raise ValueError(f"{bin_name}[{i}] must be less than or equal to {max_value}, got {value}")

            # Validate bins are in ascending order
            for i in range(1, len(bin_values)):
                if bin_values[i] <= bin_values[i - 1]:
                    raise ValueError(f"{bin_name} must be in ascending order: {bin_values[i - 1]} >= {bin_values[i]} at positions {i - 1}, {i}")

AgeDiagnostic

Bases: IndividualIntervention

The AgeDiagnostic allows you to broadcast different events based on the individual's age. For example, you could distribute this intervention to people who are high risk and use the intervention to have different things happen (because of the broadcasted events) based on their age.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
age_thresholds	list[RangeThreshold]	Used to associate age ranges for individuals. Default value: None	None
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class AgeDiagnostic(IndividualIntervention):
    """
    The **AgeDiagnostic** allows you to broadcast different events based on the individual's age.  For example,
    you could distribute this intervention to people who are high risk and use the intervention to have
    different things happen (because of the broadcasted events) based on their age.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        age_thresholds(list[RangeThreshold], optional):
            Used to associate age ranges for individuals.
            Default value: None

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 age_thresholds: list[RangeThreshold] = None,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'AgeDiagnostic', common_intervention_parameters)

        for at in age_thresholds:
            self._intervention.Age_Thresholds.append(at.to_schema_dict(campaign))

AntiretroviralTherapy

Bases: IndividualIntervention

The AntiretroviralTherapy intervention class begins antiretroviral therapy (ART) for specified individuals. To remove an individual from ART, use ARTDropout. Please refer to the documentation for AntiretroviralTherapy at the following link: :doc:emod-hiv:emod/hiv-model-healthcare-systems.

Additional considerations when using this intervention

• The model will not allow someone who is HIV negative to be put on ART.
• A person who has not previously been on ART is considered to be 'starting ART' at the time this intervention is applied; the model will track this start time/duration.
• If a person is already on ART from another intervention, receiving a second ART intervention will have no effect.
• If a person is on already ART and receives the ARTMortalityTable intervention, the original ART start time will be used to calculate the duration from enrollment to ART AIDS Death. The duration since starting ART will not change; it will continue to increase.
• If a person is on ART and receives the ARTDropout intervention, the person will go off ART and the duration will be reset; if receiving a new ART intervention, this new start time/duration will be used in any calculations.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
days_to_achieve_viral_suppression	float	The number of days after ART initiation over which infectiousness declines linearly until the art_multiplier_on_transmission_prob_per_act takes full effect. Minimum value: 0 Maximum value: 3.40282e+38 Default value: 183	183
art_survival_who_stage_threshold_for_cox	float	If the person receiving ART has a WHO Stage greater than or equal to this threshold, then use the hazard ratio determined by the parameter art_survival_hazard_ratio_who_stage_3plus. Minimum value: 0 Maximum value: 5 Default value: 3	3
art_survival_hazard_ratio_who_stage_3plus	float	The hazard ratio comparing those starting ART in WHO stage >= 3 to those in WHO stage < 3. Minimum value: 1e-06 Maximum value: 1000000.0 Default value: 2.7142	2.7142
art_survival_hazard_ratio_female	float	The hazard ratio comparing survival female to male survival for those starting ART. Minimum value: 1e-06 Maximum value: 1000000.0 Default value: 0.6775	0.6775
art_survival_hazard_ratio_cd4_slope	float	The slope value to sue when calculating the hazard for for the person based on their CD4 count. multiplier = exp(cd4_slope * cd4 + cd4_intercept) Minimum value: -1000000.0 Maximum value: 1000000.0 Default value: -0.00758256	-0.00758256
art_survival_hazard_ratio_cd4_intercept	float	The Y-intercept to use when calculating the hazard ratio for the person based on their CD4 count. multiplier = exp(cd4_slope * cd4 + cd4_intercept) Minimum value: -1000000.0 Maximum value: 1000000.0 Default value: 0.282852	0.282852
art_survival_hazard_ratio_body_weight_kg_slope	float	The slope to use when calculating the hazard ratio for the person's body weight. The body weight is determined by WHO stage: * WHO Stage 0 = 65.0 kg * WHO Stage 1-2 = 62.1 kg * WHO Stage 2-3 = 57.0 kg * WHO Stage 3-4 = 50.0 kg * WHO Stage 4+ = 40.1 kg multiplier = exp(weight_slope * weight + weight_intercept) Minimum value: -1000000.0 Maximum value: 1000000.0 Default value: -0.073153	-0.073153
art_survival_hazard_ratio_body_weight_kg_intercept	float	The Y-intercept to use when calculating the hazard ratio for the person's body weight. The body weight is determined by WHO stage: WHO Stage 0 = 65.0 kg WHO Stage 1-2 = 62.1 kg WHO Stage 2-3 = 57.0 kg WHO Stage 3-4 = 50.0 kg WHO Stage 4+ = 40.1 kg multiplier = exp(weight_slope * weight + weight_intercept) Minimum value: -1000000.0 Maximum value: 1000000.0 Default value: 3.05043	3.05043
art_survival_hazard_ratio_age_over_40yr	float	The hazard ratio comparing the survival time of those starting ART over 40 years of age compared to those starting ART <40 years. Minimum value: 1e-06 Maximum value: 1000000.0 Default value: 1.4309	1.4309
art_survival_baseline_hazard_weibull_shape	float	Shape parameter for a Weibull distribution of survival time in years for a male < 40 with WHO stage of 1 or 2 starting ART (base case). Minimum value: 0 Maximum value: 10 Default value: 0.34	0.34
art_survival_baseline_hazard_weibull_scale	float	Scale parameter for a Weibull distribution of survival time in years for a male < 40 with WHO stage of 1 or 2 starting ART (base case). Minimum value: 1e-06 Maximum value: 1000000.0 Default value: 123.83	123.83
art_multiplier_on_transmission_prob_per_act	float	Multiplier acting on Base_Infectivity to determine the per-act transmission probability of a virally suppressed HIV+ individual. Minimum value: 0 Maximum value: 1 Default value: 0.08	0.08
art_is_active_against_mortality_and_transmission	bool	If set to true (1), ART will suppress viral load and extend prognosis. Default value: True	True
art_cd4_at_initiation_saturating_reduction_in_mortality	float	The duration from ART enrollment to on-ART HIV-cause death increases with CD4 at ART initiation up to a threshold determined by this parameter value. This is the maximum value that CD4 is allowed to have in the hazard ratio calculation for CD4. Minimum value: 0 Maximum value: 3.40282e+38 Default value: 350	350
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class AntiretroviralTherapy(IndividualIntervention):
    """
    The **AntiretroviralTherapy** intervention class begins antiretroviral therapy (ART) for specified individuals.
    To remove an individual from ART, use **ARTDropout**. Please refer to the documentation for
    **AntiretroviralTherapy** at the following link:
    :doc:`emod-hiv:emod/hiv-model-healthcare-systems`.

    Additional considerations when using this intervention:
        - The model will not allow someone who is HIV negative to be put on ART.
        - A person who has not previously been on ART is considered to be 'starting ART' at the time this
          intervention is applied; the model will track this start time/duration.
        - If a person is already on ART from another intervention, receiving a second ART intervention will
          have no effect.
        - If a person is on already ART and receives the ARTMortalityTable intervention, the original ART
          start time will be used to calculate the duration from enrollment to ART AIDS Death. The duration
          since starting ART will not change; it will continue to increase.
        - If a person is on ART and receives the **ARTDropout** intervention, the person will go off ART and
          the duration will be reset; if receiving a new ART intervention, this new start time/duration will
          be used in any calculations.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        days_to_achieve_viral_suppression(float, optional):
            The number of days after ART initiation over which infectiousness declines linearly until the
            **art_multiplier_on_transmission_prob_per_act** takes full effect.
            Minimum value: 0
            Maximum value: 3.40282e+38
            Default value: 183

        art_survival_who_stage_threshold_for_cox(float, optional):
            If the person receiving ART has a WHO Stage greater than or equal to this threshold, then use the
            hazard ratio determined by the parameter **art_survival_hazard_ratio_who_stage_3plus**.
            Minimum value: 0
            Maximum value: 5
            Default value: 3

        art_survival_hazard_ratio_who_stage_3plus(float, optional):
            The hazard ratio comparing those starting ART in WHO stage >= 3 to those in WHO stage < 3.
            Minimum value: 1e-06
            Maximum value: 1000000.0
            Default value: 2.7142

        art_survival_hazard_ratio_female(float, optional):
            The hazard ratio comparing survival female to male survival for those starting ART.
            Minimum value: 1e-06
            Maximum value: 1000000.0
            Default value: 0.6775

        art_survival_hazard_ratio_cd4_slope(float, optional):
            The slope value to sue when calculating the hazard for for the person based on their CD4 count.
            multiplier = exp(cd4_slope * cd4 + cd4_intercept)
            Minimum value: -1000000.0
            Maximum value: 1000000.0
            Default value: -0.00758256

        art_survival_hazard_ratio_cd4_intercept(float, optional):
            The Y-intercept to use when calculating the hazard ratio for the person based on their CD4 count.
            multiplier = exp(cd4_slope * cd4 + cd4_intercept)
            Minimum value: -1000000.0
            Maximum value: 1000000.0
            Default value: 0.282852

        art_survival_hazard_ratio_body_weight_kg_slope(float, optional):
            The slope to use when calculating the hazard ratio for the person's body weight.
            The body weight is determined by WHO stage:
            * WHO Stage 0 = 65.0 kg
            * WHO Stage 1-2 = 62.1 kg
            * WHO Stage 2-3 = 57.0 kg
            * WHO Stage 3-4 = 50.0 kg
            * WHO Stage 4+ = 40.1 kg
            multiplier = exp(weight_slope * weight + weight_intercept)
            Minimum value: -1000000.0
            Maximum value: 1000000.0
            Default value: -0.073153

        art_survival_hazard_ratio_body_weight_kg_intercept(float, optional):
            The Y-intercept to use when calculating the hazard ratio for the person's body weight.

            The body weight is determined by WHO stage:

            * WHO Stage 0 = 65.0 kg
            * WHO Stage 1-2 = 62.1 kg
            * WHO Stage 2-3 = 57.0 kg
            * WHO Stage 3-4 = 50.0 kg
            * WHO Stage 4+ = 40.1 kg

            multiplier = exp(weight_slope * weight + weight_intercept)
            Minimum value: -1000000.0
            Maximum value: 1000000.0
            Default value: 3.05043

        art_survival_hazard_ratio_age_over_40yr(float, optional):
            The hazard ratio comparing the survival time of those starting ART over 40 years of age compared to
            those starting ART <40 years.
            Minimum value: 1e-06
            Maximum value: 1000000.0
            Default value: 1.4309

        art_survival_baseline_hazard_weibull_shape(float, optional):
            Shape parameter for a Weibull distribution of survival time in years for a male < 40 with WHO stage
            of 1 or 2 starting ART (base case).
            Minimum value: 0
            Maximum value: 10
            Default value: 0.34

        art_survival_baseline_hazard_weibull_scale(float, optional):
            Scale parameter for a Weibull distribution of survival time in years for a male < 40 with WHO stage
            of 1 or 2 starting ART (base case).
            Minimum value: 1e-06
            Maximum value: 1000000.0
            Default value: 123.83

        art_multiplier_on_transmission_prob_per_act(float, optional):
            Multiplier acting on Base_Infectivity to determine the per-act transmission probability of a
            virally suppressed HIV+ individual.
            Minimum value: 0
            Maximum value: 1
            Default value: 0.08

        art_is_active_against_mortality_and_transmission(bool, optional):
            If set to true (1), ART will suppress viral load and extend prognosis.
            Default value: True

        art_cd4_at_initiation_saturating_reduction_in_mortality(float, optional):
            The duration from ART enrollment to on-ART HIV-cause death increases with CD4 at ART initiation up
            to a threshold determined by this parameter value. This is the maximum value that CD4 is allowed to
            have in the hazard ratio calculation for CD4.
            Minimum value: 0
            Maximum value: 3.40282e+38
            Default value: 350

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 days_to_achieve_viral_suppression: float = 183,
                 art_survival_who_stage_threshold_for_cox: float = 3,
                 art_survival_hazard_ratio_who_stage_3plus: float = 2.7142,
                 art_survival_hazard_ratio_female: float = 0.6775,
                 art_survival_hazard_ratio_cd4_slope: float = -0.00758256,
                 art_survival_hazard_ratio_cd4_intercept: float = 0.282852,
                 art_survival_hazard_ratio_body_weight_kg_slope: float = -0.073153,
                 art_survival_hazard_ratio_body_weight_kg_intercept: float = 3.05043,
                 art_survival_hazard_ratio_age_over_40yr: float = 1.4309,
                 art_survival_baseline_hazard_weibull_shape: float = 0.34,
                 art_survival_baseline_hazard_weibull_scale: float = 123.83,
                 art_multiplier_on_transmission_prob_per_act: float = 0.08,
                 art_is_active_against_mortality_and_transmission: bool = True,
                 art_cd4_at_initiation_saturating_reduction_in_mortality: float = 350,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'AntiretroviralTherapy', common_intervention_parameters)

        self._intervention.Days_To_Achieve_Viral_Suppression = validate_value_range(days_to_achieve_viral_suppression, 'days_to_achieve_viral_suppression', 0, 3.40282e+38, float)
        self._intervention.ART_Survival_WHO_Stage_Threshold_For_Cox = validate_value_range(art_survival_who_stage_threshold_for_cox, 'art_survival_who_stage_threshold_for_cox', 0, 5, float)
        self._intervention.ART_Survival_Hazard_Ratio_WHO_Stage_3Plus = validate_value_range(art_survival_hazard_ratio_who_stage_3plus, 'art_survival_hazard_ratio_who_stage_3plus', 1e-06, 1000000.0, float)
        self._intervention.ART_Survival_Hazard_Ratio_Female = validate_value_range(art_survival_hazard_ratio_female, 'art_survival_hazard_ratio_female', 1e-06, 1000000.0, float)
        self._intervention.ART_Survival_Hazard_Ratio_CD4_Slope = validate_value_range(art_survival_hazard_ratio_cd4_slope, 'art_survival_hazard_ratio_cd4_slope', -1000000.0, 1000000.0, float)
        self._intervention.ART_Survival_Hazard_Ratio_CD4_Intercept = validate_value_range(art_survival_hazard_ratio_cd4_intercept, 'art_survival_hazard_ratio_cd4_intercept', -1000000.0, 1000000.0, float)
        self._intervention.ART_Survival_Hazard_Ratio_Body_Weight_Kg_Slope = validate_value_range(art_survival_hazard_ratio_body_weight_kg_slope, 'art_survival_hazard_ratio_body_weight_kg_slope', -1000000.0, 1000000.0, float)
        self._intervention.ART_Survival_Hazard_Ratio_Body_Weight_Kg_Intercept = validate_value_range(art_survival_hazard_ratio_body_weight_kg_intercept, 'art_survival_hazard_ratio_body_weight_kg_intercept', -1000000.0, 1000000.0, float)
        self._intervention.ART_Survival_Hazard_Ratio_Age_Over_40Yr = validate_value_range(art_survival_hazard_ratio_age_over_40yr, 'art_survival_hazard_ratio_age_over_40yr', 1e-06, 1000000.0, float)
        self._intervention.ART_Survival_Baseline_Hazard_Weibull_Shape = validate_value_range(art_survival_baseline_hazard_weibull_shape, 'art_survival_baseline_hazard_weibull_shape', 0, 10, float)
        self._intervention.ART_Survival_Baseline_Hazard_Weibull_Scale = validate_value_range(art_survival_baseline_hazard_weibull_scale, 'art_survival_baseline_hazard_weibull_scale', 1e-06, 1000000.0, float)
        self._intervention.ART_Multiplier_On_Transmission_Prob_Per_Act = validate_value_range(art_multiplier_on_transmission_prob_per_act, 'art_multiplier_on_transmission_prob_per_act', 0, 1, float)
        self._intervention.ART_Is_Active_Against_Mortality_And_Transmission = 1 if art_is_active_against_mortality_and_transmission else 0
        self._intervention.ART_CD4_at_Initiation_Saturating_Reduction_in_Mortality = validate_value_range(art_cd4_at_initiation_saturating_reduction_in_mortality, 'art_cd4_at_initiation_saturating_reduction_in_mortality', 0, 3.40282e+38, float)

AntiretroviralTherapyFull

Bases: IndividualIntervention

The AntriretroviralTherapyFull intervention class begins antiretroviral therapy (ART) on the person receiving the intervention. This class is similar to the standard AntiretroviralTherapy, but enhances it with two key features: 1) a built-in delay timer such that when the delay expires, the person will come off of ART (ARTDropout should NOT be used with this intervention), and 2) persistence with the individual so the user can track this intervention using ReferenceTrackingEventCoordinator.

Additional considerations when using this intervention

• The model will not allow someone who is HIV negative to be put on ART.
• A person who has not previously been on ART is considered to be 'starting ART' at the time this intervention is applied; the model will track this start time/duration.
• If a person is already on ART from another intervention, receiving a second ART intervention will have no effect.
• If a person is on already ART and receives the ARTMortalityTable intervention, the original ART start time will be used to calculate the duration from enrollment to ART AIDS Death. The duration since starting ART will not change; it will continue to increase.
• If a person is on ART and receives the ARTDropout intervention, the person will go off ART and the duration will be reset; if receiving a new ART intervention, this new start time/duration will be used in any calculations.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
time_on_art_distribution	(BaseDistribution, required)	The type of distribution to use when determine how long a person will be on ART. Please use the following distribution classes from emodpy_hiv.utils.distributions to define the distribution: * ConstantDistribution * UniformDistribution * GaussianDistribution * ExponentialDistribution * PoissonDistribution * LogNormalDistribution * DualConstantDistribution * WeibullDistribution * DualExponentialDistribution	required
stop_art_event	str	This event is broadcast when the person drops off ART. This could happen either via the timer running out or the intervention detected a disqualifying property. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	None
days_to_achieve_viral_suppression	float	The number of days after ART initiation over which infectiousness declines linearly until the ART_Multiplier_On_Transmission_Prob_Per_Act takes full effect. Minimum value: 0 Maximum value: 3.40282e+38 Default value: 183	183
art_survival_who_stage_threshold_for_cox	float	If the person receiving ART has a WHO Stage greater than or equal to this threshold, then use the hazard ratio determined by the parameter ART_Survival_Hazard_Ratio_WHO_Stage_3Plus. Minimum value: 0 Maximum value: 5 Default value: 3	3
art_survival_hazard_ratio_who_stage_3plus	float	The hazard ratio comparing those starting ART in WHO stage >= 3 to those in WHO stage < 3. Minimum value: 1e-06 Maximum value: 1000000.0 Default value: 2.7142	2.7142
art_survival_hazard_ratio_female	float	The hazard ratio comparing survival female to male survival for those starting ART. Minimum value: 1e-06 Maximum value: 1000000.0 Default value: 0.6775	0.6775
art_survival_hazard_ratio_cd4_slope	float	The slope value to sue when calculating the hazard for for the person based on their CD4 count. multiplier = exp(cd4_slope * cd4 + cd4_intercept) Minimum value: -1000000.0 Maximum value: 1000000.0 Default value: -0.00758256	-0.00758256
art_survival_hazard_ratio_cd4_intercept	float	The Y-intercept to use when calculating the hazard ratio for the person based on their CD4 count. multiplier = exp(cd4_slope * cd4 + cd4_intercept) Minimum value: -1000000.0 Maximum value: 1000000.0 Default value: 0.282852	0.282852
art_survival_hazard_ratio_body_weight_kg_slope	float	The slope to use when calculating the hazard ratio for the person's body weight. The body weight is determined by WHO stage: * WHO Stage 0 = 65.0 kg * WHO Stage 1-2 = 62.1 kg * WHO Stage 2-3 = 57.0 kg * WHO Stage 3-4 = 50.0 kg * WHO Stage 4+ = 40.1 kg multiplier = exp(weight_slope * weight + weight_intercept) Minimum value: -1000000.0 Maximum value: 1000000.0 Default value: -0.073153	-0.073153
art_survival_hazard_ratio_body_weight_kg_intercept	float	The Y-intercept to use when calculating the hazard ratio for the person's body weight. The body weight is determined by WHO stage: WHO Stage 0 = 65.0 kg WHO Stage 1-2 = 62.1 kg WHO Stage 2-3 = 57.0 kg WHO Stage 3-4 = 50.0 kg WHO Stage 4+ = 40.1 kg multiplier = exp(weight_slope * weight + weight_intercept) Minimum value: -1000000.0 Maximum value: 1000000.0 Default value: 3.05043	3.05043
art_survival_hazard_ratio_age_over_40yr	float	The hazard ratio comparing the survival time of those starting ART over 40 years of age compared to those starting ART <40 years. Minimum value: 1e-06 Maximum value: 1000000.0 Default value: 1.4309	1.4309
art_survival_baseline_hazard_weibull_shape	float	Shape parameter for a Weibull distribution of survival time in years for a male < 40 with WHO stage of 1 or 2 starting ART (base case). Minimum value: 0 Maximum value: 10 Default value: 0.34	0.34
art_survival_baseline_hazard_weibull_scale	float	Scale parameter for a Weibull distribution of survival time in years for a male < 40 with WHO stage of 1 or 2 starting ART (base case). Minimum value: 1e-06 Maximum value: 1000000.0 Default value: 123.83	123.83
art_multiplier_on_transmission_prob_per_act	float	Multiplier acting on Base_Infectivity to determine the per-act transmission probability of a virally suppressed HIV+ individual. Minimum value: 0 Maximum value: 1 Default value: 0.08	0.08
art_is_active_against_mortality_and_transmission	bool	If set to true (1), ART will suppress viral load and extend prognosis. Default value: True	True
art_cd4_at_initiation_saturating_reduction_in_mortality	float	The duration from ART enrollment to on-ART HIV-cause death increases with CD4 at ART initiation up to a threshold determined by this parameter value. This is the maximum value that CD4 is allowed to have in the hazard ratio calculation for CD4. Minimum value: 0 Maximum value: 3.40282e+38 Default value: 350	350
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class AntiretroviralTherapyFull(IndividualIntervention):
    """
    The **AntriretroviralTherapyFull** intervention class begins antiretroviral therapy (ART) on the person
    receiving the intervention. This class is similar to the standard AntiretroviralTherapy, but enhances
    it with two key features: 1) a built-in delay timer such that when the delay expires, the person will
    come off of ART (**ARTDropout** should NOT be used with this intervention), and 2) persistence with the
    individual so the user can track this intervention using ReferenceTrackingEventCoordinator.

    Additional considerations when using this intervention:
        - The model will not allow someone who is HIV negative to be put on ART.
        - A person who has not previously been on ART is considered to be 'starting ART' at the time this
          intervention is applied; the model will track this start time/duration.
        - If a person is already on ART from another intervention, receiving a second ART intervention will
          have no effect.
        - If a person is on already ART and receives the ARTMortalityTable intervention, the original ART
          start time will be used to calculate the duration from enrollment to ART AIDS Death. The duration
          since starting ART will not change; it will continue to increase.
        - If a person is on ART and receives the **ARTDropout** intervention, the person will go off ART and
          the duration will be reset; if receiving a new ART intervention, this new start time/duration will
          be used in any calculations.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        time_on_art_distribution(BaseDistribution, required):
            The type of distribution to use when determine how long a person will be on ART.
            Please use the following distribution classes from emodpy_hiv.utils.distributions
            to define the distribution:
            * ConstantDistribution
            * UniformDistribution
            * GaussianDistribution
            * ExponentialDistribution
            * PoissonDistribution
            * LogNormalDistribution
            * DualConstantDistribution
            * WeibullDistribution
            * DualExponentialDistribution

        stop_art_event(str, optional):
            This event is broadcast when the person drops off ART. This could happen either via the timer
            running out or the intervention detected a disqualifying property.  See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
            Default value: None

        days_to_achieve_viral_suppression(float, optional):
            The number of days after ART initiation over which infectiousness declines linearly until the
            **ART_Multiplier_On_Transmission_Prob_Per_Act** takes full effect.
            Minimum value: 0
            Maximum value: 3.40282e+38
            Default value: 183

        art_survival_who_stage_threshold_for_cox(float, optional):
            If the person receiving ART has a WHO Stage greater than or equal to this threshold, then use the
            hazard ratio determined by the parameter **ART_Survival_Hazard_Ratio_WHO_Stage_3Plus**.
            Minimum value: 0
            Maximum value: 5
            Default value: 3

        art_survival_hazard_ratio_who_stage_3plus(float, optional):
            The hazard ratio comparing those starting ART in WHO stage >= 3 to those in WHO stage < 3.
            Minimum value: 1e-06
            Maximum value: 1000000.0
            Default value: 2.7142

        art_survival_hazard_ratio_female(float, optional):
            The hazard ratio comparing survival female to male survival for those starting ART.
            Minimum value: 1e-06
            Maximum value: 1000000.0
            Default value: 0.6775

        art_survival_hazard_ratio_cd4_slope(float, optional):
            The slope value to sue when calculating the hazard for for the person based on their CD4 count.
            multiplier = exp(cd4_slope * cd4 + cd4_intercept)
            Minimum value: -1000000.0
            Maximum value: 1000000.0
            Default value: -0.00758256

        art_survival_hazard_ratio_cd4_intercept(float, optional):
            The Y-intercept to use when calculating the hazard ratio for the person based on their CD4 count.
            multiplier = exp(cd4_slope * cd4 + cd4_intercept)
            Minimum value: -1000000.0
            Maximum value: 1000000.0
            Default value: 0.282852

        art_survival_hazard_ratio_body_weight_kg_slope(float, optional):
            The slope to use when calculating the hazard ratio for the person's body weight.
            The body weight is determined by WHO stage:
            * WHO Stage 0 = 65.0 kg
            * WHO Stage 1-2 = 62.1 kg
            * WHO Stage 2-3 = 57.0 kg
            * WHO Stage 3-4 = 50.0 kg
            * WHO Stage 4+ = 40.1 kg
            multiplier = exp(weight_slope * weight + weight_intercept)
            Minimum value: -1000000.0
            Maximum value: 1000000.0
            Default value: -0.073153

        art_survival_hazard_ratio_body_weight_kg_intercept(float, optional):
            The Y-intercept to use when calculating the hazard ratio for the person's body weight.

            The body weight is determined by WHO stage:

            * WHO Stage 0 = 65.0 kg
            * WHO Stage 1-2 = 62.1 kg
            * WHO Stage 2-3 = 57.0 kg
            * WHO Stage 3-4 = 50.0 kg
            * WHO Stage 4+ = 40.1 kg

            multiplier = exp(weight_slope * weight + weight_intercept)
            Minimum value: -1000000.0
            Maximum value: 1000000.0
            Default value: 3.05043

        art_survival_hazard_ratio_age_over_40yr(float, optional):
            The hazard ratio comparing the survival time of those starting ART over 40 years of age compared to
            those starting ART <40 years.
            Minimum value: 1e-06
            Maximum value: 1000000.0
            Default value: 1.4309

        art_survival_baseline_hazard_weibull_shape(float, optional):
            Shape parameter for a Weibull distribution of survival time in years for a male < 40 with WHO stage
            of 1 or 2 starting ART (base case).
            Minimum value: 0
            Maximum value: 10
            Default value: 0.34

        art_survival_baseline_hazard_weibull_scale(float, optional):
            Scale parameter for a Weibull distribution of survival time in years for a male < 40 with WHO stage
            of 1 or 2 starting ART (base case).
            Minimum value: 1e-06
            Maximum value: 1000000.0
            Default value: 123.83

        art_multiplier_on_transmission_prob_per_act(float, optional):
            Multiplier acting on Base_Infectivity to determine the per-act transmission probability of a
            virally suppressed HIV+ individual.
            Minimum value: 0
            Maximum value: 1
            Default value: 0.08

        art_is_active_against_mortality_and_transmission(bool, optional):
            If set to true (1), ART will suppress viral load and extend prognosis.
            Default value: True

        art_cd4_at_initiation_saturating_reduction_in_mortality(float, optional):
            The duration from ART enrollment to on-ART HIV-cause death increases with CD4 at ART initiation up
            to a threshold determined by this parameter value. This is the maximum value that CD4 is allowed to
            have in the hazard ratio calculation for CD4.
            Minimum value: 0
            Maximum value: 3.40282e+38
            Default value: 350

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 time_on_art_distribution: BaseDistribution,
                 stop_art_event: str = None,
                 days_to_achieve_viral_suppression: float = 183,
                 art_survival_who_stage_threshold_for_cox: float = 3,
                 art_survival_hazard_ratio_who_stage_3plus: float = 2.7142,
                 art_survival_hazard_ratio_female: float = 0.6775,
                 art_survival_hazard_ratio_cd4_slope: float = -0.00758256,
                 art_survival_hazard_ratio_cd4_intercept: float = 0.282852,
                 art_survival_hazard_ratio_body_weight_kg_slope: float = -0.073153,
                 art_survival_hazard_ratio_body_weight_kg_intercept: float = 3.05043,
                 art_survival_hazard_ratio_age_over_40yr: float = 1.4309,
                 art_survival_baseline_hazard_weibull_shape: float = 0.34,
                 art_survival_baseline_hazard_weibull_scale: float = 123.83,
                 art_multiplier_on_transmission_prob_per_act: float = 0.08,
                 art_is_active_against_mortality_and_transmission: bool = True,
                 art_cd4_at_initiation_saturating_reduction_in_mortality: float = 350,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'AntiretroviralTherapyFull', common_intervention_parameters)

        if not isinstance(time_on_art_distribution, BaseDistribution):
            raise ValueError(f"time_on_art_distribution must be an instance of BaseDistribution, not {type(time_on_art_distribution)}.")
        self.set_distribution(time_on_art_distribution, 'Time_On_ART')

        self._intervention.Stop_ART_Event = set_event(stop_art_event, 'stop_art_event', campaign, True)
        self._intervention.Days_To_Achieve_Viral_Suppression = validate_value_range(days_to_achieve_viral_suppression, 'days_to_achieve_viral_suppression', 0, 3.40282e+38, float)
        self._intervention.ART_Survival_WHO_Stage_Threshold_For_Cox = validate_value_range(art_survival_who_stage_threshold_for_cox, 'art_survival_who_stage_threshold_for_cox', 0, 5, float)
        self._intervention.ART_Survival_Hazard_Ratio_WHO_Stage_3Plus = validate_value_range(art_survival_hazard_ratio_who_stage_3plus, 'art_survival_hazard_ratio_who_stage_3plus', 1e-06, 1000000.0, float)
        self._intervention.ART_Survival_Hazard_Ratio_Female = validate_value_range(art_survival_hazard_ratio_female, 'art_survival_hazard_ratio_female', 1e-06, 1000000.0, float)
        self._intervention.ART_Survival_Hazard_Ratio_CD4_Slope = validate_value_range(art_survival_hazard_ratio_cd4_slope, 'art_survival_hazard_ratio_cd4_slope', -1000000.0, 1000000.0, float)
        self._intervention.ART_Survival_Hazard_Ratio_CD4_Intercept = validate_value_range(art_survival_hazard_ratio_cd4_intercept, 'art_survival_hazard_ratio_cd4_intercept', -1000000.0, 1000000.0, float)
        self._intervention.ART_Survival_Hazard_Ratio_Body_Weight_Kg_Slope = validate_value_range(art_survival_hazard_ratio_body_weight_kg_slope, 'art_survival_hazard_ratio_body_weight_kg_slope', -1000000.0, 1000000.0, float)
        self._intervention.ART_Survival_Hazard_Ratio_Body_Weight_Kg_Intercept = validate_value_range(art_survival_hazard_ratio_body_weight_kg_intercept, 'art_survival_hazard_ratio_body_weight_kg_intercept', -1000000.0, 1000000.0, float)
        self._intervention.ART_Survival_Hazard_Ratio_Age_Over_40Yr = validate_value_range(art_survival_hazard_ratio_age_over_40yr, 'art_survival_hazard_ratio_age_over_40yr', 1e-06, 1000000.0, float)
        self._intervention.ART_Survival_Baseline_Hazard_Weibull_Shape = validate_value_range(art_survival_baseline_hazard_weibull_shape, 'art_survival_baseline_hazard_weibull_shape', 0, 10, float)
        self._intervention.ART_Survival_Baseline_Hazard_Weibull_Scale = validate_value_range(art_survival_baseline_hazard_weibull_scale, 'art_survival_baseline_hazard_weibull_scale', 1e-06, 1000000.0, float)
        self._intervention.ART_Multiplier_On_Transmission_Prob_Per_Act = validate_value_range(art_multiplier_on_transmission_prob_per_act, 'art_multiplier_on_transmission_prob_per_act', 0, 1, float)
        self._intervention.ART_Is_Active_Against_Mortality_And_Transmission = 1 if art_is_active_against_mortality_and_transmission else 0
        self._intervention.ART_CD4_at_Initiation_Saturating_Reduction_in_Mortality = validate_value_range(art_cd4_at_initiation_saturating_reduction_in_mortality, 'art_cd4_at_initiation_saturating_reduction_in_mortality', 0, 3.40282e+38, float)

CD4Diagnostic

Bases: IndividualIntervention

The CD4Diagnostic allows you to have different things happen to a person based on their actual CD4 count. For example, if a person was given an HIVRapidDiagnostic and tested positive, you could give that person the CD4Diagnositic. The diagnostic would broadcast different events based on their current CD4 count. If the CD4 count was high, you could broadcast an event that would give the person a delay that would have the person re-test in three months. If the CD4 count was low, you could broadcast an event that would cause them to go on ART immediately.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
cd4_thresholds	list[RangeThreshold]	This parameter associates ranges of CD4 counts with events that should occur for individuals whose CD4 counts fall into those ranges. Default value: None	None
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class CD4Diagnostic(IndividualIntervention):
    """
    The **CD4Diagnostic** allows you to have different things happen to a person based on their actual CD4 count.
    For example, if a person was given an HIVRapidDiagnostic and tested positive, you could give that person
    the **CD4Diagnositic**.  The diagnostic would broadcast different events based on their current CD4 count.
    If the CD4 count was high, you could broadcast an event that would give the person a delay that would have
    the person re-test in three months.  If the CD4 count was low, you could broadcast an event that would cause
    them to go on ART immediately.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        cd4_thresholds(list[RangeThreshold], optional):
            This parameter associates ranges of CD4 counts with events that should occur for individuals whose
            CD4 counts fall into those ranges.
            Default value: None

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 cd4_thresholds: list[RangeThreshold] = None,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'CD4Diagnostic', common_intervention_parameters)

        for ct in cd4_thresholds:
            self._intervention.CD4_Thresholds.append(ct.to_schema_dict(campaign))

CoitalActRiskFactors

Bases: IndividualIntervention

The CoitalActRiskFactors intervention class provides a method of modifying an individual's risk/probability of acquiring or transmitting an STI. If other risk multipliers are active (across other interventions), the values will be multiplied together; the resulting value will be multiplied with any active STI co-infection factors. When the intervention expires, the individual's risk factor multiplier returns to one. Since this intervention persists, it can be used with Distributors.add_intervention_tracker(). NOTE: An individual can have multiple of these interventions with each one being multiplied times the other.

The risk multiplier for a coital act has three contributions:

1. *Coital Act Risk Factors* - The factors from the use of this intervention.

2. *Co-Infection* - A person can get a co-infection by using the **ModifyStiCoInfectionStatus**
   intervention.  If the person has a co-infection, then the configuration paameters **STI_Coinfection_Transmission_Multiplier**
   or **STI_Coinfection_Acquisition_Multiplier** depending on whether the person has HIV (transmitter)
   or not (aquirer).  The maximum value of the multiplier between the transmitter and acquirer is used.

3. *Condom Transmission Blocking* - If condoms were used in this coital act, then the
   configuration parameter **Condom_Transmission_Blocking_Probability** is included.

The value of the multiplier is calculated as follows:

>>> co_inf_transmission = infected_individual.STI_Coinfection_Transmission_Multiplier if co-infected else 1
>>> co_inf_acquisition  = uninfected_individual.STI_Coinfection_Acquisition_Multiplier if co-infected else 1
>>> risk_multiplier = max( co_inf_transmission, co_inf_acquisition )
>>>
>>> risk_factor_transmission = infected_individual.CoitalActsRiskFactors.Transmission_Multiplier
>>> risk_factor_acquisition = uninfected_individual.CoitalActsRiskFactors.Acquisition_Multiplier
>>> risk_multiplier *= risk_factor_transmission * risk_factor_acquisition;
>>>
>>> risk_multiplier *= (1 - Condom_Transmission_Blocking_Probability) if using_condom else 1

This risk multiplier is then used to determine if the uninfected person becomes infected:

>>> probability_infected = risk_multiplier
>>>                      * transmission_probability
>>>                      * acquisition_probability

Acquisition Probability

There are three things that contribute to the probability that an uninfected person can acquire HIV from a coital act with an infected person. They are:

1. *Male Circumcision* - If the uninfected person is male and has been circumcised, their probability
   of acquisition is reduced.  The male individual will have the **MaleCircumcision** intervention and its
   **Circumcision_Reduced_Acquire** parameter will be used.

2. *Female Susceptibility By Age* - If the uninfected person is female, then their current age is used
   to determine the a factor from the configuration parameters **Male_To_Female_Relative_Infectivity_Ages**
   and **Male_To_Female_Relative_Infectivity_Multipliers**.  Their age is used with linear interpolation
   to calculate a multiplier.

3. *PrEP / Vaccine* - If the uninfected person has a vaccine or PrEP, their probability of acquisition
   is also reduced.

>>> probability_acquire = 1.0
>>> probability_acquire *= MaleCircumcision.Circumcision_Reduced_Acquire if male and circumcised else 1
>>> probability_acquire *= get_female_susceptibility( person.age ) if female else 1
>>> probability_acquire *= vaccine_reduced_acquire if person has vaccine else 1

Transmission Probability

In EMOD, the probability of a person transmitting HIV comes down to whether nor not the person has been vaccinated and how infectious they are.

1. *Vaccine* - If the infected person has a vaccine that reduces transmission, its probability of
   transmission reduction is used.

2. *Infectiousness* - The infectiousness of a person depends on the following four factors:

    2a. *Base Infectivity* - The configuration parameter **Base_Infectivity** determines the starting
    amount of infectiousness. It is the starting point of the calculation and is assumed to be
    female-to-male transmission.

    2b. *Heterogeneity* - To represent the heterogeneity in people, the **Base_Infectivity** is
    multiplied by a value from a Log Normal distribution based on the configuration parameter
    **Heterogeneous_Infectiousness_LogNormal_Scale**.

        >>> median = -0.5 * Heterogeneous_Infectiousness_LogNormal_Scale**2
        >>> heterogeneity_factor = median + eGauss() * Heterogeneous_Infectiousness_LogNormal_Scale

    where eGauss() is a gaussian distributed random number between 0 and 1.

    2c. *Stage of Infection* - The mount the infection has progressed also impacts the amount of
    infectiousness.  If the person is in the 'acute' stage, then we multiply the **Base_Infectivity**
    times the configuration parameter **Acute_Stage_Infectivity_Multiplier**.  If the person is in
    the 'AIDS' stage, we multiply by the configuration parameter **AIDS_Stage_Infectivity_Multiplier**.
    If they are in the 'latent' stage, we do not adjust the **Base_Infectivity**.

    2d. *ART Suppression* - If a person has been given an ART intervention (**AntiretroviralTherapy**,
    **AntiretroviralTherapyFull**, or **ARTMortalityTable**) and has not dropped off of art (**ARTDropout**),
    then ART can suppress the person's infectiousness.  This amount of suppression is determined by
    the intervention parameters **ART_Multiplier_On_Transmission_Prob_Per_Act** and
    **Days_To_Achieve_Viral_Suppression**.  If the person has been on ART less than
    **Days_To_Achieve_Viral_Suppression**, the **ART_Multiplier_On_Transmission_Prob_Per_Act**
    will be reduced proportionally.

These different factors are combined as follows:

    >>> infectiousness = Base_Infectivity
    >>> infectiousness *= heterogeneity_factor
    >>>
    >>> if hiv_stage == ACUTE:
    >>>     infectiousness *= Acute_Stage_Infectivity_Multiplier
    >>> elif hiv_stage == AIDS:
    >>>     infectiousness *= AIDS_Stage_Infectivity_Multiplier
    >>>
    >>> suppression = ART_Multiplier_On_Transmission_Prob_Per_Act
    >>> if Days_To_Achieve_Viral_Suppression > 0:
    >>>     art_mult = ART_Multiplier_On_Transmission_Prob_Per_Act
    >>>     days_to_achieve = Days_To_Achieve_Viral_Suppression
    >>>     suppression = 1 - ((1 - art_mult) / days_to_achieve) * time_since_starting_ART
    >>> infectiousness *= suppression

The transmission probability is then calculated as:

>>> probability_transmission = infectiousness * vaccine_reduced_transmission

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
transmission_multiplier	float	Multiplier for STI transmission probability per coital act. Minimum value: 0 Maximum value: 100 Default value: 1	1
expiration_period_distribution	(BaseDistribution, required)	The distribution type to use for setting the expiration of the intervention. Each intervention gets an expiration duration by doing a random draw from the distribution. Please use the following distribution classes from emodpy_hiv.utils.distributions to define the distribution: * ConstantDistribution * UniformDistribution * GaussianDistribution * ExponentialDistribution * PoissonDistribution * LogNormalDistribution * DualConstantDistribution * WeibullDistribution * DualExponentialDistribution	required
expiration_event_trigger	str	When the intervention expires, this individual-level event will be broadcast. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	None
acquisition_multiplier	float	Multiplier for STI acquisition probability per coital act. Minimum value: 0 Maximum value: 100 Default value: 1	1
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class CoitalActRiskFactors(IndividualIntervention):
    """
    The **CoitalActRiskFactors** intervention class provides a method of modifying an individual's
    risk/probability of acquiring or transmitting an STI. If other risk multipliers are active
    (across other interventions), the values will be multiplied together; the resulting value
    will be multiplied with any active STI co-infection factors. When the intervention expires,
    the individual's risk factor multiplier returns to one. Since this intervention persists,
    it can be used with Distributors.add_intervention_tracker(). NOTE: An individual can have
    multiple of these interventions with each one being multiplied times the other.

    The risk multiplier for a coital act has three contributions:

        1. *Coital Act Risk Factors* - The factors from the use of this intervention.

        2. *Co-Infection* - A person can get a co-infection by using the **ModifyStiCoInfectionStatus**
           intervention.  If the person has a co-infection, then the configuration paameters **STI_Coinfection_Transmission_Multiplier**
           or **STI_Coinfection_Acquisition_Multiplier** depending on whether the person has HIV (transmitter)
           or not (aquirer).  The maximum value of the multiplier between the transmitter and acquirer is used.

        3. *Condom Transmission Blocking* - If condoms were used in this coital act, then the
           configuration parameter **Condom_Transmission_Blocking_Probability** is included.

    The value of the multiplier is calculated as follows:

        >>> co_inf_transmission = infected_individual.STI_Coinfection_Transmission_Multiplier if co-infected else 1
        >>> co_inf_acquisition  = uninfected_individual.STI_Coinfection_Acquisition_Multiplier if co-infected else 1
        >>> risk_multiplier = max( co_inf_transmission, co_inf_acquisition )
        >>>
        >>> risk_factor_transmission = infected_individual.CoitalActsRiskFactors.Transmission_Multiplier
        >>> risk_factor_acquisition = uninfected_individual.CoitalActsRiskFactors.Acquisition_Multiplier
        >>> risk_multiplier *= risk_factor_transmission * risk_factor_acquisition;
        >>>
        >>> risk_multiplier *= (1 - Condom_Transmission_Blocking_Probability) if using_condom else 1

    This risk multiplier is then used to determine if the uninfected person becomes infected:

        >>> probability_infected = risk_multiplier
        >>>                      * transmission_probability
        >>>                      * acquisition_probability

    **Acquisition Probability**

    There are three things that contribute to the probability that an uninfected person can acquire HIV
    from a coital act with an infected person.  They are:

        1. *Male Circumcision* - If the uninfected person is male and has been circumcised, their probability
           of acquisition is reduced.  The male individual will have the **MaleCircumcision** intervention and its
           **Circumcision_Reduced_Acquire** parameter will be used.

        2. *Female Susceptibility By Age* - If the uninfected person is female, then their current age is used
           to determine the a factor from the configuration parameters **Male_To_Female_Relative_Infectivity_Ages**
           and **Male_To_Female_Relative_Infectivity_Multipliers**.  Their age is used with linear interpolation
           to calculate a multiplier.

        3. *PrEP / Vaccine* - If the uninfected person has a vaccine or PrEP, their probability of acquisition
           is also reduced.

        >>> probability_acquire = 1.0
        >>> probability_acquire *= MaleCircumcision.Circumcision_Reduced_Acquire if male and circumcised else 1
        >>> probability_acquire *= get_female_susceptibility( person.age ) if female else 1
        >>> probability_acquire *= vaccine_reduced_acquire if person has vaccine else 1

    **Transmission Probability**

    In EMOD, the probability of a person transmitting HIV comes down to whether nor not the person has been
    vaccinated and how infectious they are.

        1. *Vaccine* - If the infected person has a vaccine that reduces transmission, its probability of
           transmission reduction is used.

        2. *Infectiousness* - The infectiousness of a person depends on the following four factors:

            2a. *Base Infectivity* - The configuration parameter **Base_Infectivity** determines the starting
            amount of infectiousness. It is the starting point of the calculation and is assumed to be
            female-to-male transmission.

            2b. *Heterogeneity* - To represent the heterogeneity in people, the **Base_Infectivity** is
            multiplied by a value from a Log Normal distribution based on the configuration parameter
            **Heterogeneous_Infectiousness_LogNormal_Scale**.

                >>> median = -0.5 * Heterogeneous_Infectiousness_LogNormal_Scale**2
                >>> heterogeneity_factor = median + eGauss() * Heterogeneous_Infectiousness_LogNormal_Scale

            where eGauss() is a gaussian distributed random number between 0 and 1.

            2c. *Stage of Infection* - The mount the infection has progressed also impacts the amount of
            infectiousness.  If the person is in the 'acute' stage, then we multiply the **Base_Infectivity**
            times the configuration parameter **Acute_Stage_Infectivity_Multiplier**.  If the person is in
            the 'AIDS' stage, we multiply by the configuration parameter **AIDS_Stage_Infectivity_Multiplier**.
            If they are in the 'latent' stage, we do not adjust the **Base_Infectivity**.

            2d. *ART Suppression* - If a person has been given an ART intervention (**AntiretroviralTherapy**,
            **AntiretroviralTherapyFull**, or **ARTMortalityTable**) and has not dropped off of art (**ARTDropout**),
            then ART can suppress the person's infectiousness.  This amount of suppression is determined by
            the intervention parameters **ART_Multiplier_On_Transmission_Prob_Per_Act** and
            **Days_To_Achieve_Viral_Suppression**.  If the person has been on ART less than
            **Days_To_Achieve_Viral_Suppression**, the **ART_Multiplier_On_Transmission_Prob_Per_Act**
            will be reduced proportionally.

        These different factors are combined as follows:

            >>> infectiousness = Base_Infectivity
            >>> infectiousness *= heterogeneity_factor
            >>>
            >>> if hiv_stage == ACUTE:
            >>>     infectiousness *= Acute_Stage_Infectivity_Multiplier
            >>> elif hiv_stage == AIDS:
            >>>     infectiousness *= AIDS_Stage_Infectivity_Multiplier
            >>>
            >>> suppression = ART_Multiplier_On_Transmission_Prob_Per_Act
            >>> if Days_To_Achieve_Viral_Suppression > 0:
            >>>     art_mult = ART_Multiplier_On_Transmission_Prob_Per_Act
            >>>     days_to_achieve = Days_To_Achieve_Viral_Suppression
            >>>     suppression = 1 - ((1 - art_mult) / days_to_achieve) * time_since_starting_ART
            >>> infectiousness *= suppression

    The transmission probability is then calculated as:

        >>> probability_transmission = infectiousness * vaccine_reduced_transmission

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        transmission_multiplier(float, optional):
            Multiplier for STI transmission probability per coital act.
            Minimum value: 0
            Maximum value: 100
            Default value: 1

        expiration_period_distribution(BaseDistribution, required):
            The distribution type to use for setting the expiration of the intervention. Each intervention gets
            an expiration duration by doing a random draw from the distribution.  Please use the following
            distribution classes from emodpy_hiv.utils.distributions to define the distribution:
            * ConstantDistribution
            * UniformDistribution
            * GaussianDistribution
            * ExponentialDistribution
            * PoissonDistribution
            * LogNormalDistribution
            * DualConstantDistribution
            * WeibullDistribution
            * DualExponentialDistribution

        expiration_event_trigger(str, optional):
            When the intervention expires, this individual-level event will be broadcast. See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
            Default value: None

        acquisition_multiplier(float, optional):
            Multiplier for STI acquisition probability per coital act.
            Minimum value: 0
            Maximum value: 100
            Default value: 1

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 expiration_period_distribution: BaseDistribution,
                 transmission_multiplier: float = 1,
                 expiration_event_trigger: str = None,
                 acquisition_multiplier: float = 1,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'CoitalActRiskFactors', common_intervention_parameters)

        self._intervention.Transmission_Multiplier = validate_value_range(transmission_multiplier, 'transmission_multiplier', 0, 100, float)
        self._intervention.Expiration_Event_Trigger = set_event(expiration_event_trigger, 'expiration_event_trigger', campaign, True)
        self._intervention.Acquisition_Multiplier = validate_value_range(acquisition_multiplier, 'acquisition_multiplier', 0, 100, float)

        if not isinstance(expiration_period_distribution, BaseDistribution):
            raise ValueError(f"expiration_period_distribution must be an instance of BaseDistribution, not {type(expiration_period_distribution)}.")
        self.set_distribution(expiration_period_distribution, 'Expiration_Period')

FemaleContraceptive

Bases: IndividualIntervention

The FemaleContraceptive intervention is used to reduce the fertility rate of females of reproductive age (14 to 45 years old), based on a distribution set by the user. This intervention can only be distributed to females, and ignores the waning condition expiration (as women could still use a contraceptive, even if it is ineffective). Note: the Birth_Rate_Dependence configuration parameter must be set to INDIVIDUAL_PREGNANCIES or INDIVIDUAL_PREGNANCIES_BY_AGE_AND_YEAR or an error will result.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
waning_config	(AbstractWaningConfig, required)	A WaningConfig object used to control the efficacy of the contraceptive, typically over time. Specify how this effect decays over time using one of the Waning Config classes in emodpy_hiv.campaign.waning_config.	required
usage_expiration_event	str	When the woman stops using the contraceptive, this event will be broadcast. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	required
usage_duration_distribution	(BaseDistribution, required)	For the distribution of each contraceptive, a randomly selected duration from this distribution will determine when the woman stops using the contraceptive. This is independent of how long the contraceptive is effective. Please use the following distribution classes from emodpy_hiv.utils.distributions to define the distribution: * ConstantDistribution * UniformDistribution * GaussianDistribution * ExponentialDistribution * PoissonDistribution * LogNormalDistribution * DualConstantDistribution * WeibullDistribution * DualExponentialDistribution	required
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class FemaleContraceptive(IndividualIntervention):
    """
    The **FemaleContraceptive** intervention is used to reduce the fertility rate of females of reproductive age
    (14 to 45 years old), based on a distribution set by the user. This intervention can only be distributed to
    females, and ignores the waning condition expiration (as women could still use a contraceptive, even if it
    is ineffective). Note: the Birth_Rate_Dependence configuration parameter must be set to
    INDIVIDUAL_PREGNANCIES or INDIVIDUAL_PREGNANCIES_BY_AGE_AND_YEAR or an error will result.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        waning_config(AbstractWaningConfig, required):
            A WaningConfig object used to control the efficacy of the contraceptive, typically over time.
            Specify how this effect decays over time using one of the Waning Config classes in
            emodpy_hiv.campaign.waning_config.

        usage_expiration_event(str, optional):
            When the woman stops using the contraceptive, this event will be broadcast. See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
            Default value: None

        usage_duration_distribution(BaseDistribution, required):
            For the distribution of each contraceptive, a randomly selected duration from this distribution
            will determine when the woman stops using the contraceptive.  This is independent of how long the
            contraceptive is effective. Please use the following distribution classes
            from emodpy_hiv.utils.distributions to define the distribution:
            * ConstantDistribution
            * UniformDistribution
            * GaussianDistribution
            * ExponentialDistribution
            * PoissonDistribution
            * LogNormalDistribution
            * DualConstantDistribution
            * WeibullDistribution
            * DualExponentialDistribution

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 waning_config: AbstractWaningConfig,
                 usage_expiration_event: str,
                 usage_duration_distribution: BaseDistribution,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'FemaleContraceptive', common_intervention_parameters)
        if not isinstance(waning_config, AbstractWaningConfig):
            raise ValueError(f"waning_config must be an instance of AbstractWaningConfig, not {type(waning_config)}.")
        self._intervention.Waning_Config = waning_config.to_schema_dict(campaign)
        self._intervention.Usage_Expiration_Event = set_event(usage_expiration_event, 'usage_expiration_event', campaign, True)
        if not isinstance(usage_duration_distribution, BaseDistribution):
            raise ValueError(f"usage_duration_distribution must be an instance of BaseDistribution, not {type(usage_duration_distribution)}.")
        self.set_distribution(usage_duration_distribution, 'Usage_Duration')

HIVARTStagingByCD4Diagnostic

Bases: IndividualIntervention

The HIVARTStagingByCD4Diagnostic intervention class checks for treatment eligibility based on CD4 count. It uses the lowest-ever recorded CD4 count for that individual, based on the history of past CD4 counts conducted using the HIVDrawBlood intervention. To specify the outcome based on age bins instead of CD4 testing, use HIVARTStagingCD4AgnosticDiagnostic.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
cd4_threshold	(ValueMap, required)	It is a piecewise table of years to CD4 and the individual's CD4 count must be below this threshold in order to get a positive 'diagnosis'.	required
if_pregnant	(ValueMap, required)	If the individual does not pass the diagnostic from the cd4_threshold or if_active_TB, and the individual is pregnant, then the individual's CD4 is compared to the value found in the ValueMap matrix.	required
if_active_tb	(ValueMap, required)	If the individual's CD4 is not below the threshold in the cd4_threshold table and the individual has TB, then the individual's CD4 will be compared to the CD4 value retrieved from the ValueMap matrix based on the current year. Whether a person has TB is determined by the value of an Individual Property as determined by the parameters individual_property_active_tb_key(typically 'HasActiveTB') and individual_property_active_tb_value(typically 'Yes').	required
positive_diagnosis_event	(str, required)	If the test is positive, this specifies an event that will be broadcast. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event.	required
negative_diagnosis_event	str	If the test is negative, this specifies an event that will be broadcast. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	None
individual_property_active_tb_value	str	The IndividualProperty value ('Yes') used to determine whether the individual has TB. If you want to use this feature, you will need to define the property in the demographics Default value: None	None
individual_property_active_tb_key	str	The IndividualProperty key ('HasActiveTB') used to determine whether the individual has TB. If you want to use this feature, you will need to define the property in the demographics Default value: None	None
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class HIVARTStagingByCD4Diagnostic(IndividualIntervention):
    """
    The **HIVARTStagingByCD4Diagnostic** intervention class checks for treatment eligibility based on CD4 count.
    It uses the lowest-ever recorded CD4 count for that individual, based on the history of past CD4 counts
    conducted using the **HIVDrawBlood** intervention. To specify the outcome based on age bins instead of CD4
    testing, use **HIVARTStagingCD4AgnosticDiagnostic**.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        cd4_threshold(ValueMap, required):
            It is a piecewise table of years to CD4 and the individual's CD4 count must be below this threshold in order
            to get a positive 'diagnosis'.

        if_pregnant(ValueMap, required):
            If the individual does not pass the diagnostic from the **cd4_threshold** or if_active_TB, and the
            individual is pregnant, then the individual's CD4 is compared to the value found in the
            **ValueMap matrix**.

        if_active_tb(ValueMap, required):
            If the individual's CD4 is not below the threshold in the **cd4_threshold** table and the individual
            has TB, then the individual's CD4 will be compared to the CD4 value retrieved from the **ValueMap** matrix
            based on the current year. Whether a person has TB is determined by the value of an Individual Property as
            determined by the parameters individual_property_active_tb_key(typically 'HasActiveTB') and
            individual_property_active_tb_value(typically 'Yes').

        positive_diagnosis_event(str, required):
            If the test is positive, this specifies an event that will be broadcast. See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.

        negative_diagnosis_event(str, optional):
            If the test is negative, this specifies an event that will be broadcast.
            See :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
            Default value: None

        individual_property_active_tb_value(str, optional):
            The **IndividualProperty** value ('Yes') used to determine whether the individual has TB. If you want to
            use this feature, you will need to define the property in the demographics
            Default value: None

        individual_property_active_tb_key(str, optional):
            The **IndividualProperty** key ('HasActiveTB') used to determine whether the individual has TB. If you want
            to use this feature, you will need to define the property in the demographics
            Default value: None

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 cd4_threshold: ValueMap,
                 if_pregnant: ValueMap,
                 if_active_tb: ValueMap,
                 positive_diagnosis_event: str,
                 negative_diagnosis_event: str = None,
                 individual_property_active_tb_value: str = None,
                 individual_property_active_tb_key: str = None,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'HIVARTStagingByCD4Diagnostic', common_intervention_parameters)

        self._intervention.Threshold = cd4_threshold.to_schema_dict(campaign)
        self._intervention.If_Pregnant = if_pregnant.to_schema_dict(campaign)
        self._intervention.If_Active_TB = if_active_tb.to_schema_dict(campaign)
        self._intervention.Positive_Diagnosis_Event = set_event(positive_diagnosis_event, 'positive_diagnosis_event', campaign, False)
        self._intervention.Negative_Diagnosis_Event = set_event(negative_diagnosis_event, 'negative_diagnosis_event', campaign, True)

        # individual_property_active_tb_value and individual_property_active_tb_key are optional, but if one is set, both must be set
        if individual_property_active_tb_value is not None and individual_property_active_tb_key is not None:
            self._intervention.Individual_Property_Active_TB_Value = individual_property_active_tb_value
            self._intervention.Individual_Property_Active_TB_Key = individual_property_active_tb_key
        elif individual_property_active_tb_value is not None or individual_property_active_tb_key is not None:
            raise ValueError("If individual_property_active_tb_value is set, individual_property_active_tb_key must also be set, and vice versa.")

HIVARTStagingCD4AgnosticDiagnostic

Bases: IndividualIntervention

The HIVARTStagingCD4AgnosticDiagnostic intervention class checks for treatment eligibility based on age. It uses the individual's age and the adult_treatment_age argument to determine if the person should be usin the adult or child requirements. To specify the outcome based on CD4 testing, use HIVARTStagingByCD4Diagnostic.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
child_treat_under_age_in_years_threshold	(ValueMap, required)	Determines the age at which children are eligible for ART regardless of CD4, WHO stage, or other factors. This parameter uses ValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years.	required
child_by_who_stage	(ValueMap, required)	Determines the WHO stage at or above which children are eligible for ART. This parameter uses ValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years.	required
child_by_tb	(ValueMap, required)	Determines the WHO stage at or above which children having active TB are eligible for ART. This parameter uses ValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years. Whether a child has TB is determined by the value of an Individual Property as determined by the parameters individual_property_active_tb_key(typically 'HasActiveTB') and individual_property_active_tb_value(typically 'Yes').	required
adult_by_who_stage	(ValueMap, required)	Determines the WHO stage at or above which adults are eligible for ART. This parameter uses ValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years.	required
adult_by_tb	(ValueMap, required)	Determines the WHO stage at or above which adults having active TB are eligible for ART. This parameter uses ValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years. Whether an adult has TB is determined by the value of an Individual Property as determined by the parameters individual_property_active_tb_key(typically 'HasActiveTB') and individual_property_active_tb_value(typically 'Yes').	required
adult_by_pregnant	(ValueMap, required)	Determines the WHO stage at or above which pregnant adults are eligible for ART. This parameter uses ValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years.	required
positive_diagnosis_event	(str, required)	If an individual tests positive, this specifies an event that may trigger another intervention when the event occurs. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event.	required
negative_diagnosis_event	str	If an individual tests negative, this specifies an event that will be broadcast and may trigger another intervention. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	None
individual_property_active_tb_value	str	The IndividualProperty value ('Yes') used to determine whether the individual has TB. Default value: None	None
individual_property_active_tb_key	str	The IndividualProperty key ('HasActiveTB') used to determine whether the individual has TB. Default value: None	None
adult_treatment_age	float	The age (in years) that delineates adult patients from pediatric patients for the purpose of treatment eligibility. Patients younger than this age may be eligible on the basis of their pediatric patient status. Minimum value: -1 Maximum value: 3.40282e+38 Default value: 5	5
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class HIVARTStagingCD4AgnosticDiagnostic(IndividualIntervention):
    """
    The **HIVARTStagingCD4AgnosticDiagnostic** intervention class checks for treatment eligibility based on age.
    It uses the individual's age and the **adult_treatment_age** argument to determine if the person should be
    usin the adult or child requirements. To specify the outcome based on CD4 testing,
    use **HIVARTStagingByCD4Diagnostic**.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        child_treat_under_age_in_years_threshold(ValueMap, required):
            Determines the age at which children are eligible for ART regardless of CD4, WHO stage, or other
            factors. This parameter uses **ValueMap** to define **Times** (by year) and **Values**
            for the history and expected treatment guidelines for future years.

        child_by_who_stage(ValueMap, required):
            Determines the WHO stage at or above which children are eligible for ART. This parameter uses
            **ValueMap** to define **Times** (by year) and **Values** for the history and expected
            treatment guidelines for future years.

        child_by_tb(ValueMap, required):
            Determines the WHO stage at or above which children having active TB are eligible for ART.
            This parameter uses **ValueMap** to define **Times** (by year) and **Values** for the history and expected
            treatment guidelines for future years. Whether a child has TB is determined by the value of an Individual Property as
            determined by the parameters individual_property_active_tb_key(typically 'HasActiveTB') and
            individual_property_active_tb_value(typically 'Yes').

        adult_by_who_stage(ValueMap, required):
            Determines the WHO stage at or above which adults are eligible for ART. This parameter uses
            ValueMap to define **Times** (by year) and **Values** for the history and expected
            treatment guidelines for future years.

        adult_by_tb(ValueMap, required):
            Determines the WHO stage at or above which adults having active TB are eligible for ART.
            This parameter uses ValueMap to define **Times**
            (by year) and **Values** for the history and expected treatment guidelines for future years. Whether an
            adult has TB is determined by the value of an Individual Property as
            determined by the parameters individual_property_active_tb_key(typically 'HasActiveTB') and
            individual_property_active_tb_value(typically 'Yes').

        adult_by_pregnant(ValueMap, required):
            Determines the WHO stage at or above which pregnant adults are eligible for ART. This parameter
            uses ValueMap to define **Times** (by year) and **Values** for the history and expected
            treatment guidelines for future years.

        positive_diagnosis_event(str, required):
            If an individual tests positive, this specifies an event that may trigger another intervention when
            the event occurs. See :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in
            EMOD or use your own custom event.

        negative_diagnosis_event(str, optional):
            If an individual tests negative, this specifies an event that will be broadcast and may trigger another
            intervention. See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
            Default value: None

        individual_property_active_tb_value(str, optional):
            The **IndividualProperty** value ('Yes') used to determine whether the individual has TB.
            Default value: None

        individual_property_active_tb_key(str, optional):
            The **IndividualProperty** key ('HasActiveTB') used to determine whether the individual has TB.
            Default value: None

        adult_treatment_age(float, optional):
            The age (in years) that delineates adult patients from pediatric patients for the purpose of
            treatment eligibility. Patients younger than this age may be eligible on the basis of their
            pediatric patient status.
            Minimum value: -1
            Maximum value: 3.40282e+38
            Default value: 5

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 child_treat_under_age_in_years_threshold: ValueMap,
                 child_by_who_stage: ValueMap,
                 child_by_tb: ValueMap,
                 adult_by_who_stage: ValueMap,
                 adult_by_tb: ValueMap,
                 adult_by_pregnant: ValueMap,
                 positive_diagnosis_event: str,
                 negative_diagnosis_event: str = None,
                 individual_property_active_tb_value: str = None,
                 individual_property_active_tb_key: str = None,
                 adult_treatment_age: float = 5,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'HIVARTStagingCD4AgnosticDiagnostic', common_intervention_parameters)

        self._intervention.Child_Treat_Under_Age_In_Years_Threshold = child_treat_under_age_in_years_threshold.to_schema_dict(campaign)
        self._intervention.Child_By_WHO_Stage = child_by_who_stage.to_schema_dict(campaign)
        self._intervention.Child_By_TB = child_by_tb.to_schema_dict(campaign)
        self._intervention.Adult_By_WHO_Stage = adult_by_who_stage.to_schema_dict(campaign)
        self._intervention.Adult_By_TB = adult_by_tb.to_schema_dict(campaign)
        self._intervention.Adult_By_Pregnant = adult_by_pregnant.to_schema_dict(campaign)
        self._intervention.Positive_Diagnosis_Event = set_event(positive_diagnosis_event, 'positive_diagnosis_event', campaign, False)
        self._intervention.Negative_Diagnosis_Event = set_event(negative_diagnosis_event, 'negative_diagnosis_event', campaign, True)

        # individual_property_active_tb_value and individual_property_active_tb_key are optional, but if one is set, both must be set
        if individual_property_active_tb_value is not None and individual_property_active_tb_key is not None:
            self._intervention.Individual_Property_Active_TB_Value = individual_property_active_tb_value
            self._intervention.Individual_Property_Active_TB_Key = individual_property_active_tb_key
        elif individual_property_active_tb_value is not None or individual_property_active_tb_key is not None:
            raise ValueError(
                "If individual_property_active_tb_value is set, individual_property_active_tb_key must also be set, and vice versa.")
        self._intervention.Adult_Treatment_Age = validate_value_range(adult_treatment_age, 'adult_treatment_age', -1, 3.40282e+38, float)

HIVDrawBlood

Bases: IndividualIntervention

The HIVDrawBlood intervention class represents a test where blood is drawn and the person's CD4 or viral load are determined. It allows for a test result to be recorded and used for future health care decisions, but does not intrinsically lead to a health care event. A future health care decision will use this recorded CD4 count or viral load, even if the actual CD4/viral load has changed since last phlebotomy. The result can be updated by distributing another HIVDrawBlood intervention.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
positive_diagnosis_event	(str, required)	If an individual tests positive, this specifies an event that may trigger another intervention when the event occurs. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event.	required
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class HIVDrawBlood(IndividualIntervention):
    """
    The **HIVDrawBlood** intervention class represents a test where blood is drawn and the person's CD4 or
    viral load are determined. It allows for a test result to be recorded and used for future health care
    decisions, but does not intrinsically lead to a health care event. A future health care decision will
    use this recorded CD4 count or viral load, even if the actual CD4/viral load has changed since last
    phlebotomy. The result can be updated by distributing another **HIVDrawBlood** intervention.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        positive_diagnosis_event(str, required):
            If an individual tests positive, this specifies an event that may trigger another intervention when
            the event occurs. See :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or
            use your own custom event.

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 positive_diagnosis_event: str,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'HIVDrawBlood', common_intervention_parameters)

        self._intervention.Positive_Diagnosis_Event = set_event(positive_diagnosis_event, 'positive_diagnosis_event', campaign, False)

HIVMuxer

Bases: IndividualIntervention

The HIVMuxer intervention class is a method of placing groups of individuals into a waiting pattern for the next event, and is based on DelayedIntervention. HIVMuxer adds the ability to limit the number of times an individual can be registered with the delay, which ensures that an individual is only provided with the delay one time. For example, without HIVMuxer, an individual could be given an exponential delay twice, effectively doubling the rate of leaving the delay.

Please refer to the documentation for HIVMuxer at the following link: :doc:emod-hiv:emod/parameter-campaign-individual-hivmuxer

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
muxer_name	(str, required)	A name used to identify the delay and check whether individuals have entered it multiple times. If the same name is used at multiple points in the health care process, then the number of entries is combined when max_entries is applied.	required
delay_period_distribution	(BaseDistribution, required)	The distribution type to use for assigning the delay period for distributing interventions. Each assigned value is a random draw from the distribution. Please use the following distribution classes from emodpy_hiv.utils.distributions to define the distribution: * ConstantDistribution * UniformDistribution * GaussianDistribution * ExponentialDistribution * PoissonDistribution * LogNormalDistribution * DualConstantDistribution * WeibullDistribution * DualExponentialDistribution	required
max_entries	int	The maximum number of times the individual can be registered with the HIVMuxer delay. Determines what should happen if an individual reaches the HIVMuxer stage of health care multiple times. For example, registering for an exponential delay two times effectively doubles the rate of leaving the delay. Setting max_entries to 1 prevents the rate from doubling. Minimum value: 0 Maximum value: 2147480000.0 Default value: 1	1
expiration_period	float	A fixed time period, in days, after which the broadcast_on_expiration_event occurs instead of the broadcast_delay_complete_event. Only applied if the expiration_period occurs earlier than the end of the delay period. For example, if loss to follow-up (LTFU) occurs at a high rate for the first 6 months of care, and then later transitions to a lower rate, then the Expiration_Period should be set to 183 days and Broadcast_On_Expiration_Event can link to another delay intervention with a longer average delay time until LTFU. If LTFU does not occur in the first 6 months, then the expiration will allow the first rate to give way to the post-6-month rate. Minimum value: 0 Maximum value: 3.40282e+38 Default value: 3.40282e+38	3.40282e+38
broadcast_on_expiration_event	str	If the delay intervention expires before arriving at the end of the delay period, this specifies the event that should occur. For example, if loss to follow-up occurs at a high rate for the first 6 months of care, and then later transitions to a lower rate, then the Expiration_Period should be set to 183 days and Broadcast_On_Expiration_Event can link to another delay intervention with a longer average delay time until loss to follow up (LTFU). If LTFU does not occur in the first 6 months, then the expiration will allow the first rate to give way to the post-6-month rate. See the list of available events for possible values. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	None
broadcast_delay_complete_event	str	The event that should occur at the end of the delay period. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. custom event. Default value: None	None
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 4 common parameters: intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. The following parameters are not valid for this intervention: cost Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class HIVMuxer(IndividualIntervention):
    """
    The **HIVMuxer** intervention class is a method of placing groups of individuals into a waiting pattern for the next
    event, and is based on DelayedIntervention. **HIVMuxer** adds the ability to limit the number of times an individual
    can be registered with the delay, which ensures that an individual is only provided with the delay one time. For
    example, without **HIVMuxer**, an individual could be given an exponential delay twice, effectively doubling the rate
    of leaving the delay.

    Please refer to the documentation for **HIVMuxer** at the following link:
    :doc:`emod-hiv:emod/parameter-campaign-individual-hivmuxer`

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        muxer_name(str, required):
            A name used to identify the delay and check whether individuals have entered it multiple times. If
            the same name is used at multiple points in the health care process, then the number of entries is
            combined when **max_entries** is applied.

        delay_period_distribution(BaseDistribution, required):
            The distribution type to use for assigning the delay period for distributing interventions. Each
            assigned value is a random draw from the distribution. Please use the following distribution classes
            from emodpy_hiv.utils.distributions to define the distribution:
            * ConstantDistribution
            * UniformDistribution
            * GaussianDistribution
            * ExponentialDistribution
            * PoissonDistribution
            * LogNormalDistribution
            * DualConstantDistribution
            * WeibullDistribution
            * DualExponentialDistribution

        max_entries(int, optional):
            The maximum number of times the individual can be registered with the HIVMuxer delay. Determines
            what should happen if an individual reaches the HIVMuxer stage of health care multiple times. For
            example, registering for an exponential delay two times effectively doubles the rate of leaving the
            delay. Setting **max_entries** to 1 prevents the rate from doubling.
            Minimum value: 0
            Maximum value: 2147480000.0
            Default value: 1

        expiration_period(float, optional):
            A fixed time period, in days, after which the **broadcast_on_expiration_event** occurs instead of
            the **broadcast_delay_complete_event**. Only applied if the **expiration_period** occurs earlier than the end of
            the delay period. For example, if loss to follow-up (LTFU) occurs at a high rate for the first 6
            months of care, and then later transitions to a lower rate, then the **Expiration_Period** should
            be set to 183 days and **Broadcast_On_Expiration_Event** can link to another delay intervention
            with a longer average delay time until LTFU. If LTFU does not occur in the first 6 months, then the
            expiration will allow the first rate to give way to the post-6-month rate.
            Minimum value: 0
            Maximum value: 3.40282e+38
            Default value: 3.40282e+38

        broadcast_on_expiration_event(str, optional):
            If the delay intervention expires before arriving at the end of the delay period, this specifies
            the event that should occur. For example, if loss to follow-up occurs at a high rate for the first
            6 months of care, and then later transitions to a lower rate, then the **Expiration_Period** should
            be set to 183 days and **Broadcast_On_Expiration_Event** can link to another delay intervention
            with a longer average delay time until loss to follow up (LTFU). If LTFU does not occur in the
            first 6 months, then the expiration will allow the first rate to give way to the post-6-month rate.
            See the list of available events for possible values. See :doc:`emod-hiv:emod/parameter-campaign-event-list`
            for events already used in EMOD or use your own custom event.
            Default value: None

        broadcast_delay_complete_event(str, optional):
            The event that should occur at the end of the delay period. See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your own custom
            event.
            custom event.
            Default value: None

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 4 common
            parameters: intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            The following parameters are not valid for this intervention:
            cost
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 muxer_name: str,
                 delay_period_distribution: BaseDistribution,
                 max_entries: int = 1,
                 expiration_period: float = 3.40282e+38,
                 broadcast_on_expiration_event: str = None,
                 broadcast_delay_complete_event: str = None,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'HIVMuxer', common_intervention_parameters)

        self._intervention.Muxer_Name = muxer_name
        if not isinstance(delay_period_distribution, BaseDistribution):
            raise ValueError(f"delay_period_distribution must be an instance of BaseDistribution, not {type(delay_period_distribution)}.")
        self.set_distribution(delay_period_distribution, 'Delay_Period')

        self._intervention.Max_Entries = validate_value_range(max_entries, 'max_entries', 0, 2147480000.0, int)
        self._intervention.Expiration_Period = validate_value_range(expiration_period, 'expiration_period', 0, 3.40282e+38, float)
        self._intervention.Broadcast_On_Expiration_Event = set_event(broadcast_on_expiration_event, 'broadcast_on_expiration_event', campaign, True)
        self._intervention.Broadcast_Event = set_event(broadcast_delay_complete_event, 'broadcast_event', campaign, True)

    def _set_cost(self, cost: float) -> None:
        raise ValueError('Cost_To_Consumer is not a valid parameter for the HIVMuxer intervention.')

HIVPiecewiseByYearAndSexDiagnostic

Bases: IndividualIntervention

The HIVPiecewiseByYearAndSexDiagnostic intervention class is used to model the roll-out of an intervention over time. Unlike HIVSigmoidByYearAndSexDiagnostic, which requires the time trend to have a sigmoid shape, this intervention allows for any trend of time to be configured using piecewise or linear interpolation. The trends over time can be configured differently for males and females. Note that the term "diagnosis" is used, but this intervention is typically used more like a trend in behavior or coverage over time.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
time_value_map	(ValueMap, required)	Please use the ValueMap class from emodpy_hiv.campaign.common to define the time_value_map. The years (times) and matching probabilities for test results. This parameter uses ValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years. This creates a JSON structure containing one array of Times and one for Values, which allows for a time-variable probability that can take on any shape over time. When queried at a simulation year corresponding to one of the listed Times, it returns the corresponding Value. When queried earlier than the first listed Time, it returns the default Value. When queried in between listed Times, it either returns the Value for the most recent past time (when linear_interpolation is False) or linearly interpolates Values between Times (when linear_interpolation is True). When queried after the last Time in the list, it returns the last Value. The Times and Values must be of equal length, and can consist of a single value. Times must monotonically increase.	required
positive_diagnosis_event	(str, required)	If an individual tests positive, this specifies an event that may trigger another intervention when the event occurs. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event.	required
negative_diagnosis_event	str	If an individual tests negative, this specifies an event that may trigger another intervention when the event occurs. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	None
linear_interpolation	bool	When set to False, interpolation between values in the time_value_map is zero-order ('staircase'). When set to True, interpolation between values in the time_value_map is linear. The final value is held constant for all times after the last time specified in the time_value_map. Default value: False	False
female_multiplier	float	Allows for the probabilities in the time_value_map to be different for males and females, by multiplying the female probabilities by a constant value. Minimum value: 0 Maximum value: 3.40282e+38 Default value: 1	1
default_value	float	The probability of positive diagnosis if the intervention is used before the earliest specified time in the time_value_map. Minimum value: 0 Maximum value: 1 Default value: 0	0
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class HIVPiecewiseByYearAndSexDiagnostic(IndividualIntervention):
    """
    The **HIVPiecewiseByYearAndSexDiagnostic** intervention class is used to model the roll-out of an
    intervention over time. Unlike **HIVSigmoidByYearAndSexDiagnostic**, which requires the time trend
    to have a sigmoid shape, this intervention allows for any trend of time to be configured using
    piecewise or linear interpolation. The trends over time can be configured differently for males and
    females. Note that the term "diagnosis" is used, but this intervention is typically used more like a
    trend in behavior or coverage over time.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        time_value_map(ValueMap, required):
            Please use the ValueMap class from emodpy_hiv.campaign.common to define the **time_value_map**.
            The years (times) and matching probabilities for test results. This parameter uses
            ValueMap to define **Times** (by year) and **Values** for the history and expected
            treatment guidelines for future years. This creates a JSON structure containing one array of
            **Times** and one for **Values**, which allows for a time-variable probability that can take on any
            shape over time. When queried at a simulation year corresponding to one of the listed **Times**, it
            returns the corresponding **Value**. When queried earlier than the first listed **Time**, it
            returns the default **Value**. When queried in between listed **Times**, it either returns the
            **Value** for the most recent past time (when **linear_interpolation** is False) or linearly interpolates
            Values between **Times** (when **linear_interpolation** is True). When queried after the last **Time** in
            the list, it returns the last **Value**. The **Times** and **Values** must be of equal length, and
            can consist of a single value. **Times** must monotonically increase.

        positive_diagnosis_event(str, required):
            If an individual tests positive, this specifies an event that may trigger another intervention when
            the event occurs. See :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or
            use your own custom event.

        negative_diagnosis_event(str, optional):
            If an individual tests negative, this specifies an event that may trigger another intervention when
            the event occurs. See :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or
            use your own custom event.
            Default value: None

        linear_interpolation(bool, optional):
            When set to False, interpolation between values in the **time_value_map** is zero-order
            ('staircase'). When set to True, interpolation between values in the **time_value_map** is linear. The
            final value is held constant for all times after the last time specified in the **time_value_map**.
            Default value: False

        female_multiplier(float, optional):
            Allows for the probabilities in the **time_value_map** to be different for males and females, by
            multiplying the female probabilities by a constant value.
            Minimum value: 0
            Maximum value: 3.40282e+38
            Default value: 1

        default_value(float, optional):
            The probability of positive diagnosis if the intervention is used before the earliest specified
            time in the **time_value_map**.
            Minimum value: 0
            Maximum value: 1
            Default value: 0

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 time_value_map: ValueMap,
                 positive_diagnosis_event: str,
                 negative_diagnosis_event: str = None,
                 linear_interpolation: bool = False,
                 female_multiplier: float = 1,
                 default_value: float = 0,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'HIVPiecewiseByYearAndSexDiagnostic', common_intervention_parameters)

        self._intervention.Time_Value_Map = time_value_map.to_schema_dict(campaign)
        self._intervention.Positive_Diagnosis_Event = set_event(positive_diagnosis_event, 'positive_diagnosis_event', campaign, False)
        self._intervention.Negative_Diagnosis_Event = set_event(negative_diagnosis_event, 'negative_diagnosis_event', campaign, True)
        self._intervention.Interpolation_Order = 1 if linear_interpolation else 0
        self._intervention.Female_Multiplier = validate_value_range(female_multiplier, 'female_multiplier', 0, 3.40282e+38, float)
        self._intervention.Default_Value = validate_value_range(default_value, 'default_value', 0, 1, float)

HIVRandomChoice

Bases: IndividualIntervention

The HIVRandomChoice intervention class is used to change the logic in how and where treatment is applied to individuals based on specified probabilities.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
choice_probabilities	(list[float], required)	An array of probabilities that the event will be selected, used with choice_names. Values in map must be normalized to sum to one.	None
choice_names	(list[str], required)	An array of event names to be broadcast if randomly selected, used with choice_probabilities.	None
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class HIVRandomChoice(IndividualIntervention):
    """
    The **HIVRandomChoice** intervention class is used to change the logic in how and where treatment is applied
    to individuals based on specified probabilities.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        choice_probabilities(list[float], required):
            An array of probabilities that the event will be selected, used with **choice_names**. Values in
            map must be normalized to sum to one.

        choice_names(list[str], required):
            An array of event names to be broadcast if randomly selected, used with **choice_probabilities**.

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 choice_probabilities: list[float] = None,
                 choice_names: list[str] = None,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'HIVRandomChoice', common_intervention_parameters)

        # check if the choice_probabilities and choice_names are the same length
        if len(choice_probabilities) != len(choice_names):
            raise ValueError('The length of choice_probabilities and choice_names must be the same.')

        # check if the sum of the choice_probabilities is equal to 1
        if sum(choice_probabilities) != 1:
            raise ValueError('The sum of choice_probabilities must be equal to 1.')

        choice_names = [set_event(choice_name, 'choice_name', campaign, False) for choice_name in choice_names]

        self._intervention.Choice_Probabilities = choice_probabilities
        self._intervention.Choice_Names = choice_names

HIVRapidHIVDiagnostic

Bases: IndividualIntervention

The HIVRapidHIVDiagnostic intervention class builds on StandardDiagnostic by also updating the individual's knowledge of their HIV status. This can affect their access to ART in the future as well as other behaviors. This intervention should be used only if the individual's knowledge of their status should impact a voluntary male circumcision campaign.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
positive_diagnosis_event	(str, required)	If the test is positive, this specifies an event that will be broadcast. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event.	required
base_sensitivity	float	Use this parameter to set a constant value for sensitivity of the diagnostic. If you want to set the sensitivity over time, use the sensitivity_versus_time parameter instead. You need to set either base_sensitivity or sensitivity_versus_time. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test. Minimum value: 0 Maximum value: 1 Default value: None	None
sensitivity_versus_time	(ValueMap, Optional)	Use this parameter to set the sensitivity of the diagnostic test over time. If you want to set a constant value for sensitivity, use the base_sensitivity parameter instead. You need to set either base_sensitivity or sensitivity_versus_time. This expects a ValueMap object (from emodpy_hiv.campaign.common) that contains two arrays: The 'Times' values are the duration from when the person became infected. 'Values' is the sensitivity of the diagnostic for the given age of the infection. Default value: None	None
base_specificity	float	The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test. Minimum value: 0 Maximum value: 1 Default value: 1	1
probability_received_result	float	The probability that an individual received the results of a diagnostic test. Minimum value: 0 Maximum value: 1 Default value: 1	1
negative_diagnosis_event	str	If the test is negative, this event will be broadcast. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	None
enable_is_symptomatic	bool	If true, requires an infection to be symptomatic to return a positive test. Default value: True	False
days_to_diagnosis	float	The number of days from diagnosis (which is done when the intervention is distributed) until a positive response is performed. The response to a negative diagnosis is done immediately when the diagnosis is made (at distribution of the intervention). Minimum value: 0 Maximum value: 3.40282e+38 Default value: 0	0
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class HIVRapidHIVDiagnostic(IndividualIntervention):
    """
    The **HIVRapidHIVDiagnostic** intervention class builds on **StandardDiagnostic** by also updating the
    individual's knowledge of their HIV status. This can affect their access to ART in the future as well as
    other behaviors. This intervention should be used only if the individual's knowledge of their status should
    impact a voluntary male circumcision campaign.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        positive_diagnosis_event(str, required):
            If the test is positive, this specifies an event that will be broadcast.
            See :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or
            use your own custom event.

        base_sensitivity(float, optional):
            Use this parameter to set a constant value for sensitivity of the diagnostic. If you want to set
            the sensitivity over time, use the **sensitivity_versus_time** parameter instead. You need to set either
            **base_sensitivity** or **sensitivity_versus_time**.
            This sets the proportion of the time that individuals with the condition being tested receive a positive
            diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero,
            then individuals who have the condition always receive a false-negative diagnostic test.
            Minimum value: 0
            Maximum value: 1
            Default value: None

        sensitivity_versus_time(ValueMap, Optional):
            Use this parameter to set the sensitivity of the diagnostic test over time. If you want to set a constant
            value for sensitivity, use the **base_sensitivity** parameter instead. You need to set either
            **base_sensitivity** or **sensitivity_versus_time**.
            This expects a ValueMap object (from emodpy_hiv.campaign.common) that contains two arrays:
            The 'Times' values are the duration from when the person became infected. 'Values' is the
            sensitivity of the diagnostic for the given age of the infection.
            Default value: None


        base_specificity(float, optional):
            The specificity of the diagnostic. This sets the proportion of the time that individuals without
            the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always
            accurately reflects the lack of having the condition. When set to zero, then individuals who do not
            have the condition always receive a false-positive diagnostic test.
            Minimum value: 0
            Maximum value: 1
            Default value: 1

        probability_received_result(float, optional):
            The probability that an individual received the results of a diagnostic test.
            Minimum value: 0
            Maximum value: 1
            Default value: 1

        negative_diagnosis_event(str, optional):
            If the test is negative, this event will be broadcast. See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your own
            custom event.
            Default value: None

        enable_is_symptomatic(bool, optional):
            If true, requires an infection to be symptomatic to return a positive test.
            Default value: True

        days_to_diagnosis(float, optional):
            The number of days from diagnosis (which is done when the intervention is distributed) until a
            positive response is performed. The response to a negative diagnosis is done immediately when the
            diagnosis is made (at distribution of the intervention).
            Minimum value: 0
            Maximum value: 3.40282e+38
            Default value: 0

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 positive_diagnosis_event: str,
                 base_sensitivity: float = None,
                 base_specificity: float = 1,
                 sensitivity_versus_time: ValueMap = None,
                 probability_received_result: float = 1,
                 negative_diagnosis_event: str = None,
                 enable_is_symptomatic: bool = False,
                 days_to_diagnosis: float = 0,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'HIVRapidHIVDiagnostic', common_intervention_parameters)

        if base_sensitivity is None and sensitivity_versus_time is None:
            raise ValueError('Either base_sensitivity or sensitivity_versus_time must be provided.')
        elif base_sensitivity is not None and sensitivity_versus_time is not None:
            raise ValueError('Only one of base_sensitivity or sensitivity_versus_time can be provided.')
        elif base_sensitivity is not None:
            self._intervention.Base_Sensitivity = validate_value_range(base_sensitivity, 'base_sensitivity', 0, 1, float)
            self._intervention.Sensitivity_Type = SensitivityType.SINGLE_VALUE
        else:
            self._intervention.Sensitivity_Versus_Time = sensitivity_versus_time.to_schema_dict(campaign)
            self._intervention.Sensitivity_Type = SensitivityType.VERSUS_TIME

        self._intervention.Positive_Diagnosis_Event = set_event(positive_diagnosis_event, 'positive_diagnosis_event', campaign, False)
        self._intervention.Probability_Received_Result = validate_value_range(probability_received_result, 'probability_received_result', 0, 1, float)
        self._intervention.Negative_Diagnosis_Event = set_event(negative_diagnosis_event, 'negative_diagnosis_event', campaign, True)
        self._intervention.Enable_Is_Symptomatic = enable_is_symptomatic
        self._intervention.Days_To_Diagnosis = validate_value_range(days_to_diagnosis, 'days_to_diagnosis', 0, 3.40282e+38, float)
        self._intervention.Base_Specificity = validate_value_range(base_specificity, 'base_specificity', 0, 1, float)

HIVSigmoidByYearAndSexDiagnostic

Bases: IndividualIntervention

The HIVSigmoidByYearAndSexDiagnostic intervention class broadcasts a positive 'diagnosis' event by selecting a probability of that event from a sigmoidal curve versus time. For a linear approach, use HIVPiecewiseByYearandSexDiagnostic.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
positive_diagnosis_event	(str, required)	If an individual tests positive, this specifies an event that may trigger another intervention when the event occurs. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event.	required
year_sigmoid	(Sigmoid, required)	Defines a sigmoidal curve for the probability of a positive diagnosis versus time (year).	required
female_multiplier	float	Allows for the sigmoid time-varying probability to be different for males and females, by multiplying the female probability by a constant value. Minimum value: 0 Maximum value: 3.40282e+38 Default value: 1	1
negative_diagnosis_event	str	If an individual tests negative, this specifies an event that may trigger another intervention when the event occurs. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	None
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class HIVSigmoidByYearAndSexDiagnostic(IndividualIntervention):
    """
    The **HIVSigmoidByYearAndSexDiagnostic** intervention class broadcasts a positive 'diagnosis' event by
    selecting a probability of that event from a sigmoidal curve versus time. For a linear approach, use
    **HIVPiecewiseByYearandSexDiagnostic**.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        positive_diagnosis_event(str, required):
            If an individual tests positive, this specifies an event that may trigger another intervention when
            the event occurs. See :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or
            use your own custom event.

        year_sigmoid(Sigmoid, required):
            Defines a sigmoidal curve for the probability of a positive diagnosis versus time (year).

        female_multiplier(float, optional):
            Allows for the sigmoid time-varying probability to be different for males and females, by
            multiplying the female probability by a constant value.
            Minimum value: 0
            Maximum value: 3.40282e+38
            Default value: 1

        negative_diagnosis_event(str, optional):
            If an individual tests negative, this specifies an event that may trigger another intervention when
            the event occurs. See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
            Default value: None

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 positive_diagnosis_event: str,
                 year_sigmoid: Sigmoid,
                 female_multiplier: float = 1,
                 negative_diagnosis_event: str = None,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'HIVSigmoidByYearAndSexDiagnostic', common_intervention_parameters)

        if year_sigmoid is None:
            raise ValueError("'year_sigmoid' must be defined.")

        # Don't need to check values because these values are the same as the ranges in the Sigmoid class.
        self._intervention.Ramp_Min = year_sigmoid.min
        self._intervention.Ramp_Max = year_sigmoid.max
        self._intervention.Ramp_MidYear = year_sigmoid.mid
        self._intervention.Ramp_Rate = year_sigmoid.rate
        self._intervention.Female_Multiplier = validate_value_range(female_multiplier, 'female_multiplier', 0, 3.40282e+38, float)
        self._intervention.Positive_Diagnosis_Event = set_event(positive_diagnosis_event, 'positive_diagnosis_event', campaign, False)
        self._intervention.Negative_Diagnosis_Event = set_event(negative_diagnosis_event, 'negative_diagnosis_event', campaign, True)

InterventionForCurrentPartners

Bases: IndividualIntervention

The InterventionForCurrentPartners intervention class provides a mechanism for the partners of individuals in the care system to also seek care. Partners do not need to seek testing at the same time; a delay may occur between the initial test and the partner's test. If a relationship has been paused, such as when a partner migrates to a different node, the partner will not be contacted.

Either the intervention_config or broadcast_event parameter must be set, but not both.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
intervention_config	IndividualIntervention	The intervention definition that is immediately distributed to the partner. This parameter is required if broadcast_event is not set. Default value: None	None
broadcast_event	str	The event that is immediately broadcast to the partner. See :doc:emod-hiv:emod/parameter-campaign-event-list for possible built-in values, or use your own custom event. This parameter is required if intervention_config is not set. Default value: None	None
prioritize_partners_by	PrioritizePartnersBy	How to prioritize partners for the intervention, as long as they have been in a relationship longer than minimum_duration_years. Expect PrioritizePartnersBy enum from emodpy_hiv.utils.emod_enum. Possible values are: * NO_PRIORTIZATION - All partners are contacted. * CHOSEN_AT_RANDOM - Partners are randomly selected until maximum_partners have received the intervention. * LONGER_TIME_IN_RELATIONSHIP - Partners are sorted in descending order of the duration of the relationship. Partners are contacted from the beginning of this list until maximum_partners have received the intervention. * SHORTER_TIME_IN RELATIONSHIP - Partners are sorted in ascending order of the duration of the relationship. Partners are contacted from the beginning of the list until maximum_partners have received the intervention. * OLDER_AGE - Partners are sorted in descending order of their age. Partners are contacted from the beginning of this list until maximum_partners have received the intervention. * YOUNGER_AGE - Partners sorted in ascending order of the duration of the relationship. Partners are contacted from the beginning of this list until maximum_partners have received the intervention. * RELATIONSHIP_TYPE - Partners are sorted based on the order of relationship types defined in the relationship_types array. For example, 'relationship_types' : ['MARITAL', 'INFORMAL', 'TRANSITORY', 'COMMERCIAL'], will prioritize marital first, then informal, then transitory, then commercial, with random selection between mulitple partners of the same type. Default value: PrioritizePartnersBy.NO_PRIORITIZATION	NO_PRIORITIZATION
relationship_types	list[RelationshipTypes]	An array listing all possible relationship types for which partners can qualify for the intervention. Expect RelationshipTypes enum emodpy_hiv.utils.emod_enum. Possible values are: TRANSITORY, INFORMAL, MARITAL, and COMMERCIAL. If prioritize_partners_by is set to PrioritizePartnersBy.RELATIONSHIP_TYPE, then the order of these types is used. The array may not contain duplicates, and cannot be empty. Default value: None	None
minimum_duration_years	float	The minimum amount of time, in years, between relationship formation and the current time for the partner to qualify for the intervention. Minimum value: 0 Maximum value: 200 Default value: 0	0
maximum_partners	float	The maximum number of partners that will receive the intervention. Required when Prioritize_Partners_By is not set to NO_PRIORITIZATION. Minimum value: 0 Maximum value: 100 Default value: 100	100
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 4 common parameters: intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. The following parameters are not valid for this intervention: cost Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class InterventionForCurrentPartners(IndividualIntervention):
    """
    The **InterventionForCurrentPartners** intervention class provides a mechanism for the partners of
    individuals in the care system to also seek care. Partners do not need to seek testing at the same time;
    a delay may occur between the initial test and the partner's test. If a relationship has been paused,
    such as when a partner migrates to a different node, the partner will not be contacted.

    Either the **intervention_config** or **broadcast_event** parameter must be set, but not both.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        intervention_config(IndividualIntervention, optional):
            The intervention definition that is immediately distributed to the partner. This parameter
            is required if **broadcast_event** is not set.
            Default value: None

        broadcast_event(str, optional):
            The event that is immediately broadcast to the partner.
            See :doc:`emod-hiv:emod/parameter-campaign-event-list` for possible built-in values, or use your own
            custom event. This parameter is required if **intervention_config** is not set.
            Default value: None

        prioritize_partners_by(PrioritizePartnersBy, optional):
            How to prioritize partners for the intervention, as long as they have been in a relationship longer
            than **minimum_duration_years**. Expect PrioritizePartnersBy enum from emodpy_hiv.utils.emod_enum.
            Possible values are:
            * NO_PRIORTIZATION - All partners are contacted.
            * CHOSEN_AT_RANDOM - Partners are randomly selected until **maximum_partners** have received the
            intervention.
            * LONGER_TIME_IN_RELATIONSHIP - Partners are sorted in descending order of the duration of the
            relationship. Partners are contacted from the beginning of this list until **maximum_partners**
            have received the intervention.
            * SHORTER_TIME_IN RELATIONSHIP - Partners are sorted in ascending order of the duration of the
            relationship. Partners are contacted from the beginning of the list until **maximum_partners** have
            received the intervention.
            * OLDER_AGE - Partners are sorted in descending order of their age. Partners are contacted from the
            beginning of this list until **maximum_partners** have received the intervention.
            * YOUNGER_AGE - Partners sorted in ascending order of the duration of the relationship.
            Partners are contacted from the beginning of this list until **maximum_partners** have received the
            intervention.
            * RELATIONSHIP_TYPE - Partners are sorted based on the order of relationship types defined in the
            **relationship_types** array. For example, 'relationship_types' : ['MARITAL', 'INFORMAL',
            'TRANSITORY', 'COMMERCIAL'], will prioritize marital first, then informal, then transitory, then
            commercial, with random selection between mulitple partners of the same type.
            Default value: PrioritizePartnersBy.NO_PRIORITIZATION

        relationship_types(list[RelationshipTypes], optional):
            An array listing all possible relationship types for which partners can qualify for the
            intervention. Expect RelationshipTypes enum emodpy_hiv.utils.emod_enum. Possible values are:
            TRANSITORY, INFORMAL, MARITAL, and COMMERCIAL.
            If **prioritize_partners_by** is set to PrioritizePartnersBy.RELATIONSHIP_TYPE, then the order of these types is used. The
            array may not contain duplicates, and cannot be empty.
            Default value: None

        minimum_duration_years(float, optional):
            The minimum amount of time, in years, between relationship formation and the current time for the
            partner to qualify for the intervention.
            Minimum value: 0
            Maximum value: 200
            Default value: 0

        maximum_partners(float, optional):
            The maximum number of partners that will receive the intervention. Required when
            **Prioritize_Partners_By** is not set to NO_PRIORITIZATION.
            Minimum value: 0
            Maximum value: 100
            Default value: 100

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 4 common
            parameters: intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            The following parameters are not valid for this intervention:
            cost
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 intervention_config: IndividualIntervention = None,
                 broadcast_event: str = None,
                 prioritize_partners_by: 'PrioritizePartnersBy' = PrioritizePartnersBy.NO_PRIORITIZATION,
                 relationship_types: list[str] = None,
                 minimum_duration_years: float = 0,
                 maximum_partners: float = 100,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'InterventionForCurrentPartners', common_intervention_parameters)

        self._intervention.Prioritize_Partners_By = prioritize_partners_by
        if prioritize_partners_by == PrioritizePartnersBy.RELATIONSHIP_TYPE:
            if relationship_types is None or len(relationship_types) == 0:
                raise ValueError('The relationship_types parameter must be set when prioritize_partners_by is set to RELATIONSHIP_TYPE.')
            self._intervention.Relationship_Types = relationship_types

        if prioritize_partners_by != PrioritizePartnersBy.NO_PRIORITIZATION:
            self._intervention.Maximum_Partners = validate_value_range(maximum_partners, 'maximum_partners', 0, 100,
                                                                       float)

        self._intervention.Minimum_Duration_Years = validate_value_range(minimum_duration_years, 'minimum_duration_years', 0, 200, float)

        if intervention_config is not None and broadcast_event is not None:
            raise ValueError('You can only set either intervention_config or broadcast_event, but not both.')
        elif intervention_config is not None:
            self._intervention.Intervention_Config = intervention_config.to_schema_dict()
            self._intervention.Event_Or_Config = EventOrConfig.Config
        elif broadcast_event is not None:
            self._intervention.Broadcast_Event = set_event(broadcast_event, 'broadcast_event', campaign, False)
            self._intervention.Event_Or_Config = EventOrConfig.Event
        else:
            raise ValueError('You must set either intervention_config or broadcast_event.')

    def _set_cost(self, cost: float) -> None:
        raise ValueError('Cost_To_Consumer is not a valid parameter for the InterventionForCurrentPartners intervention.')

MaleCircumcision

Bases: IndividualIntervention

The MaleCircumcision intervention class introduces male circumcision as a method to control HIV transmission. Voluntary medical male circumcision (VMMC) permanently reduces a male's likelihood of acquiring HIV; successful distribution results in a reduction in the probability of transmission.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
distributed_event_trigger	str	The name of the event to be broadcast when the intervention is distributed to an individual. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	None
circumcision_reduced_acquire	float	The reduction of susceptibility to STI by voluntary male medical circumcision (VMMC). Minimum value: 0 Maximum value: 1 Default value: 0.6	0.6
apply_if_higher_reduced_acquire	bool	If set to False, the MaleCircumcision intervention can never be applied to someone who already has a MaleCircumcision intervention. If set to True, a male who already has a MaleCircumcision intervention, but whose pre-existing MaleCircumcision intervention has a lower efficacy parameter (circumcision_reduced_acquire) than the one about to be applied, will receive the higher-efficacy MaleCircumcision. Default value: False	False
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class MaleCircumcision(IndividualIntervention):
    """
    The **MaleCircumcision** intervention class introduces male circumcision as a method to control
    HIV transmission. Voluntary medical male circumcision (VMMC) permanently reduces a male's likelihood
    of acquiring HIV; successful distribution results in a reduction in the probability of transmission.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        distributed_event_trigger(str, optional):
            The name of the event to be broadcast when the intervention is distributed to an individual. See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
            Default value: None

        circumcision_reduced_acquire(float, optional):
            The reduction of susceptibility to STI by voluntary male medical circumcision (VMMC).
            Minimum value: 0
            Maximum value: 1
            Default value: 0.6

        apply_if_higher_reduced_acquire(bool, optional):
            If set to False, the **MaleCircumcision** intervention can never be applied to someone who
            already has a **MaleCircumcision** intervention. If set to True, a male who already has a
            **MaleCircumcision** intervention, but whose pre-existing **MaleCircumcision** intervention has a
            lower efficacy parameter (**circumcision_reduced_acquire**) than the one about to be applied, will
            receive the higher-efficacy **MaleCircumcision**.
            Default value: False

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 distributed_event_trigger: str = None,
                 circumcision_reduced_acquire: float = 0.6,
                 apply_if_higher_reduced_acquire: bool = False,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'MaleCircumcision', common_intervention_parameters)

        self._intervention.Distributed_Event_Trigger = set_event(distributed_event_trigger, 'distributed_event_trigger', campaign, True)
        self._intervention.Circumcision_Reduced_Acquire = validate_value_range(circumcision_reduced_acquire, 'circumcision_reduced_acquire', 0, 1, float)
        self._intervention.Apply_If_Higher_Reduced_Acquire = 1 if apply_if_higher_reduced_acquire else 0

ModifyStiCoInfectionStatus

Bases: IndividualIntervention

The ModifyStiCoInfectionStatus intervention class creates or removes STI co-infections (which influence the rate of HIV transmission). This intervention can be used to represent things like STI treatment programs or STI outbreaks.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
new_sti_coinfection_status	(bool, required)	Determines whether to apply STI co-infection, or cure/remove STI co-infection. Set to True to include co-infection; set to False to remove co-infection.	required

Source code in emodpy_hiv/campaign/individual_intervention.py

class ModifyStiCoInfectionStatus(IndividualIntervention):
    """
    The **ModifyStiCoInfectionStatus** intervention class creates or removes STI co-infections
    (which influence the rate of HIV transmission). This intervention can be used to represent
    things like STI treatment programs or STI outbreaks.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        new_sti_coinfection_status(bool, required):
            Determines whether to apply STI co-infection, or cure/remove STI co-infection. Set to True to
            include co-infection; set to False to remove co-infection.

    """

    def __init__(self,
                 campaign: api_campaign,
                 new_sti_coinfection_status: bool):
        super().__init__(campaign, 'ModifyStiCoInfectionStatus')

        self._intervention.New_STI_CoInfection_Status = 1 if new_sti_coinfection_status else 0

    def _set_intervention_name(self, intervention_name: str) -> None:
        raise ValueError('Intervention_Name is not a valid parameter for the ModifyStiCoInfectionStatus intervention.')

    def _set_dont_allow_duplicates(self, dont_allow_duplicates: bool) -> None:
        raise ValueError('Dont_Allow_Duplicates is not a valid parameter for the ModifyStiCoInfectionStatus intervention.')

    def _set_new_property_value(self, new_property_value: str) -> None:
        raise ValueError('New_Property_Value is not a valid parameter for the ModifyStiCoInfectionStatus intervention.')

    def _set_disqualifying_properties(self, disqualifying_properties: Union[dict[str, str], list[str]]) -> None:
        raise ValueError('Disqualifying_Properties is not a valid parameter for the ModifyStiCoInfectionStatus intervention.')

    def _set_cost(self, cost: float) -> None:
        raise ValueError('Cost_To_Consumer is not a valid parameter for the ModifyStiCoInfectionStatus intervention.')

PMTCT

Bases: IndividualIntervention

The PMTCT (Prevention of Mother-to-Child Transmission) intervention class is used to define the efficacy of PMTCT treatment at time of birth. This can only be used for mothers who are not on suppressive ART and will automatically expire 40 weeks after distribution. Efficacy will be reset to 0 once it expires.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
efficacy	float	Represents the efficacy of a Prevention of Mother to Child Transmission (PMTCT) intervention, defined as the rate ratio of mother to child transmission (MTCT) between women receiving the intervention and women not receiving the intervention. A setting of 1 is equivalent to 100% blocking efficacy, and 0 reverts to the default probability of transmission, configured through the config.json parameter Maternal_Transmission_Probability. Minimum value: 0 Maximum value: 1 Default value: 0.5	0.5
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 4 common parameters: intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. The following parameters are not valid for this intervention: cost Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class PMTCT(IndividualIntervention):
    """
    The **PMTCT** (Prevention of Mother-to-Child Transmission) intervention class is used to define the efficacy
    of PMTCT treatment at time of birth. This can only be used for mothers who are not on suppressive ART and
    will automatically expire 40 weeks after distribution. Efficacy will be reset to 0 once it expires.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        efficacy(float, optional):
            Represents the efficacy of a Prevention of Mother to Child Transmission (PMTCT) intervention,
            defined as the rate ratio of mother to child transmission (MTCT) between women receiving the
            intervention and women not receiving the intervention. A setting of 1 is equivalent to 100%
            blocking efficacy, and 0 reverts to the default probability of transmission, configured through the
            config.json parameter **Maternal_Transmission_Probability**.
            Minimum value: 0
            Maximum value: 1
            Default value: 0.5

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 4 common
            parameters: intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            The following parameters are not valid for this intervention:
            cost
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 efficacy: float = 0.5,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'PMTCT', common_intervention_parameters)

        self._intervention.Efficacy = validate_value_range(efficacy, 'efficacy', 0, 1, float)

    def _set_cost(self, cost: float) -> None:
        raise ValueError('Cost_To_Consumer is not a valid parameter for the PMTCT intervention.')

RangeThreshold

An element of a look-up table where if a value (age in AgeDiagnostic or CD4 in CD4Diagnostic) is greater-than-or-equal-to the 'Low' value and less-than the 'High' value, the 'Event' will be broadcasted.

Parameters:

Name	Type	Description	Default
low	float	The low end of the diagnostic level. For this 'Event' to be selected, the value must be greater-than-or-equal-to (>=) this threshold. Minimum value: 0 Maximum value: 2000 Default value: 0	0
high	float	The high end of the diagnostic level. For this 'Event' to be selected, the value must be less-than this threshold. Minimum value: 0 Maximum value: 2000 Default value: 2000	2000
event_to_broadcast	(str, required)	If 'low' <= value < 'high, then this event will be broadcast. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event.	required

Source code in emodpy_hiv/campaign/individual_intervention.py

class RangeThreshold:
    """
    An element of a look-up table where if a value (age in **AgeDiagnostic** or CD4 in **CD4Diagnostic**)
    is greater-than-or-equal-to the 'Low' value and less-than the 'High' value, the 'Event' will be broadcasted.

    Args:
        low(float, optional):
            The low end of the diagnostic level. For this 'Event' to be selected, the value
            must be greater-than-or-equal-to (>=) this threshold.
            Minimum value: 0
            Maximum value: 2000
            Default value: 0

        high(float, optional):
            The high end of the diagnostic level. For this 'Event' to be selected, the value
            must be less-than this threshold.
            Minimum value: 0
            Maximum value: 2000
            Default value: 2000

        event_to_broadcast(str, required):
            If 'low' <= value < 'high, then this event will be broadcast.
            See :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
    """
    def __init__(self,
                 event_to_broadcast: str,
                 low: float = 0,
                 high: float = 2000):
        if event_to_broadcast is None or event_to_broadcast == '':
            raise ValueError(f"{event_to_broadcast} must be a string and cannot be None or empty.")
        self.event_to_broadcast = event_to_broadcast
        self.low  = validate_value_range( low,  'low', 0, 2000, float) # Noqa: E241, E201, E221
        self.high = validate_value_range(high, 'high', 0, 2000, float)

    def to_schema_dict(self, campaign) -> s2c.ReadOnlyDict:
        """
        A function that converts the Sigmoid object to a schema dictionary.
        """
        rt = s2c.get_class_with_defaults("idmType:RangeThreshold", schema_json=campaign.get_schema())
        rt.Low = self.low
        rt.High = self.high
        rt.Event = set_event(self.event_to_broadcast, 'event_to_broadcast', campaign, True)
        rt.finalize()
        return rt

to_schema_dict(campaign)

A function that converts the Sigmoid object to a schema dictionary.

Source code in emodpy_hiv/campaign/individual_intervention.py

def to_schema_dict(self, campaign) -> s2c.ReadOnlyDict:
    """
    A function that converts the Sigmoid object to a schema dictionary.
    """
    rt = s2c.get_class_with_defaults("idmType:RangeThreshold", schema_json=campaign.get_schema())
    rt.Low = self.low
    rt.High = self.high
    rt.Event = set_event(self.event_to_broadcast, 'event_to_broadcast', campaign, True)
    rt.finalize()
    return rt

STIBarrier

Bases: IndividualIntervention

The STIBarrier intervention is used to reduce the probability of STI or HIV transmission by applying a time-variable probability of condom usage. Each STIBarrier intervention is directed at a specific relationship type, and must be configured as a sigmoid trend over time.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
usage_expiration_event	str	When the person stops using the STIBarrier, this event will be broadcasted. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	required
usage_duration_distribution	(BaseDistribution, required)	For the distribution of each STIBarrier, a randomly selected duration from this distribution will determine when the man stops using the intervention and revert back to condom usage based on the relationship type. Please use the following distribution classes from emodpy_hiv.utils.distributions to define the distribution: * ConstantDistribution * UniformDistribution * GaussianDistribution * ExponentialDistribution * PoissonDistribution * LogNormalDistribution * DualConstantDistribution * WeibullDistribution * DualExponentialDistribution	required
relationship_type	RelationshipType	The relationship type to which the condom usage probability is applied. Possible values are: * TRANSITORY * INFORMAL * MARITAL * COMMERCIAL Default value: TRANSITORY	TRANSITORY
condom_usage_sigmoid	(Sigmoid, required)	The new sigmoid to use when determining the probability that a condom is used during a coital act within the specified relationship. This overrides the Condom_Usage_Probablility for the relationship type as defined in the Demographics file. If None (default), the Condom_Usage_Probablility is not overridden. - WARNING: For STIBarrier, the 'min' and 'max' values of the sigmoid must be between 0 and 1.	None
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class STIBarrier(IndividualIntervention):
    """
    The **STIBarrier** intervention is used to reduce the probability of STI or HIV transmission by applying
    a time-variable probability of condom usage. Each **STIBarrier** intervention is directed at a specific
    relationship type, and must be configured as a sigmoid trend over time.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        usage_expiration_event(str, optional):
            When the person stops using the STIBarrier, this event will be broadcasted.  See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
            Default value: None

        usage_duration_distribution(BaseDistribution, required):
            For the distribution of each **STIBarrier**, a randomly selected duration from this distribution
            will determine when the man stops using the intervention and revert back to condom usage based on
            the relationship type. Please use the following distribution classes
            from emodpy_hiv.utils.distributions to define the distribution:
            * ConstantDistribution
            * UniformDistribution
            * GaussianDistribution
            * ExponentialDistribution
            * PoissonDistribution
            * LogNormalDistribution
            * DualConstantDistribution
            * WeibullDistribution
            * DualExponentialDistribution

        relationship_type('RelationshipType', optional):
            The relationship type to which the condom usage probability is applied. Possible values are:
            * TRANSITORY
            * INFORMAL
            * MARITAL
            * COMMERCIAL
            Default value: TRANSITORY

        condom_usage_sigmoid(Sigmoid, required):
            The new sigmoid to use when determining the probability that a condom is used during a coital act
            within the specified relationship. This overrides the **Condom_Usage_Probablility** for the
            relationship type as defined in the Demographics file.  If None (default), the **Condom_Usage_Probablility**
            is not overridden.
            - **WARNING:** For **STIBarrier**, the 'min' and 'max' values of the sigmoid must be between 0 and 1.

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 usage_expiration_event: str,
                 usage_duration_distribution: BaseDistribution,
                 relationship_type: 'RelationshipType' = RelationshipType.TRANSITORY,
                 condom_usage_sigmoid: Sigmoid = None,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'STIBarrier', common_intervention_parameters)

        if condom_usage_sigmoid is None:
            raise ValueError("'condom_usage_sigmoid' must be defined.")
        else:
            condom_usage_sigmoid.check_value_ranges(class_name="STIBarrier",
                                                    min_low=0, min_high=1,
                                                    max_low=0, max_high=1,
                                                    mid_low=1900, mid_high=2200,
                                                    rate_low=-100, rate_high=100)

        if not isinstance(usage_duration_distribution, BaseDistribution):
            raise ValueError(f"usage_duration_distribution must be an instance of BaseDistribution, not {type(usage_duration_distribution)}.")
        self.set_distribution(usage_duration_distribution, 'Usage_Duration')

        self._intervention.Usage_Expiration_Event = set_event(usage_expiration_event, 'usage_expiration_event', campaign, True)
        self._intervention.Relationship_Type = relationship_type
        self._intervention.Rate = condom_usage_sigmoid.rate
        self._intervention.MidYear = condom_usage_sigmoid.mid
        self._intervention.Late = condom_usage_sigmoid.max
        self._intervention.Early = condom_usage_sigmoid.min

STIIsPostDebut

Bases: IndividualIntervention

The STIIsPostDebut intervention class checks to see if the individual is post-STI debut. Note that this is not connected to IndividualProperties in the demographics file.

User can either set the diagnosis_config parameters: - positive_diagnosis_config (required) - negative_diagnosis_config (optional)

or set the diagnosis_event parameters: - positive_diagnosis_event (required) - negative_diagnosis_event (optional)

but not both.

Parameters:

Name	Type	Description	Default
campaign	campaign	An instance of the emod_api.campaign module.	required
positive_diagnosis_config	IndividualIntervention	The intervention distributed to individuals if they test positive. Default value: None	None
negative_diagnosis_config	IndividualIntervention	The intervention distributed to individuals if they test negative. Default value: None	None
positive_diagnosis_event	str	The event to be broadcast on a positive test result. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	None
negative_diagnosis_event	str	The event to be broadcast on a negative test result. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	None
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 5 common parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class STIIsPostDebut(IndividualIntervention):
    """
    The **STIIsPostDebut** intervention class checks to see if the individual is post-STI debut.
    Note that this is not connected to IndividualProperties in the demographics file.

    User can either set the diagnosis_config parameters:
    - `positive_diagnosis_config` (required)
    - `negative_diagnosis_config` (optional)

    or set the diagnosis_event parameters:
    - `positive_diagnosis_event` (required)
    - `negative_diagnosis_event` (optional)

    but not both.

    Args:
        campaign (api_campaign, optional):
            An instance of the emod_api.campaign module.

        positive_diagnosis_config(IndividualIntervention, optional):
            The intervention distributed to individuals if they test positive.
            Default value: None

        negative_diagnosis_config(IndividualIntervention, optional):
            The intervention distributed to individuals if they test negative.
            Default value: None

        positive_diagnosis_event(str, optional):
            The event to be broadcast on a positive test result. See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
            Default value: None

        negative_diagnosis_event(str, optional):
            The event to be broadcast on a negative test result. See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
            Default value: None

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 5 common
            parameters: cost, intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 positive_diagnosis_config: IndividualIntervention = None,
                 negative_diagnosis_config: IndividualIntervention = None,
                 positive_diagnosis_event: str = None,
                 negative_diagnosis_event: str = None,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'STIIsPostDebut', common_intervention_parameters)

        # Make sure that user only set either config or event, but not both
        if any([positive_diagnosis_config, negative_diagnosis_config]) and any([positive_diagnosis_event, negative_diagnosis_event]):
            raise ValueError('You can only set either diagnosis_config(s) or diagnosis_event(s), but not both.')
        # Make sure that user set either config or event
        if not any([positive_diagnosis_config, negative_diagnosis_config, positive_diagnosis_event,
                    negative_diagnosis_event]):
            raise ValueError('You must set either diagnosis_config(s) or diagnosis_event(s).')

        # Set the intervention based on the provided config
        if positive_diagnosis_config or negative_diagnosis_config:
            if not positive_diagnosis_config:
                raise ValueError('positive_diagnosis_config must be set if you set negative_diagnosis_config.')
            self._intervention.Positive_Diagnosis_Config = positive_diagnosis_config.to_schema_dict()
            if negative_diagnosis_config:
                self._intervention.Negative_Diagnosis_Config = negative_diagnosis_config.to_schema_dict()
            self._intervention.Event_Or_Config = EventOrConfig.Config
            self._intervention.pop("Positive_Diagnosis_Event")
            self._intervention.pop("Negative_Diagnosis_Event")

        # Set the event based on the provided event
        if positive_diagnosis_event or negative_diagnosis_event:
            if not positive_diagnosis_event:
                raise ValueError('positive_diagnosis_event must be set if you set negative_diagnosis_event.')
            self._intervention.Positive_Diagnosis_Event = set_event(positive_diagnosis_event,
                                                                    'positive_diagnosis_event', campaign, False)
            self._intervention.Negative_Diagnosis_Event = set_event(negative_diagnosis_event,
                                                                    'negative_diagnosis_event', campaign, True)
            self._intervention.Event_Or_Config = EventOrConfig.Event
            self._intervention.pop("Positive_Diagnosis_Config")
            self._intervention.pop("Negative_Diagnosis_Config")

SetSexualDebutAge

Bases: IndividualIntervention

The SetSexualDebutAge intervention class is used to set the age of the individual when they start seeking sexual relationships. If the individual's current age is greater than the age being set, they will immediately debut.

This intervention is typically used when setting the configuration parameter Sexual_Debut_Age_Setting_Type to FROM_INTERVENTION. This setting causes all individuals to be initialized with a very large sexual debut age (max float) so that they never debut. The intervention is used to target specific individuals and set their debut age.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
setting_type	SettingType	Use Weibull distribution to initialize sexual debut age or an intervention. Default value: CURRENT_AGE	CURRENT_AGE
distributed_event_trigger	str	The name of the event to be broadcast when the intervention is distributed to an individual. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	None
age_years	float	The age (in years) at which the person receiving the intervention will start seeking sexual relationships. If the person is already order than this age, they will start seeking relationships immediately. You must set Setting_Type to USER_SPECIFIED for the parameter to become activated. Minimum value: 0 Maximum value: 3.40282e+38 Default value: 125	125
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 4 common parameters: intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. The following parameters are not valid for this intervention: cost Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class SetSexualDebutAge(IndividualIntervention):
    """
    The **SetSexualDebutAge** intervention class is used to set the age of the individual when they start
    seeking sexual relationships.  If the individual's current age is greater than the age being set, they
    will immediately debut.

    This intervention is typically used when setting the configuration parameter **Sexual_Debut_Age_Setting_Type**
    to **FROM_INTERVENTION**.  This setting causes all individuals to be initialized with a very large sexual debut
    age (max float) so that they never debut.  The intervention is used to target specific individuals and set their
    debut age.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        setting_type('SettingType', optional):
            Use Weibull distribution to initialize sexual debut age or an intervention.
            Default value: CURRENT_AGE

        distributed_event_trigger(str, optional):
            The name of the event to be broadcast when the intervention is distributed to an individual. See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
            Default value: None

        age_years(float, optional):
            The age (in years) at which the person receiving the intervention will start seeking sexual
            relationships.  If the person is already order than this age, they will start seeking relationships
            immediately. You must set **Setting_Type** to **USER_SPECIFIED** for the parameter to become
            activated.
            Minimum value: 0
            Maximum value: 3.40282e+38
            Default value: 125

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 4 common
            parameters: intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            The following parameters are not valid for this intervention:
            cost
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 setting_type: 'SettingType' = SettingType.CURRENT_AGE,
                 distributed_event_trigger: str = None,
                 age_years: float = 125,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'SetSexualDebutAge', common_intervention_parameters)

        self._intervention.Setting_Type = setting_type
        self._intervention.Distributed_Event_Trigger = set_event(distributed_event_trigger, 'distributed_event_trigger', campaign, True)
        if setting_type == SettingType.USER_SPECIFIED:
            self._intervention.Age_Years = validate_value_range(age_years, 'age_years', 0, 3.40282e+38, float)

    def _set_cost(self, cost: float) -> None:
        raise ValueError('Cost_To_Consumer is not a valid parameter for the SetSexualDebutAge intervention.')

Sigmoid

Defines a sigmoidal curve that can be used to define probabilities versus time.

Parameters:

Name	Type	Description	Default
min	float	The left asymptote for the sigmoid trend over time. The min value must be smaller than the max value. Minimum value: -1 Maximum value: 1 Default value: 0	0
max	float	The right asymptote for the sigmoid trend over time. The max value must be larger than the min value. Minimum value: -1 Maximum value: 1 Default value: 1	1
mid	float	The time of the infection point in the sigmoid trend over time. Minimum value: 1900 Maximum value: 2200 Default value: 2000	2000
rate	float	The slope of the inflection point in the sigmoid trend over time. A Rate of 1 sets the slope to a 25% change in probability per year. Specify a negative Rate (e.g. -1) to achieve a negative sigmoid. Minimum value: -100 Maximum value: 100 Default value: 1	1

Source code in emodpy_hiv/campaign/individual_intervention.py

class Sigmoid:
    """
    Defines a sigmoidal curve that can be used to define probabilities versus time.

    Args:
        min(float, optional):
            The left asymptote for the sigmoid trend over time.  The **min** value must be smaller than the **max** value.
            Minimum value: -1
            Maximum value: 1
            Default value: 0

        max(float, optional):
            The right asymptote for the sigmoid trend over time.  The **max** value must be larger than the **min** value.
            Minimum value: -1
            Maximum value: 1
            Default value: 1

        mid(float, optional):
            The time of the infection point in the sigmoid trend over time.
            Minimum value: 1900
            Maximum value: 2200
            Default value: 2000

        rate(float, optional):
            The slope of the inflection point in the sigmoid trend over time. A Rate of 1 sets the slope to a
            25% change in probability per year. Specify a negative Rate (e.g. -1) to achieve a negative sigmoid.
            Minimum value: -100
            Maximum value: 100
            Default value: 1
    """
    def __init__(self,
                 min: float = 0,
                 max: float = 1,
                 mid: float = 2000,
                 rate: float = 1):
        self.min = validate_value_range(min, 'min', -1, 1, float)
        self.max = validate_value_range(max, 'max', -1, 1, float)
        self.mid = validate_value_range(mid, 'mid', 1900, 2200, float)
        self.rate = validate_value_range(rate, 'rate', -100, 100, float)

        if self.min >= self.max:
            raise ValueError(f"The 'min'(={min}) value must be smaller than the 'max'(={max}) value.")

    def check_value_ranges(self,
                           class_name: str,
                           min_low: float = -1,
                           min_high: float = 1,
                           max_low: float = -1,
                           max_high: float = 1,
                           mid_low: float = 0,
                           mid_high: float = 3.40282e+38,
                           rate_low: float = -100,
                           rate_high: float = 100):
        if self.min < min_low or self.min > min_high:
            raise ValueError(f"For the {class_name} the Sigmoid's 'min'(={self.min}) value must be between {min_low} and {min_high}.")
        if self.max < max_low or self.max > max_high:
            raise ValueError(f"For the {class_name} the Sigmoid's 'max'(={self.max}) value must be between {max_low} and {max_high}.")
        if self.mid < mid_low or self.mid > mid_high:
            raise ValueError(f"For the {class_name} the Sigmoid's 'mid'(={self.mid}) value must be between {mid_low} and {mid_high}.")
        if self.rate < rate_low or self.rate > rate_high:
            raise ValueError(f"For the {class_name} the Sigmoid's 'rate'(={self.rate}) value must be between {rate_low} and {rate_high}.")

    def to_schema_dict(self, campaign) -> s2c.ReadOnlyDict:
        """
        A function that converts the Sigmoid object to a schema dictionary.
        """
        sigmoid = s2c.get_class_with_defaults("idmType:Sigmoid", schema_json=campaign.get_schema())
        sigmoid.Min = self.min
        sigmoid.Max = self.max
        sigmoid.Mid = self.mid
        sigmoid.Rate = self.rate
        sigmoid.finalize()
        return sigmoid

to_schema_dict(campaign)

A function that converts the Sigmoid object to a schema dictionary.

Source code in emodpy_hiv/campaign/individual_intervention.py

def to_schema_dict(self, campaign) -> s2c.ReadOnlyDict:
    """
    A function that converts the Sigmoid object to a schema dictionary.
    """
    sigmoid = s2c.get_class_with_defaults("idmType:Sigmoid", schema_json=campaign.get_schema())
    sigmoid.Min = self.min
    sigmoid.Max = self.max
    sigmoid.Mid = self.mid
    sigmoid.Rate = self.rate
    sigmoid.finalize()
    return sigmoid

StartNewRelationship

Bases: IndividualIntervention

The StartNewRelationship intervention class provides a method of triggering the formation of a relationship following a user-specified event. The parameters of the relationship that is formed can also be customized by the user, such as individual properties required of the partner, or modified condom usage probability within the relationship. Note: These new relationships can be made by people of any age (the intervention disregards IsPostDebut and Sexual_Debut_Age_Min). Additionally, these relationships are considered outside of the Pair Formation Algorithm (PFA), and do not impact/are not impacted by concurrency or pair formation parameters. Coital act and condom usage rate are as per the corresponding relationship type, unless modified by the user.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	An instance of the emod_api.campaign module.	required
relationship_type	RelationshipType	The type of the relationship to start for this person. Possible values are: * TRANSITORY * INFORMAL * MARITAL * COMMERCIAL Default value: TRANSITORY	TRANSITORY
partner_has_ip	str	The IndividualProperty key:value pair that the potential partner must have. Empty string implies no filtering. See :ref:demo-properties parameters for more information. Default value: None	''
relationship_created_event	str	The event trigger to broadcast when a new relationship is created due to the intervention. See :doc:emod-hiv:emod/parameter-campaign-event-list for events already used in EMOD or use your own custom event. Default value: None	''
condom_usage_sigmoid	(Sigmoid, required)	The new sigmoid to use when determining the probability that a condom is used during a coital act within the specified relationship. This overrides the Condom_Usage_Probablility for the relationship type as defined in the Demographics file. If None (default), the Condom_Usage_Probablility is not overridden. - WARNING: For StartNewRelationship, the 'min' and 'max' values of the sigmoid must be between 0 and 1.	None
common_intervention_parameters	CommonInterventionParameters	The CommonInterventionParameters object that contains the 4 common parameters: intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates. The following parameters are not valid for this intervention: cost Default value: None	None

Source code in emodpy_hiv/campaign/individual_intervention.py

class StartNewRelationship(IndividualIntervention):
    """
    The **StartNewRelationship** intervention class provides a method of triggering the formation of a relationship
    following a user-specified event. The parameters of the relationship that is formed can also be customized by
    the user, such as individual properties required of the partner, or modified condom usage probability within
    the relationship. Note: These new relationships can be made by people of any age (the intervention disregards
    **IsPostDebut** and **Sexual_Debut_Age_Min**). Additionally, these relationships are considered outside of the
    Pair Formation Algorithm (PFA), and do not impact/are not impacted by concurrency or pair formation parameters.
    Coital act and condom usage rate are as per the corresponding relationship type, unless modified by the user.

    Args:
        campaign (api_campaign, required):
            An instance of the emod_api.campaign module.

        relationship_type('RelationshipType', optional):
            The type of the relationship to start for this person. Possible values are:
            * TRANSITORY
            * INFORMAL
            * MARITAL
            * COMMERCIAL
            Default value: TRANSITORY

        partner_has_ip(str, optional):
            The **IndividualProperty** key:value pair that the potential partner must have. Empty string
            implies no filtering. See :ref:`demo-properties` parameters for more information.
            Default value: None

        relationship_created_event(str, optional):
            The event trigger to broadcast when a new relationship is created due to the intervention. See
            :doc:`emod-hiv:emod/parameter-campaign-event-list` for events already used in EMOD or use your
            own custom event.
            Default value: None

        condom_usage_sigmoid(Sigmoid, required):
            The new sigmoid to use when determining the probability that a condom is used during a coital act
            within the specified relationship. This overrides the **Condom_Usage_Probablility** for the
            relationship type as defined in the Demographics file.  If None (default), the **Condom_Usage_Probablility**
            is not overridden.
            - **WARNING:** For **StartNewRelationship**, the 'min' and 'max' values of the sigmoid must be between 0 and 1.

        common_intervention_parameters (CommonInterventionParameters, optional):
            The CommonInterventionParameters object that contains the 4 common
            parameters: intervention_name, new_property_value, disqualifying_properties, dont_allow_duplicates.
            The following parameters are not valid for this intervention:
            cost
            Default value: None
    """

    def __init__(self,
                 campaign: api_campaign,
                 relationship_type: 'RelationshipType' = RelationshipType.TRANSITORY,
                 partner_has_ip: str = "",
                 relationship_created_event: str = "",
                 condom_usage_sigmoid: Sigmoid = None,
                 common_intervention_parameters: CommonInterventionParameters = None):
        super().__init__(campaign, 'StartNewRelationship', common_intervention_parameters)

        self._intervention.Relationship_Type = relationship_type
        self._intervention.Relationship_Created_Event = set_event(relationship_created_event, 'relationship_created_event', campaign, True)

        if partner_has_ip:
            self._intervention.Partner_Has_IP = validate_key_value_pair(partner_has_ip)

        if condom_usage_sigmoid is not None:
            condom_usage_sigmoid.check_value_ranges(class_name="StartNewRelationship",
                                                    min_low=0, min_high=1,
                                                    max_low=0, max_high=1,
                                                    mid_low=1900, mid_high=2200,
                                                    rate_low=-100, rate_high=100)
            self._intervention.Condom_Usage_Parameters_Type = CondomUsageParametersType.SPECIFY_USAGE
            self._intervention.Condom_Usage_Sigmoid = condom_usage_sigmoid.to_schema_dict(campaign)
        else:
            self._intervention.Condom_Usage_Parameters_Type = CondomUsageParametersType.USE_DEFAULT

    def _set_cost(self, cost: float) -> None:
        raise ValueError('Cost_To_Consumer is not a valid parameter for the StartNewRelationship intervention.')