emodpy_hiv.campaign.common module#
- class emodpy_hiv.campaign.common.CommonInterventionParameters(cost: float | None = None, disqualifying_properties: list[str] | None = None, dont_allow_duplicates: bool | None = None, intervention_name: str | None = None, new_property_value: str | None = None)#
Bases:
objectA class that is used to configure the common parameters for the intervention classes in the campaign object.
- Parameters:
cost (float, optional) –
The unit ‘cost’ per intervention distributed. For interventions distributed to people, the cost will be added for each person. For internventions distributed to nodes, the cost is for each node. Setting cost to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.
Minimum value: 0.
Maximum value: 99999.
Defaults: None.
disqualifying_properties (list[str], optional) –
A list of IndividualProperty ‘key:value’ pairs that will prevent an intervention from being distributed or applied/updated (persistent interventions will abort/expire in the time step they see the change in their individual property). See :ref:demo-properties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.
Defaults to None.
dont_allow_duplicates (bool, optional) –
If set to True, the intervention is not allowed to be distributed to the same individual more than once.
If set to False, the intervention can be distributed to the same individual multiple times.
If set to None, it will use the Emod default value: False.
Defaults to None.
intervention_name (str, optional) –
The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. If set to None, it will use the name of the intervention class.
Defaults to None.
new_property_value (str, optional) –
An optional IndividualProperty ‘key:value’ pair that will be assigned when the intervention is first applied/updated. See :ref:demo-properties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.
Defaults to None.
- class emodpy_hiv.campaign.common.PropertyRestrictions(individual_property_restrictions: List[List[str]] | None = None, node_property_restrictions: List[List[str]] | None = None)#
Bases:
objectA class that is used to configure the individual property restrictions and node property restrictions in the campaign object.
Please refer to the Emod documentation for NodeProperties and IndividualProperties parameters for more information:
HIV Emod: Demographics parameters
Malaria Emod: Demographics parameters
- Parameters:
individual_property_restrictions (List[List[str]], optional) –
A 2D list contains lists of the IndividualProperty key:value pairs.
These are defined in the demographics.
Individuals must have these properties to be targeted by the intervention.
This parameter allows you to specify AND and OR combinations of key:value pairs. Please see example 1 and 2 for more information.
You can either use this parameter or node_property_restrictions, but not both.
Defaults to None.
node_property_restrictions (List[List[str]], optional) –
A 2D list contains lists of the NodeProperty key:value pairs.
These are defined in the demographics.
Nodes must have these properties to be targeted by the intervention.
You can specify AND and OR combinations of key:value pairs with this parameter. Please see example 3 section for more information.
You can either use this parameter or individual_property_restrictions, but not both.
Defaults to None.
- Raises:
Warnings – if both individual_property_restrictions and node_property_restrictions are not defined.
ValueError – if both individual_property_restrictions and node_property_restrictions are defined.
ValueError – if individual_property_restrictions or node_property_restrictions is not a 2D list(List[List[str]]).
ValueError – if the elements in the inner list are not strings that represent dictionaries key:value pairs with at least one alphanumeric character before and after ‘:’.
Examples
Example 1: This example demonstrates how to specify individual restrictions for targeting specific groups of people who are high risk AND whose InterventionStatus is ARTStaging.
>>> # replace emodpy with emodpy_hiv or emodpy_malaria based on the disease you are working on. >>> from emodpy.campaign.common import PropertyRestrictions >>> from emodpy.campaign.distributor import add_intervention_scheduled >>> property_restrictions = PropertyRestrictions(individual_property_restrictions=[["Risk:HIGH", "InterventionStatus:ARTStaging"]]) >>> add_intervention_scheduled(property_restrictions=property_restrictions, ...) >>> # the result json should look like this: >>> # { >>> # "Property_Restrictions_Within_Node": [ >>> # { >>> # "Risk": "HIGH", >>> # "InterventionStatus": "ARTStaging" >>> # } >>> # ] >>> # }
Example 2: This example demonstrates how to specify individual restrictions for targeting specific groups of people. In this case, we are targeting individuals whose InterventionStatus is set to ARTStaging and who have either HIGH or MEDIUM risk behavior. In other words, we aim to target individuals who meet either of the following conditions:
“InterventionStatus is set to ARTStaging and Risk is set to HIGH”
“InterventionStatus is set to ARTStaging AND Risk is set to MEDIUM”
>>> # replace emodpy with emodpy_hiv or emodpy_malaria based on the disease you are working on. >>> from emodpy.campaign.common import PropertyRestrictions >>> from emodpy.campaign.distributor import add_intervention_scheduled >>> property_restrictions_within_node = PropertyRestrictions( >>> individual_property_restrictions=[ >>> ["Risk:HIGH", "InterventionStatus:ARTStaging"], >>> ["Risk:MEDIUM", "InterventionStatus:ARTStaging"]]) >>> add_intervention_scheduled(property_restrictions=property_restrictions, ...) >>> # the result json should look like this: >>> # { >>> # "Property_Restrictions_Within_Node": [ >>> # { >>> # "Risk": "HIGH", >>> # "InterventionStatus": "ARTStaging" >>> # }, >>> # { >>> # "Risk": "MEDIUM", >>> # "InterventionStatus": "ARTStaging" >>> # } >>> # ] >>> # }
Example 3: This example demonstrates how to use ‘node_property_restrictions’ to specify the NodeProperty. In this case, we are targeting nodes that meet either of the following conditions:
“Risk is set to MEDIUM and Place is set to URBAN”
“Risk is set to LOW and Place is set to RURAL”
>>> # replace emodpy with emodpy_hiv or emodpy_malaria based on the disease you are working on. >>> from emodpy.campaign.common import PropertyRestrictions >>> from emodpy.campaign.distributor import add_intervention_scheduled >>> property_restrictions = PropertyRestrictions( >>> node_property_restrictions=[ >>> ["Risk:MEDIUM", "Place:URBAN"], >>> ["Risk:LOW", "Place:RURAL"]]) >>> add_intervention_scheduled(property_restrictions=property_restrictions, ...) >>> # the result json should look like this: >>> # { >>> # "Node_Property_Restrictions": [ >>> # { >>> # "Risk": "MEDIUM", >>> # "Place": "URBAN" >>> # }, >>> # { >>> # "Risk": "LOW", >>> # "Place": "RURAL" >>> # } >>> # ] >>> # }
- class emodpy_hiv.campaign.common.TargetGender(value)#
Bases:
EnumAn enumeration.
- ALL = 'All'#
- MALE = 'Male'#
- FEMALE = 'Female'#
- class emodpy_hiv.campaign.common.TargetDemographicsConfig(demographic_coverage: float | None = 1.0, target_age_min: float = 0, target_age_max: float = 1000, target_gender: TargetGender = TargetGender.ALL, target_residents_only: bool = False)#
Bases:
objectA class that is used to configure the Demographics_Coverage, Target_Demographic, Target_Age_Min, Target_Age_Max, Target_Gender and Target_Residents_Only in the coordinator class. Please refer to emodpy.campaign.distributor for its usage.
- Parameters:
demographic_coverage (float, optional) –
The fraction of the demographic covered by the event.
Defaults to 1.0.
target_age_min (float, optional) –
The minimum age targeted by the event, in years.
Defaults to 0.
target_age_max (float, optional) –
The maximum age targeted by the event, in years.
Defaults to MAX_AGE_YEARS.
target_gender (Gender, optional) –
A member of the Gender enum indicating the gender targeted by the event.
The function accepts TargetGender.ALL, TargetGender.MALE, or TargetGender.FEMALE as valid inputs.
Defaults to Gender.ALL.
target_residents_only (bool, optional) –
When set to true, the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).
You can use the MigrateIndividuals function to modify an individual’s HOME node. For more details on MigrateIndividuals, refer to the Emod documentation: MigrateIndividuals
Defaults to False.
Examples
>>> # replace emodpy with emodpy_hiv or emodpy_malaria based on the disease you are working on. >>> from emodpy.campaign.common import TargetDemographicsConfig, TargetGender >>> from emodpy.campaign.distributor import add_intervention_scheduled >>> demographics_config = TargetDemographicsConfig(demographic_coverage=0.5, target_age_min=10, >>> target_age_max=20, target_gender=TargetGender.FEMALE) >>> add_intervention_scheduled(demographics_config=demographics_config, ...)
- class emodpy_hiv.campaign.common.RepetitionConfig(number_repetitions: int = 1, timesteps_between_repetitions: int | None = None, infinite_repetitions: bool = False)#
Bases:
objectA class that is used to configure the number of times the intervention event will occur by setting the Number_Repetitions, Timesteps_Between_Repetitions in the Event_Coodinator.
It’s used with emodpy.campaign.distributor.add_intervention_scheduled function.
- Parameters:
number_repetitions (int, optional) –
The number of times the event will occur. If the value is 1, it implies that there will be no repetitions and the event will occur only once.
This parameter accepts integer values that are greater than or equal to 1.
This argument is ignored if infinite_repetitions is set to True.
Defaults to 1.
timesteps_between_repetitions (int, optional) –
The number of timesteps between repetitions.
Used in conjunction with number_repetitions or infinite_repetitions.
If number_repetitions is greater than 1 or infinite_repetitions is set to True, indicating that the event will repeat, timesteps_between_repetitions should be a positive integer interval.
Defaults to None.
infinite_repetitions (bool, optional) –
If set to True, the event will repeat indefinitely.
If True, the number_repetitions argument is ignored and timesteps_between_repetitions must be set to a positive integer.
Defaults to False.
- Raises:
ValueError – if timesteps_between_repetitions is undefined when number_repetitions is used.
Examples
>>> # replace emodpy with emodpy_hiv or emodpy_malaria based on the disease you are working on. >>> from emodpy.campaign.common import RepetitionConfig >>> from emodpy.campaign.distributor import add_intervention_scheduled >>> repetition_config = RepetitionConfig(number_repetitions=2, timesteps_between_repetitions=365) >>> add_intervention_scheduled(repetition_config=repetition_config, ...)
- class emodpy_hiv.campaign.common.ValueMap(times: List[float], values: List[float])#
Bases:
objectCreate a ValueMap object to configure the Times and Values for ValueMap in the campaign_object. This is used, for example, in certain WaningConfig classes to configure Vaccine interventions.
The ValueMap object is initialized with two lists: times and values. The times list represents specific points in time (in years), and the values list represents the corresponding values at those times. Depending on the type of campaign object used, the values are either interpolated linearly or remain constant between the specified times.
Requirements: - The number of elements in the times and values lists must be the same. - The times list must be in ascending order. - Both times and values must be non-negative numbers.
- Parameters:
- to_schema_dict(campaign) ReadOnlyDict[source]#
A function that converts the ValueMap object to a schema dictionary.
- class emodpy_hiv.campaign.common.NChooserTargetedDistributionHIV(age_ranges_years: list[list[float]], num_targeted_females: list[int] | None = None, num_targeted_males: list[int] | None = None, num_targeted: list[int] | None = None, start_year: float = 1900.0, end_year: float = 2200.0, property_restrictions: PropertyRestrictions | None = None, target_disease_state: list[list[emodpy_hiv.utils.emod_enum.TargetDiseaseState]] | None = None, target_disease_state_has_intervention_name: str | None = None)[source]#
Bases:
objectNChooserTargetedDistributionHIV class to create an object specifying when, to whom, and how many interventions are distributed. This class is used in the NChooserEventCoordinatorHIV class.
The number of individuals to distribute interventions to during this time period must be specified by either num_targeted or num_targeted_males and num_targeted_female. These values will be adjusted by x_Base_Population and spread evenly over the time period. Please refer to the emodpy_hiv.campaign.distributor.add_intervention_nchooser_df function for more information in ‘Population Scaling’ and ‘Distribution Over Time’ sections.
- Parameters:
age_ranges_years (list[list[float]], required) –
A 2D list specifying age ranges in years for qualifying individuals.
It should contain 2 lists, the first list is ‘Min’ age and the second list for ‘Max’ age.
An individual is considered in range if their age is greater than or equal to the minimum age and less than the maximum age.
In each age range (minimum age, maximum age), maxinum age must be greater or equal to minimum age.
There should not be overlapping age ranges.
It must have the same number of objects as num_targeted_xxx has elements.
For example, age_ranges_years = [[0, 1, 15, 50], [0.9999999, 14.9999999, 49.9999999, 64.9999999]] means that the intervention will be distributed to individuals with the following age ranges: [0, 0.9999999), [1, 14.9999999), [15, 49.9999999), [50, 64.9999999).
num_targeted_females (list[int], optional) –
The number of female individuals to distribute interventions to during this time period.
Note that this value will be scaled up by the population scaling factor equal to x_Base_Population.
If using this parameter, the length of the list should be the same length as each of the age_ranges_years and num_targeted_males. Cannot be used with num_targeted, leave num_targeted at None.
Minimum value: 0,
Maximum value: 2147480000.
Default value: None.
num_targeted_males (list[int], optional) –
The number of male individuals to distribute interventions to during this time period.
Note that this value will be scaled up by the population scaling factor equal to x_Base_Population.
If using this parameter, the length of the list should be the same length as each of the age_ranges_years and num_targeted_females. Cannot be used with num_targeted, leave num_targeted at None. - Minimum value: 0,
Maximum value: 2147480000.
Default value: None.
num_targeted (list[int], optional) –
The number of individuals to target with the intervention.
Note that this value will be scaled up by the population scaling factor equal to x_Base_Population.
If using this parameter, the length of the list should be the same length as each of the age_ranges_years. Cannot be used with num_targeted_males and num_targeted_female, leave them at None.
Minimum value: 0,
Maximum value: 2147480000,
Default value: None.
start_year (float, optional) –
The year to start distributing the intervention.
Defines the time period to distribute the intervention along with end_year. The intervention is evenly distributed between each time step in the time period.
To have the intervention applied other than at the beginning of the year, you must enter a decimal value after the year. For example, 2010.5 would have the intervention applied halfway through the year 2010.
Minimum value: 1900,
Maximum value: 2200,
Default value: 1900.
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.
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.
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.
Please refer to the Example section for more information about the “and”, “or” relationship in this argument.
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, it’s required when using TargetDiseaseState.HAS_INTERVENTION or TargetDiseaseState.NOT_HAS_INTERVENTION in target_disease_state.
Default value: None.
Examples
Example 1: This example demonstrates how to create a target distribution for Nchooser coordinator to distribute intervention(s) to individuals with specific age ranges. The intervention will be distributed from year 2010 to 2010.999 to MALE individuals with the following age ranges: [0, 0.9999999), [1, 14.9999999), [15, 49.9999999), [50, 64.9999999) and the number of targeted MALE individuals are: [0, 8064, 25054, 179]. While no FEMALE individuals are targeted. The targeted individuals should not have the intervention ‘DMPA_or_control’.
>>> from emodpy_hiv.campaign.common import NChooserTargetedDistributionHIV >>> age_ranges_years = [[0, 1, 15, 50], # Min ages >>> [0.9999999, 14.9999999, 49.9999999, 64.9999999]] # Max ages >>> num_targeted_females = [0, 0, 0, 0] >>> num_targeted_males = [0, 8064, 25054, 179] >>> target_distribution = NChooserTargetedDistributionHIV( >>> 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=[[TargetDiseaseState.NOT_HAVE_INTERVENTION]], >>> target_disease_state_has_intervention_name="DMPA_or_control")
Example 2: Simular to example 1, this example also demonstrates how to create a target distribution to target individuals with specific disease states. In this case, the intervention will be distributed to individuals with the following disease states: (is HIV positive AND on ART) OR (has tested positive AND on ART), meaning that they are on ART and have either tested positive or are HIV positive.
>>> from emodpy_hiv.campaign.common import NChooserTargetedDistributionHIV >>> age_ranges_years = [[0, 1, 15, 50], # Min ages >>> [0.9999999, 14.9999999, 49.9999999, 64.9999999]] # Max ages >>> num_targeted_females = [0, 0, 0, 0] >>> num_targeted_males = [0, 8064, 25054, 179] >>> target_distribution = NChooserTargetedDistributionHIV( >>> 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=[[TargetDiseaseState.HIV_POSITIVE, TargetDiseaseState.HAS_INTERVENTION], >>> [TargetDiseaseState.TESTED_POSITIVE, TargetDiseaseState.HAS_INTERVENTION]], >>> target_disease_state_has_intervention_name="ART")
You can use property_restrictions to target individuals with specific properties that are not disease state specifc. Node property restriction is not supported in this feature. Please see examples in the PropertyRestrictions class.
- to_schema_dict(campaign: <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'>)[source]#
Returns the TargetedDistributionHIV object as a dictionary that match the schema and can be used in the campaign.