emodpy_hiv.interventions.nchooser module

emodpy_hiv.interventions.nchooser.new_target_distribution(camp: <module 'emod_api.campaign' from '/home/docs/checkouts/readthedocs.org/user_builds/institute-for-disease-modeling-emodpy-hiv/envs/latest/lib/python3.9/site-packages/emod_api/campaign.py'>, age_ranges_years: ~typing.List[~typing.List[float]], start_year: float, end_year: float, num_targeted_females: ~typing.List[int], num_targeted_males: ~typing.List[int], num_targeted: ~typing.List[int] | None = None, property_restrictions_within_node: ~typing.List[~typing.Dict[str, ~typing.Any]] | None = None, target_disease_state: ~typing.List[~typing.List[str]] | None = None, target_disease_state_has_intervention_name: str | None = None) → Dict[source]

Configures a new target distribution for a campaign, specifying when, to whom, and how many interventions are distributed.

Parameters:

  • camp (campaign) – The campaign object to which the target distribution will be added.

  • age_ranges_years (List[List[Union[float]], List[Union[float]]]) – A 2D list specifying age ranges for qualifying individuals.It should contain 2 lists, the first list is ‘Max’ age and the second list for ‘Min’ age.

  • start_year (float) – The year to start distributing the intervention.

  • end_year (float) – The year to stop distributing the intervention.

  • num_targeted_females (List[int]) – The number of female individuals to target.

  • num_targeted_males (List[int]) – The number of male individuals to target.

  • num_targeted (List[int], optional) – The number of individuals to target with the intervention. Default to None.

  • property_restrictions_within_node (List[Dict[str, Any]], optional) – A list of property restrictions, each represented as a dict with keys as property names and values as property values. Default to None.

  • target_disease_state (List[List[str]], optional) – A 2D list specifying targeted disease states. Default to None. To qualify for the intervention, an individual must have only one of the targeted disease states. An individual must have all the disease states in the inner array. Possible values are: HIV_Positive, HIV_Negative, Tested_Positive, Tested_Negative, Male_Circumcision_Positive, Male_Circumcision_Negative, Has_Intervention, Not_Have_Intervention.

  • target_disease_state_has_intervention_name (str, optional) – The name of the intervention to look for in an individual when targeting specific disease states ( ‘Has_Intervention’ or ‘Not_Have_Intervention’). Default to None.

Returns:

A dictionary representing a target distribution configuration for the campaign.

Example

>>> camp = emod_api.campaign
>>> age_ranges_years = [[0.99999, 14.9999999, 49.9999, 64.9999],   # Max ages
>>>                     [0,       1,          15,      50]]        # Min ages
>>> num_targeted_females = [0,    0,          0,       0]
>>> num_targeted_males = [0, 8064.777513, 25054.39959, 179.0207223]
>>> distribution = new_target_distribution(camp=camp,
>>>                                        age_ranges_years=age_ranges_years,
>>>                                        start_year=2010.0,
>>>                                        end_year=2010.999,
>>>                                        num_targeted_females=num_targeted_females,
>>>                                        num_targeted_males=num_targeted_males,
>>>                                        target_disease_state=[["Not_Have_Intervention"]],
>>>                                        target_disease_state_has_intervention_name="DMPA_or_control")
emodpy_hiv.interventions.nchooser.add_nchooser_event(camp: <module 'emod_api.campaign' from '/home/docs/checkouts/readthedocs.org/user_builds/institute-for-disease-modeling-emodpy-hiv/envs/latest/lib/python3.9/site-packages/emod_api/campaign.py'>, target_distributions: list, intervention_config, start_day: int | float = 1, event_name: str = '', node_ids: ~typing.List[int] | None = None) → None[source]

Creates a new NChooserEventCoordinatorHIV event in the specified EMOD campaign.

This function adds a new event to an EMOD campaign object. It configures the event with specific intervention configurations and distributions, targeting specific nodes from a defined start year.

Please refer to the documentation for NChooserEventCoordinatorHIV at the following link: NChooserEventCoordinatorHIV

Parameters:

  • camp (emod_api.campaign) – The campaign object to which the event will be added. This should be an instance of the emod_api.campaign class.

  • target_distributions (list[TargetedDistributionHIV]) – A list of distribution configurations for the event. Each distribution configuration dictates how the intervention is distributed among the population.

  • intervention_config (Intervention) – An Emod Intervention object.

  • start_day (int | float, optional) – The day when the event starts. Defaults to 1.

  • event_name (str, optional) – The name of the campaign event, default to empty string.

  • node_ids (list of int, optional) – A list of node IDs where the event will be applied. If None, the event applies to all nodes. Defaults to None.

Returns:

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

Return type:

None

Examples

>>> import emod_api
>>> from emodpy_hiv.interventions import malecirc, nchooser
>>>
>>> campaign_obj = emod_api.campaign
>>> intervention_config = malecirc.new_intervention(campaign_obj)
>>> distribution_1 = nchooser.new_target_distribution(campaign_obj, ...)
>>> distribution_2 = nchooser.new_target_distribution(campaign_obj, ...)
>>> distributions = [distribution_1, distribution_2]
>>> nchooser.add_nchooser_event(campaign_obj, distributions, intervention_config, start_day=365,
>>>                             node_ids=[1, 2, 3])
emodpy_hiv.interventions.nchooser.add_nchooser_distributed_circumcision_event(camp: <module 'emod_api.campaign' from '/home/docs/checkouts/readthedocs.org/user_builds/institute-for-disease-modeling-emodpy-hiv/envs/latest/lib/python3.9/site-packages/emod_api/campaign.py'>, target_disease_state: list, has_intervention_name_exclusion: str, distributions: ~pandas.core.frame.DataFrame, property_restrictions: ~typing.List[~typing.Dict[str, ~typing.Any]] | None = None, circumcision_reduced_acquire: float = 0.6, distributed_event_trigger: str = 'Program_VMMC', start_day: int | float = 1, event_name: str = '', node_ids: ~typing.List[int] | None = None) → None[source]

Creates a new NChooserEventCoordinatorHIV event in the specified EMOD campaign with a MaleCircumcision intervention and Distributions specified in distributions dataframe.

Parameters:

  • camp (emod_api.campaign) – The campaign object to which the event will be added. This should be an instance of the emod_api.campaign class.

  • target_disease_state (List[List[str]]) – A 2D list specifying targeted disease states.

  • has_intervention_name_exclusion (str) – The name of the intervention to look for in an individual when targeting specific disease states. It’s also the Intervention_Name of the MaleCircumcision intervention.

  • distributions – A DataFrame contains the data for these columns: year, min_age, max_age, n_circumcisions.

  • property_restrictions (List[Dict[str, Any]], optional) – A list of property restrictions, each represented as a dict with keys as property names and values as property values. Deafult to None.

  • circumcision_reduced_acquire (Float, optional) – Circumcision_Reduced_Acquire parameter: The reduction of susceptibility to STI by voluntary male medical circumcision (VMMC). Default to 0.6.

  • distributed_event_trigger (str, optional) – This is the event that is broadcasted when the circumcision is distributed to the man. One could add it to a report to say count the number of men who were circumcised during the reporting period. Default to ‘Program_VMMC’.

  • start_day (int | float, optional) – The day when the event starts. Defaults to 1.

  • event_name (str, optional) – The name of the campaign event, default to empty string.

  • node_ids (list of int, optional) – A list of node IDs where the event will be applied. If None, the event applies to all nodes. Defaults to None.

Returns:

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

Return type:

None

Examples

>>> import emod_api
>>> from emodpy_hiv.interventions import nchooser
>>> import pandas as pd
>>>
>>> campaign_obj = emod_api.campaign
>>> target_disease_state = [["HIV_Negative", "Not_Have_Intervention"]]
>>> has_intervention_name_exclusion = 'MaleCircumcision'
>>> data = {'year': [2010, 2010, 2011, 2011],
>>>         'min_age': [1, 15, 1, 15],
>>>         'max_age': [14.999, 49.999, 14.999, 49.999],
>>>         'n_circumcisions': [200, 1300, 290, 1490]}
>>> distributions = pd.DataFrame.from_dict(data)
>>> nchooser.add_nchooser_distributed_circumcision_event(campaign_obj, target_disease_state,
>>>                                                      has_intervention_name_exclusion, distributions,
>>>                                                      start_day=365, node_ids=[1, 2, 3])