Skip to content

event_coordinator

NChooserEventCoordinatorHIV

Bases: InterventionDistributorEventCoordinator

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

Parameters:

Name Type Description Default
campaign (campaign, required)
  • The campaign object to which the event will be added.
 required
intervention_list (list[IndividualIntervention], required)
  • A list of individual-level interventions to be distributed.
 required
targeted_distributions (list[TargetedDistributionHIV], required)
  • A list of TargetedDistributionHIV objects specifying when, to whom, and how many interventions are distributed.
 required
Source code in emodpy_hiv/campaign/event_coordinator.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
class NChooserEventCoordinatorHIV(InterventionDistributorEventCoordinator):
    """
    The NChooserEventCoordinatorHIV coordinator class distributes individual-level interventions to
    exactly N people of a targeted demographic in HIV simulations. This contrasts with other event coordinators that
    distribute an intervention to a percentage of the population, not to an exact count. This event coordinator is
    similar to the NChooserEventCoordinator for other simulation types, but replaces start and end days in
    TargetedDistribution with start and end years in TargetedDistributionHIV and includes HIV-specific restrictions that
    individuals must have in order to qualify for the intervention.

    Args:
        campaign (api_campaign, required):
            - The campaign object to which the event will be added.
        intervention_list (list[IndividualIntervention], required):
            - A list of individual-level interventions to be distributed.
        targeted_distributions (list[TargetedDistributionHIV], required):
            - A list of TargetedDistributionHIV objects specifying when, to whom, and how many interventions are distributed.
    """
    def __init__(self,
                 campaign: api_campaign,
                 intervention_list: list[IndividualIntervention],
                 targeted_distributions: list[NChooserTargetedDistributionHIV]):
        """
        NChooserEventCoordinatorHIV class to create a
        """
        super().__init__(campaign, "NChooserEventCoordinatorHIV", intervention_list)

        self._coordinator.Distributions = [targeted_distribution.to_schema_dict(campaign)
                                           for targeted_distribution in targeted_distributions]

__init__(campaign, intervention_list, targeted_distributions)

NChooserEventCoordinatorHIV class to create a

Source code in emodpy_hiv/campaign/event_coordinator.py 
31
32
33
34
35
36
37
38
39
40
41
def __init__(self,
             campaign: api_campaign,
             intervention_list: list[IndividualIntervention],
             targeted_distributions: list[NChooserTargetedDistributionHIV]):
    """
    NChooserEventCoordinatorHIV class to create a
    """
    super().__init__(campaign, "NChooserEventCoordinatorHIV", intervention_list)

    self._coordinator.Distributions = [targeted_distribution.to_schema_dict(campaign)
                                       for targeted_distribution in targeted_distributions]

ReferenceTrackingEventCoordinatorTrackingConfig

Bases: InterventionDistributorEventCoordinator

The ReferenceTrackingEventCoordinatorTrackingConfig coordinator class defines a particular prevalence of an individual-level attribute that should be present in a population over time, and a corresponding intervention that will cause individuals to acquire that attribute. The coordinator tracks the actual prevalence of that attribute against the desired prevalence; it will poll the population of nodes it has been assigned to determine how many people have the attribute. When coverage is less than the desired prevalence, it will distribute enough of the designated intervention to reach the desired prevalence. This coordinator is similar to the ReferenceTrackingEventCoordinator, but allows an attribute in the population to be polled, not only the intervention itself having been received. This allows for tracking overall coverage when, potentially, multiple routes exist for individuals to have acquired the same target attribute.

Parameters:

Name Type Description Default
campaign (campaign, required)
  • The campaign object to which the event will be added.
 required
intervention_list (list[IndividualIntervention], required)
  • A list of individual-level interventions to be distributed.
 required
time_value_map (ValueMap, required)
  • A ValueMap object to map coverages over a defined range of time.
 required
tracking_config (AbstractTargetingConfig, required)
  • An AbstractTargetingConfig to define the attribute to be tracked within the targeted group.
  • The number of people that have this attribute is the numerator while the other targeting parameters define the denominator of the coverage.
  • The intervention will be distributed to people without the attribute, if coverage is below the target level the time of polling.
 required
end_year float
  • The year to stop distributing the intervention.
  • Defines the time period to distribute the intervention along with start_year. The intervention is evenly distributed between each time step in the time period.
  • Minimum value: 1900,
  • Maximum value: 2200,
  • Default value: 2200.
 2200
update_period float
  • The time period in days between updates to the intervention distribution.
  • Minimum value: 1,
  • Maximum value: 3650,
  • Default value: 365.
 365
target_demographics_config TargetDemographicsConfig
  • A TargetDemographicsConfig to define the demographic characteristics of individuals targeted by the intervention.
  • Please refer to the emodpy_hiv.campaign.common.TargetDemographicsConfig module for more information.
  • Please note that the demographic_coverage is not used in this coordinator. Use TargetDemographicsConfig(demographic_coverage=None) to avoid errors.
  • Default value: TargetDemographicsConfig(demographic_coverage=None).
 TargetDemographicsConfig(demographic_coverage=None)
property_restrictions PropertyRestrictions
  • A PropertyRestrictions to define the individual-level or node-level property restrictions in the coordinator.
  • Default value: None.
 None
targeting_config AbstractTargetingConfig
  • An AbstractTargetingConfig to define who to target individuals with the intervention besides the target_demographics_config and property_restrictions.
  • Please refer to the emodpy_hiv.utils.targeting_config module for more information.
  • Default value: None.
 required
Source code in emodpy_hiv/campaign/event_coordinator.py 
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
class ReferenceTrackingEventCoordinatorTrackingConfig(InterventionDistributorEventCoordinator):
    """
    The ReferenceTrackingEventCoordinatorTrackingConfig coordinator class defines a particular prevalence of an
    individual-level attribute that should be present in a population over time, and a corresponding intervention that
    will cause individuals to acquire that attribute. The coordinator tracks the actual prevalence of that attribute
    against the desired prevalence; it will poll the population of nodes it has been assigned to determine how many
    people have the attribute. When coverage is less than the desired prevalence, it will distribute enough of the
    designated intervention to reach the desired prevalence. This coordinator is similar to the
    ReferenceTrackingEventCoordinator, but allows an attribute in the population to be polled, not only the intervention
    itself having been received. This allows for tracking overall coverage when, potentially, multiple routes exist for
    individuals to have acquired the same target attribute.

    Args:
        campaign (api_campaign, required):
            - The campaign object to which the event will be added.
        intervention_list (list[IndividualIntervention], required):
            - A list of individual-level interventions to be distributed.
        time_value_map (ValueMap, required):
            - A ValueMap object to map coverages over a defined range of time.
        tracking_config (AbstractTargetingConfig, required):
            - An AbstractTargetingConfig to define the attribute to be tracked within the targeted group.
            - The number of people that have this attribute is the numerator while the other targeting parameters define the denominator of the coverage.
            - The intervention will be distributed to people without the attribute, if coverage is below the target level the time of polling.
        end_year (float, optional):
            - The year to stop distributing the intervention.
            - Defines the time period to distribute the intervention along with start_year. The intervention is evenly distributed between each time step in the time period.
            - Minimum value: 1900,
            - Maximum value: 2200,
            - Default value: 2200.
        update_period (float, optional):
            - The time period in days between updates to the intervention distribution.
            - Minimum value: 1,
            - Maximum value: 3650,
            - Default value: 365.
        target_demographics_config (TargetDemographicsConfig, optional):
            - A TargetDemographicsConfig to define the demographic characteristics of individuals targeted by the intervention.
            - Please refer to the emodpy_hiv.campaign.common.TargetDemographicsConfig module for more information.
            - Please note that the demographic_coverage is not used in this coordinator. Use TargetDemographicsConfig(demographic_coverage=None) to avoid errors.
            - Default value: TargetDemographicsConfig(demographic_coverage=None).
        property_restrictions (PropertyRestrictions, optional):
            - A PropertyRestrictions to define the individual-level or node-level property restrictions in the coordinator.
            - Default value: None.
        targeting_config (AbstractTargetingConfig, optional):
            - An AbstractTargetingConfig to define who to target individuals with the intervention besides the target_demographics_config and property_restrictions.
            - Please refer to the emodpy_hiv.utils.targeting_config module for more information.
            - Default value: None.
    """
    def __init__(self,
                 campaign: api_campaign,
                 intervention_list: list[IndividualIntervention],
                 time_value_map: ValueMap,
                 targeting_config: AbstractTargetingConfig,
                 tracking_config: AbstractTargetingConfig,
                 end_year: float = 2200,
                 update_period: float = 365,
                 target_demographics_config: TargetDemographicsConfig = TargetDemographicsConfig(demographic_coverage=None),
                 property_restrictions: PropertyRestrictions = None):

        super().__init__(campaign, "ReferenceTrackingEventCoordinatorTrackingConfig", intervention_list)

        if not all(isinstance(intervention, IndividualIntervention) for intervention in intervention_list):
            raise ValueError("intervention_list should contain only IndividualIntervention objects.")

        if target_demographics_config is not None:
            if target_demographics_config.demographic_coverage is not None:
                raise ValueError("The demographic_coverage parameter is not used in this coordinator. "
                                 "Use TargetDemographicsConfig(demographic_coverage=None) to avoid errors.")
            target_demographics_config._set_target_demographics(self._coordinator)
        if property_restrictions is not None:
            property_restrictions._set_property_restrictions(self._coordinator)
        if targeting_config is not None:
            self._coordinator.Targeting_Config = targeting_config.to_schema_dict(campaign)

        self._coordinator.End_Year = end_year
        self._coordinator.Update_Period = update_period
        self._coordinator.Time_Value_Map = time_value_map.to_schema_dict(campaign)
        self._coordinator.Tracking_Config = tracking_config.to_simple_dict(campaign)