emodpy.campaign.common module

class emodpy.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: object

A 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.campaign.common.TargetGender(value)

Bases: Enum

An enumeration.

ALL = 'All'

MALE = 'Male'

FEMALE = 'Female'

class emodpy.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: object

A 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.campaign.common.RepetitionConfig(number_repetitions: int = 1, timesteps_between_repetitions: int | None = None, infinite_repetitions: bool = False)

Bases: object

A 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.campaign.common.PropertyRestrictions(individual_property_restrictions: List[List[str]] | None = None, node_property_restrictions: List[List[str]] | None = None)

Bases: object

A 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:

1. “InterventionStatus is set to ARTStaging and Risk is set to HIGH”

2. “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:

1. “Risk is set to MEDIUM and Place is set to URBAN”

2. “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.campaign.common.ValueMap(times: List[float], values: List[float])

Bases: object

Create 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:

• times (List[float]) –

  • A list of times (in years) at which the value changes.

  • The times should be in ascending order.

• values (List[float]) –

  • A list of values that correspond to the times.

  • The list of values should have the same length as times.

to_schema_dict(campaign) → ReadOnlyDict

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