distributor

add_intervention_nchooser_df(campaign, intervention_list, distribution_df, property_restrictions=None, target_disease_state=None, target_disease_state_has_intervention_name=None, event_name=None, node_ids=None)

Overview:

Distributes a list of 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.

Population Scaling:

'N' is assumed to be a number that is for the non-scaled population. This means you can make it the number actually used in the real world. The 'N' values entered will be multiplied by the config parameter x_Base_Population.

For example

• If you wanted to model how the real world distributed 2,000 male circumcisions in 1990 when the total population was 400,000, and your demographic parameters are configured such that EMOD has about 400,000 people in 1990, you would distribute 2,000 male circumcisions.
• If the simulation is taking a long time, and you change config.x_Base_Population to 0.5 to cut the agents in the simulation in half, you would also want to reduce the number of male circumcisions being distributed. This feature will automatically adjust the number being targeted by config.x_Base_Population to only hand out 1,000 male circumcisions.

Distribution Over Time:

NChooser will also spread out the number of interventions being distributed over the entire time period.

For example

• Let's assume that you are trying to distribute MaleCircumcision to 9 men over five update periods. NChooser will give out two interventions the first four update periods and one during the last update period.

DataFrame Requirements:

This function takes in a DataFrame containing the distribution data

• Required columns: year, min_age, max_age
• At least one of the following columns is required: num_targeted, num_targeted_female, num_targeted_male

The data in the DataFrame is used to create a list of NChooserTargetedDistributionHIV objects specifying: - When: with the year data - To whom: with the min_age and max_age data - How many interventions are distributed: with the num_targeted data, or the num_targeted_female for female individuals and num_targeted_male for male individuals

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	The campaign object to which the event will be added. This should be an instance of the emod_api.campaign class.	required
intervention_list	(list[IndividualIntervention], required)	A list of IndividualIntervention objects. NodeIntervention is not supported in this feature. Refer to the emodpy_hiv.campaign.individual_intervention module for available IndividualIntervention derived classes.	required
distribution_df	(DataFrame, required)	A DataFrame containing the data for these columns: year, min_age, max_age, num_targeted, num_targeted_female, num_targeted_male. The first three columns are required, and at least one of the last three columns is required. num_targeted: The number of individuals to be targeted, gender-agnostic. It can't be used with num_targeted_female or num_targeted_male. num_targeted_female: The number of female individuals to be targeted. It can't be used with num_targeted. num_targeted_male: The number of male individuals to be targeted. It can't be used with num_targeted.	required
target_disease_state	list[list[TargetDiseaseState]]	A two-dimensional list of disease states using the TargetDiseaseState enum. To qualify for the intervention, an individual must match at least one of the inner lists of disease states. Each entry in the inner array is an "and" requirement, meaning an individual must match all states in one inner list to qualify. Each inner list is combined with an "or" relationship with other inner list, meaning an individual needs to match at least one of the inner list to qualify. Possible values: Refer to the TargetDiseaseState enum for the possible values. Default value: None.	None
target_disease_state_has_intervention_name	str	The name of the intervention to look for in an individual when targeting specific disease states. It's required when using TargetDiseaseState.HAS_INTERVENTION or TargetDiseaseState.NOT_HAS_INTERVENTION in target_disease_state.	None
property_restrictions	PropertyRestrictions	A PropertyRestrictions to define the individual-level property restrictions in the coordinator. Please note that node property restrictions are not supported in this feature. Default value: None.	None
event_name	str	The name of the campaign event. Default value: None	None
node_ids	list[int]	A list of node IDs where the event will be applied. If None, the event applies to all nodes. Default value: None.	None

Returns:

Name	Type	Description
None	None	This function does not return anything. It modifies the campaign object in place.

Examples:

Example 1: This example demonstrates how to distribute a MaleCircumcision intervention to male individuals who are HIV positive and do not have the intervention already. The intervention is distributed based on the distribution data provided in a DataFrame.

>>> import emod_api
>>> from emodpy_hiv.campaign.distributor import add_intervention_nchooser_df
>>> from emodpy_hiv.campaign.individual_intervention import MaleCircumcision
>>> from emodpy_hiv.campaign.common import CommonInterventionParameters as CIP
>>> from emodpy_hiv.utils.emod_enum import TargetDiseaseState
>>> import pandas as pd
>>>
>>> campaign_obj = emod_api.campaign
>>> campaign_obj.schema_path = 'path_to_schema'
>>> # Initialize a MaleCircumcision intervention with intervention_name: 'MaleCircumcision'
>>> intervention_name='MaleCircumcision'
>>> mc = MaleCircumcision(campaign_obj, common_intervention_parameters=CIP(intervention_name=intervention_name)
>>> # Create a DataFrame with the distribution data: year, min_age, max_age, num_targeted_male
>>> # The intervention will be distributed to MALE individuals with the following values:
>>> #    for the year 2010, age ranges: [1, 14.999), [15, 49.999), the number of targeted MALE individuals are: [200, 1300].
>>> #    for the year 2011, age ranges: [1, 14.999), [15, 49.999), the number of targeted MALE individuals are: [290, 1490].
>>> data = {'year': [2010, 2010, 2011, 2011],
>>>         'min_age': [1, 15, 1, 15],
>>>         'max_age': [14.999, 49.999, 14.999, 49.999],
>>>         'num_targeted_male': [200, 1300, 290, 1490]}
>>> distributions_df = pd.DataFrame.from_dict(data)
>>> # Distribute the MaleCircumcision intervention to the campaign with the distribution data. The targeted
>>> # individuals should be male, HIV negative and don't have an intervention called 'MaleCircumcision' already.
>>> add_intervention_nchooser_df(campaign_obj,
>>>                              intervention_list=[mc],
>>>                              target_disease_state=[[TargetDiseaseState.HIV_POSITIVE, TargetDiseaseState.NOT_HAVE_INTERVENTION]],
>>>                              target_disease_state_has_intervention_name=intervention_name,
>>>                              distribution_df=distributions_df)

Example 2: This example demonstrates the usage of "And" and "Or" relationship in the target_disease_state parameter. With the following target_disease_state parameter, the MaleCircumcision intervention will be distributed to individuals who don't have the intervention already and are either HIV positive or tested positive.

>>> add_intervention_nchooser_df(campaign_obj,
>>>                              intervention_list=[mc],
>>>                              target_disease_state=[[TargetDiseaseState.HIV_POSITIVE, TargetDiseaseState.NOT_HAVE_INTERVENTION],
>>>                                                   [TargetDiseaseState.TESTED_POSITIVE, TargetDiseaseState.NOT_HAVE_INTERVENTION]],
>>>                              target_disease_state_has_intervention_name=intervention_name,
>>>                              distribution_df=distributions_df)

Raises:

Source code in emodpy_hiv/campaign/distributor.py

def add_intervention_nchooser_df(campaign: api_campaign,
                                 intervention_list: list[IndividualIntervention],
                                 distribution_df: pd.DataFrame,
                                 property_restrictions: PropertyRestrictions = None,
                                 target_disease_state: list[list[TargetDiseaseState]] = None,
                                 target_disease_state_has_intervention_name: str = None,
                                 event_name: str = None,
                                 node_ids: list[int] = None) -> None:
    """
    # Overview:

    Distributes a list of 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.

    # Population Scaling:

    'N' is assumed to be a number that is for the non-scaled population. This means you can make it the number actually
    used in the real world. The 'N' values entered will be multiplied by the config parameter `x_Base_Population`.

    For example:
        - If you wanted to model how the real world distributed 2,000 male circumcisions in 1990 when the total
          population was 400,000, and your demographic parameters are configured such that EMOD has about 400,000 people
          in 1990, you would distribute 2,000 male circumcisions.
        - If the simulation is taking a long time, and you change `config.x_Base_Population` to 0.5 to cut the agents in
          the simulation in half, you would also want to reduce the number of male circumcisions being distributed.
          This feature will automatically adjust the number being targeted by `config.x_Base_Population` to only hand
          out 1,000 male circumcisions.

    # Distribution Over Time:

    NChooser will also spread out the number of interventions being distributed over the entire time period.

    For example:
        - Let's assume that you are trying to distribute MaleCircumcision to 9 men over five update periods. NChooser
          will give out two interventions the first four update periods and one during the last update period.

    # DataFrame Requirements:

    This function takes in a DataFrame containing the distribution data:
        - Required columns: `year`, `min_age`, `max_age`
        - At least one of the following columns is required: `num_targeted`, `num_targeted_female`, `num_targeted_male`

    The data in the DataFrame is used to create a list of `NChooserTargetedDistributionHIV` objects specifying:
        - When: with the `year` data
        - To whom: with the `min_age` and `max_age` data
        - How many interventions are distributed: with the `num_targeted` data, or the `num_targeted_female` for female
          individuals and `num_targeted_male` for male individuals

    Args:
        campaign (emod_api.campaign, required):
            - The campaign object to which the event will be added.
            - This should be an instance of the emod_api.campaign class.
        intervention_list (list[IndividualIntervention], required):
            - A list of IndividualIntervention objects. NodeIntervention is not supported in this feature.
            - Refer to the emodpy_hiv.campaign.individual_intervention module for available IndividualIntervention derived classes.
        distribution_df (pd.DataFrame, required):
            - A DataFrame containing the data for these columns: year, min_age, max_age, num_targeted,
              num_targeted_female, num_targeted_male.
            - The first three columns are required, and at least one of the last three columns is required.
            - num_targeted: The number of individuals to be targeted, gender-agnostic. It can't be used with
              num_targeted_female or num_targeted_male.
            - num_targeted_female: The number of female individuals to be targeted. It can't be used with num_targeted.
            - num_targeted_male: The number of male individuals to be targeted. It can't be used with num_targeted.
        target_disease_state (list[list[TargetDiseaseState]], optional):
            - A two-dimensional list of disease states using the TargetDiseaseState enum.
            - To qualify for the intervention, an individual must match at least one of the inner lists of disease states.
            - Each entry in the inner array is an "and" requirement, meaning an individual must match all states in one
              inner list to qualify.
            - Each inner list is combined with an "or" relationship with other inner list, meaning an individual needs
              to match at least one of the inner list to qualify.
            - Possible values: Refer to the TargetDiseaseState enum for the possible values.
            - Default value: None.
        target_disease_state_has_intervention_name (str, optional):
            - The name of the intervention to look for in an individual when targeting specific disease states.
            - It's required when using TargetDiseaseState.HAS_INTERVENTION or TargetDiseaseState.NOT_HAS_INTERVENTION in target_disease_state.
        property_restrictions (PropertyRestrictions, optional):
            - A PropertyRestrictions to define the individual-level property restrictions in the coordinator.
            - Please note that node property restrictions are not supported in this feature.
            - Default value: None.
        event_name (str, optional):
            - The name of the campaign event.
            - Default value: None
        node_ids (list[int], optional):
            - A list of node IDs where the event will be applied.
            - If None, the event applies to all nodes.
            - Default value: None.

    Returns:
            None: This function does not return anything. It modifies the campaign object in place.

    Examples:
        Example 1: This example demonstrates how to distribute a MaleCircumcision intervention to male individuals
        who are HIV positive and do not have the intervention already. The intervention is distributed based on the
        distribution data provided in a DataFrame.

        >>> import emod_api
        >>> from emodpy_hiv.campaign.distributor import add_intervention_nchooser_df
        >>> from emodpy_hiv.campaign.individual_intervention import MaleCircumcision
        >>> from emodpy_hiv.campaign.common import CommonInterventionParameters as CIP
        >>> from emodpy_hiv.utils.emod_enum import TargetDiseaseState
        >>> import pandas as pd
        >>>
        >>> campaign_obj = emod_api.campaign
        >>> campaign_obj.schema_path = 'path_to_schema'
        >>> # Initialize a MaleCircumcision intervention with intervention_name: 'MaleCircumcision'
        >>> intervention_name='MaleCircumcision'
        >>> mc = MaleCircumcision(campaign_obj, common_intervention_parameters=CIP(intervention_name=intervention_name)
        >>> # Create a DataFrame with the distribution data: year, min_age, max_age, num_targeted_male
        >>> # The intervention will be distributed to MALE individuals with the following values:
        >>> #    for the year 2010, age ranges: [1, 14.999), [15, 49.999), the number of targeted MALE individuals are: [200, 1300].
        >>> #    for the year 2011, age ranges: [1, 14.999), [15, 49.999), the number of targeted MALE individuals are: [290, 1490].
        >>> data = {'year': [2010, 2010, 2011, 2011],
        >>>         'min_age': [1, 15, 1, 15],
        >>>         'max_age': [14.999, 49.999, 14.999, 49.999],
        >>>         'num_targeted_male': [200, 1300, 290, 1490]}
        >>> distributions_df = pd.DataFrame.from_dict(data)
        >>> # Distribute the MaleCircumcision intervention to the campaign with the distribution data. The targeted
        >>> # individuals should be male, HIV negative and don't have an intervention called 'MaleCircumcision' already.
        >>> add_intervention_nchooser_df(campaign_obj,
        >>>                              intervention_list=[mc],
        >>>                              target_disease_state=[[TargetDiseaseState.HIV_POSITIVE, TargetDiseaseState.NOT_HAVE_INTERVENTION]],
        >>>                              target_disease_state_has_intervention_name=intervention_name,
        >>>                              distribution_df=distributions_df)

        Example 2: This example demonstrates the usage of "And" and "Or" relationship in the target_disease_state parameter.
        With the following target_disease_state parameter, the MaleCircumcision intervention will be distributed to
        individuals who don't have the intervention already and are either HIV positive or tested positive.

        >>> add_intervention_nchooser_df(campaign_obj,
        >>>                              intervention_list=[mc],
        >>>                              target_disease_state=[[TargetDiseaseState.HIV_POSITIVE, TargetDiseaseState.NOT_HAVE_INTERVENTION],
        >>>                                                   [TargetDiseaseState.TESTED_POSITIVE, TargetDiseaseState.NOT_HAVE_INTERVENTION]],
        >>>                              target_disease_state_has_intervention_name=intervention_name,
        >>>                              distribution_df=distributions_df)

    Raises:

    """
    # These are the columns that are expected in the distribution dataframe
    required_columns = {'year', 'min_age', 'max_age'}
    if not required_columns.issubset(distribution_df.columns):
        raise ValueError(f"Expected these columns: {required_columns} in the distribution_df "
                         f"dataframe. Got distributions.columns: {distribution_df.columns}")

    # Only one of the following names is required.
    optional_columns = {'num_targeted', 'num_targeted_female', 'num_targeted_male'}
    # Check if at least one optional column is present in the distribution dataframe
    if not optional_columns.intersection(distribution_df.columns):
        raise ValueError(f"Expected at least one of these columns: {optional_columns} in the distribution_df "
                         f"dataframe. Got distributions.columns: {distribution_df.columns}")

    # Get the unique value of target years from the distribution dataframe
    target_years = distribution_df.year.unique()
    # Created the distribution objects for each target year
    targeted_distributions = []
    for year in target_years:
        # Filter the distribution dataframe with year
        df_cur_year = distribution_df[distribution_df['year'] == year].sort_values(by=['min_age'])
        # Max and Min age ranges for qualifying individuals.
        age_ranges_years = [df_cur_year['min_age'].tolist(), df_cur_year['max_age'].tolist()]
        num_targeted = None
        num_targeted_female = None
        num_targeted_male = None
        if 'num_targeted' in distribution_df.columns:
            num_targeted = df_cur_year['num_targeted'].tolist()
            if 'num_targeted_female' in distribution_df.columns or 'num_targeted_male' in distribution_df.columns:
                raise ValueError("num_targeted column should not be used with num_targeted_female or num_targeted_male.")
        else:
            if 'num_targeted_female' in distribution_df.columns:
                num_targeted_female = df_cur_year['num_targeted_female'].tolist()
            if 'num_targeted_male' in distribution_df.columns:
                num_targeted_male = df_cur_year['num_targeted_male'].tolist()

            # If one of them is not set, it should contain 0s with the same length as the other one.
            if num_targeted_female is None:
                num_targeted_female = [0] * len(num_targeted_male)
            if num_targeted_male is None:
                num_targeted_male = [0] * len(num_targeted_female)

        targeted_distribution = NChooserTargetedDistributionHIV(age_ranges_years=age_ranges_years,
                                                                start_year=float(year),
                                                                end_year=year + 0.999999,
                                                                num_targeted=num_targeted,
                                                                num_targeted_females=num_targeted_female,
                                                                num_targeted_males=num_targeted_male,
                                                                property_restrictions=property_restrictions,
                                                                target_disease_state=target_disease_state,
                                                                target_disease_state_has_intervention_name=target_disease_state_has_intervention_name)
        targeted_distributions.append(targeted_distribution)

    # Call the add_intervention_nchooser function to distribute the intervention_list with target_distributions
    # Set start_year to the minimum year in the target_years
    start_year = float(min(target_years))
    _add_intervention_nchooser(campaign,
                               intervention_list=intervention_list,
                               targeted_distributions=targeted_distributions,
                               start_year=start_year,
                               event_name=event_name,
                               node_ids=node_ids)

add_intervention_reference_tracking(campaign, intervention_list, time_value_map, tracking_config, start_year, end_year=2200, update_period=365, target_demographics_config=TargetDemographicsConfig(demographic_coverage=None), property_restrictions=None, targeting_config=None, event_name=None, node_ids=None)

Distribute interventions to the population such that a user determined coverage of an attribute is maintained over time.

This function creates a "tracker" that will track the prevalence of a specific attribute in the population and distribute interventions to achieve the desired coverage. The tracker will periodically poll the population to determine the current prevalence of the attribute and distribute the number of interventions needed to get prevalence up to the desired value. If prevalence is higher than the desired value, then no interventions will be distributed. Other things outside of this tracker (like expiration timers in the intervention) maybe needed to cause the coverage to stay down to the desired coverage.

Parameters:

Name	Type	Description	Default
campaign	(campaign, required)	The campaign object to which the intervention will be added.	required
intervention_list	(list[IndividualIntervention], required)	A list of IndividualIntervention objects. NodeIntervention is not supported in this feature. Refer to the emodpy_hiv.campaign.individual_intervention module for available IndividualIntervention derived classes.	required
time_value_map	(ValueMap, required)	A ValueMap object that defines the target coverage levels over time.	required
tracking_config	(AbstractTargetingConfig, required)	An AbstractTargetingConfig object that defines the attribute to be tracked within the targeted group. The number of individuals with this attribute is used as the numerator for coverage calculations. The number of individual selected via targeting_config, target_demographics, and property_restrictions determine the denominator. Please refer to the emodpy_hiv.utils.targeting_config module for more information.	required
start_year	(float, required)	The year to start distributing the intervention. Defines the start of the time period over which the intervention will be distributed. Minimum value: 1900, Maximum value: 2200.	required
end_year	float	The year to stop distributing the intervention. Defines the end of the time period over which the intervention will be distributed. Minimum value: 1900, Maximum value: 2200, Default value: 2200.	2200
update_period	float	The time period in days between when the tracker polls the population and determines if it should distribute more interventions. 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 object that defines individual-level property restrictions for the intervention. Node property restrictions are not supported. 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 note that when defining the target group, you do NOT want to specify the negative what you want to track. because the number of people in the target group is your denominator when calculating coverage. For example, if you want the tracker to have 50% of men circumcised, then you need men who are both circumcised and not circumcised in the denominator and only the number circumcised men in the numerator. Please refer to the emodpy_hiv.utils.targeting_config module for more information. Default value: None.	None
event_name	str	The name of the campaign event. Default value: None.	None
node_ids	list[int]	A list of node IDs to which the intervention should be applied. If None, the intervention is applied to all nodes. Default value: None.	None

Returns:

Name	Type	Description
None	None	This function does not return anything. It modifies the campaign object in place.

Examples:

Use a reference tracker to ensure that the fraction of medium risk men that are circumcised meets certain levels each year from 1960 through 1965 where the tracker is updating who is circumcised every 6 months (182 days) If coverage is below the target level at the time of polling, apply the MaleCircumcision intervention to uncircumcised men to reach the target coverage.

Please note that you don't need to specify the negative of what you want to track(~IsCircumcised()) in the targeting_config. See more details in the targeting_config argument description.

>>> import emod_api
>>> from emodpy_hiv.campaign.distributor import add_intervention_reference_tracking
>>> from emodpy_hiv.campaign.individual_intervention import MaleCircumcision
>>> from emodpy_hiv.campaign.common import (ValueMap, TargetGender, CommonInterventionParameters as CIP,
>>>                                        TargetDemographicsConfig as TDC)
>>> from emodpy_hiv.utils.targeting_config import IsCircumcised, HasIP
>>>
>>> campaign_obj = emod_api.campaign
>>> campaign_obj.schema_path = 'path_to_schema'
>>> mc = MaleCircumcision(campaign_obj,
>>>                       distributed_event_trigger='VMMC_1')
>>> time_value_map = ValueMap(times=[1960,  1961,   1962,   1963,   1964],
>>>                          values=[0.25,  0.375,  0.4,    0.4375, 0.46875])
>>> targeting_config = HasIP(ip_key_value="Risk:MEDIUM")
>>> tracking_config = IsCircumcised()
>>> add_intervention_reference_tracking(campaign_obj,
>>>                                     intervention_list=[mc],
>>>                                     time_value_map=time_value_map,
>>>                                     tracking_config=tracking_config,
>>>                                     targeting_config=targeting_config,
>>>                                     start_year=1960,
>>>                                     end_year=1965,
>>>                                     update_period=182,
>>>                                     target_demographics_config=TDC(target_gender=TargetGender.MALE))

Source code in emodpy_hiv/campaign/distributor.py

def add_intervention_reference_tracking(campaign: api_campaign,
                                        intervention_list: list[IndividualIntervention],
                                        time_value_map: ValueMap,
                                        tracking_config: AbstractTargetingConfig,
                                        start_year: float,
                                        end_year: float = 2200,
                                        update_period: float = 365,
                                        target_demographics_config: TargetDemographicsConfig = TargetDemographicsConfig(demographic_coverage=None),
                                        property_restrictions: PropertyRestrictions = None,
                                        targeting_config: AbstractTargetingConfig = None,
                                        event_name: str = None,
                                        node_ids: list[int] = None) -> None:
    """
    Distribute interventions to the population such that a user determined coverage of an attribute is maintained over
    time.

    This function creates a "tracker" that will track the prevalence of a specific attribute in the population and
    distribute interventions to achieve the desired coverage. The tracker will periodically poll the population to
    determine the current prevalence of the attribute and distribute the number of interventions needed to get
    prevalence up to the desired value. If prevalence is higher than the desired value, then no interventions will be
    distributed. Other things outside of this tracker (like expiration timers in the intervention) maybe needed to
    cause the coverage to stay down to the desired coverage.

    Args:
        campaign (api_campaign, required):
            - The campaign object to which the intervention will be added.
        intervention_list (list[IndividualIntervention], required):
            - A list of IndividualIntervention objects. NodeIntervention is not supported in this feature.
            - Refer to the emodpy_hiv.campaign.individual_intervention module for available IndividualIntervention derived classes.
        time_value_map (ValueMap, required):
            - A ValueMap object that defines the target coverage levels over time.
        tracking_config (AbstractTargetingConfig, required):
            - An AbstractTargetingConfig object that defines the attribute to be tracked within the targeted group.
            - The number of individuals with this attribute is used as the numerator for coverage calculations.
            - The number of individual selected via targeting_config, target_demographics, and property_restrictions determine the denominator.
            - Please refer to the emodpy_hiv.utils.targeting_config module for more information.
        start_year (float, required):
            - The year to start distributing the intervention.
            - Defines the start of the time period over which the intervention will be distributed.
            - Minimum value: 1900,
            - Maximum value: 2200.
        end_year (float, optional):
            - The year to stop distributing the intervention.
            - Defines the end of the time period over which the intervention will be distributed.
            - Minimum value: 1900,
            - Maximum value: 2200,
            - Default value: 2200.
        update_period (float, optional):
            - The time period in days between when the tracker polls the population and determines if it should
              distribute more interventions.
            - 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 object that defines individual-level property restrictions for the intervention.
            - Node property restrictions are not supported.
            - 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 note that when defining the target group, you do NOT want to specify the negative what you want to
              track. because the number of people in the target group is your denominator when calculating coverage.
              For example, if you want the tracker to have 50% of men circumcised, then you need men who are both
              circumcised and not circumcised in the denominator and only the number circumcised men in the numerator.
            - Please refer to the emodpy_hiv.utils.targeting_config module for more information.
            - Default value: None.
        event_name (str, optional):
            - The name of the campaign event.
            - Default value: None.
        node_ids (list[int], optional):
            - A list of node IDs to which the intervention should be applied.
            - If None, the intervention is applied to all nodes.
            - Default value: None.

    Returns:
        None: This function does not return anything. It modifies the campaign object in place.

    Examples:
        Use a reference tracker to ensure that the fraction of medium risk men that are circumcised meets certain
        levels each year from 1960 through 1965 where the tracker is updating who is circumcised every 6 months (182 days)
        If coverage is below the target level at the time of polling, apply the MaleCircumcision
        intervention to uncircumcised men to reach the target coverage.

        Please note that you don't need to specify the negative of what you want to track(~IsCircumcised()) in the
        targeting_config. See more details in the targeting_config argument description.

        >>> import emod_api
        >>> from emodpy_hiv.campaign.distributor import add_intervention_reference_tracking
        >>> from emodpy_hiv.campaign.individual_intervention import MaleCircumcision
        >>> from emodpy_hiv.campaign.common import (ValueMap, TargetGender, CommonInterventionParameters as CIP,
        >>>                                        TargetDemographicsConfig as TDC)
        >>> from emodpy_hiv.utils.targeting_config import IsCircumcised, HasIP
        >>>
        >>> campaign_obj = emod_api.campaign
        >>> campaign_obj.schema_path = 'path_to_schema'
        >>> mc = MaleCircumcision(campaign_obj,
        >>>                       distributed_event_trigger='VMMC_1')
        >>> time_value_map = ValueMap(times=[1960,  1961,   1962,   1963,   1964],
        >>>                          values=[0.25,  0.375,  0.4,    0.4375, 0.46875])
        >>> targeting_config = HasIP(ip_key_value="Risk:MEDIUM")
        >>> tracking_config = IsCircumcised()
        >>> add_intervention_reference_tracking(campaign_obj,
        >>>                                     intervention_list=[mc],
        >>>                                     time_value_map=time_value_map,
        >>>                                     tracking_config=tracking_config,
        >>>                                     targeting_config=targeting_config,
        >>>                                     start_year=1960,
        >>>                                     end_year=1965,
        >>>                                     update_period=182,
        >>>                                     target_demographics_config=TDC(target_gender=TargetGender.MALE))
    """
    if not isinstance(time_value_map, ValueMap):
        raise ValueError("The time_value_map should be an instance of the ValueMap class.")
    # Validate the start_year and end_year
    if end_year <= start_year:
        raise ValueError("The end_year should be greater than the start_year.")
    # All years in ValueMap should be within the start_year and end_year
    if all([year < start_year or year > end_year for year in time_value_map._times]):
        raise ValueError("All years in the time_value_map is not within the start_year and end_year.")
    # At lease one year in the ValueMap is not within the start_year and end_year
    if any([year < start_year or year > end_year for year in time_value_map._times]):
        warnings.warn("At least one year in the time_value_map is not be within the start_year and end_year."
                      "Please make sure that is intended.\n"
                      f"start_year: {start_year}, end_year: {end_year}, years in time_value_map: {time_value_map._times}.",
                      category=UserWarning)

    # Create a ReferenceTrackingEventCoordinatorTrackingConfig with the intervention_list
    coordinator = ReferenceTrackingEventCoordinatorTrackingConfig(campaign,
                                                                  intervention_list=intervention_list,
                                                                  time_value_map=time_value_map,
                                                                  targeting_config=targeting_config,
                                                                  tracking_config=tracking_config,
                                                                  end_year=end_year,
                                                                  update_period=update_period,
                                                                  target_demographics_config=target_demographics_config,
                                                                  property_restrictions=property_restrictions,
                                                                  )
    # Create a CampaignEventByYear object with the coordinator
    event = create_campaign_event(campaign, coordinator=coordinator, event_name=event_name, node_ids=node_ids,
                                  start_day=None, start_year=start_year)

    # Add the event to the campaign
    campaign.add(event.to_schema_dict(campaign))