emodpy_hiv.country_model module

emodpy_hiv.country_model.get_country_class(country_class_name: str)

Import the countries module and return the class of the country.

Parameters:

country_class_name –

The name of the country to get the class for. The name is expected to be exactly like like it is in its module. Countries with more than one word are expected to have an underscore (‘_’) between the words.

Examples of naming convention: - Zambia should be located in the module emodpy_hiv.countries.zambia.zambia - South Africa should have a class called South_Africa and be in a module called emodpy_hiv.countries.south_africa.south_africa

class emodpy_hiv.country_model.Country

Bases: ABC

Country is an “abstract” base class for HIV models of different countries or regions. It is intended that a person wanting to develop a new model of a country will either subclass Country (or another Country model) and change the things that are different. One could use this to ensure that things that are supposed to be the same across all of the country models are the same.

WARNING: Country models are used as the class and not an instance object. That is, one does not create an object like: * my_country = MyCountry() Instead, they call the classmethods directly from the class like: * demographics = MyCountry.build_demographics() If someone attempts to create an instance, we want it to throw an exception so people don’t use it in a way that is not intended.

WARNING_2: As of Python 3.13, you are not supposed to combine different properties with the classmethod property. It should be used by itself. This is way we are using class variables instead of properties. When we do class inheritance, each subclass gets its own instance of the class variables. For example, if Zambia and Kenya are both subclasss of Country, they will have their own instance of country_name even though it is declared in Country. This allows us to set country_name for Zambia without it impacting Kenya.

NOTE: We are using classes instead of modules because we can still get inheritance like you’d expect. For example, with classes if BaseCountry has three methods: func_A(), func_B(), and func_C(). Assume func_C() calls both func_A() and func_B(). Let’s alo assume that we create Zambia as a subclass of BaseCountry and have it override func_B(). With classes, when func_C()) is called for Zambia, it will use the overridden func_B(). If we tried to do the same thing with modules, func_C() would use the func_B() defined in BaseCountry.

We use Country as a class and this idea of “parameterized calls” so that the country can play well with emod_workflow. The “parameterized calls” need the functions to be static and these calls allow us to give a unique name to each parameter. Unique parameter names allow the user to specifically refer to a parameter even when there are numerous instances of the object that has the parameter.

country_name = None

base_year = 1960.5

static generate_label(relationship_type: str | None = None, risk_group: str | None = None, node_ids: List[int] | None = None, node_name: str | None = None) → str

classmethod get_config_parameterized_calls(config: ReadOnlyDict) → List[ParameterizedCall]

Return a list of ParameterizedCall objects that will complete the configuration of an EMOD config object.

Args

config: The object to be updated when using instance methods with ParameterizedCall.

Returns:

List of ParameterizedCall objects

classmethod get_demographics_parameterized_calls(demographics: HIVDemographics) → List[ParameterizedCall]

Return a list of ParameterizedCall objects that will complete the configuration of an EMOD demographics object.

Args

demographics: If not None, this will be the object that is updated

Returns:

List of ParameterizedCall objects

classmethod get_campaign_parameterized_calls(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'>) → List[ParameterizedCall]

Return a list of ParameterizedCall objects that will complete the configuration of an EMOD campaign object.

Args

campaign: If not None, this will be the object that is updated

Returns:

List of ParameterizedCall objects

classmethod initialize_config(schema_path: str | Path) → ReadOnlyDict

Override this in the subclass to set the default values for the config object as needed.

classmethod initialize_demographics() → HIVDemographics

Create the initial demographics object that will be modified by the ParameterizedCall objects from get_demographics_parameterized_calls()

classmethod initialize_campaign(schema_path: str | Path) → <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'>

Create the initial campaign object that will be modified by the ParameterizedCall objects from get_campaign_parameterized_calls()

classmethod build_reports(reporters: Reporters) → Reporters

Function that creates reports to be used in the experiment. The function must have Reporters object as the parameter and return that object. It is assumed that all the reporters come from the reporters that are part of EMOD main code. EMOD also supports reporters as custom plug-in dlls, however, not through the current emodpy system.

Parameters:

reporters – The Reporters object to add reports to

Returns:

Reporters object

classmethod build_config(config: ReadOnlyDict) → ReadOnlyDict

A function that creates a config object that can be used with EMODTask.from_defaults().

Parameters:

config (ReadOnlyDict) – the config object that will be modified. It has the following structure: config.parameters.<parameter_name> , with <parameter_name> being an attribute.

Returns:

a config object

classmethod build_demographics() → HIVDemographics

A function that configures the demographics for EMOD and can be used with EMODTask.from_defaults().

Returns:

a demographics object

classmethod build_campaign(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'>) → <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'>

A method to pass into EMODTask to build campaign events for Emod.

Parameters:

campaign (emod_api.campaign) – The emod_api campaign object to be modified.

Returns:

a campaign object

static load_nchooser_distribution_data(file_path: str) → dict

Load target distribution data into a dataframe format that works for Nchooser and group by node_id. :param file_path: path to the csv file that contains the data

Returns:

a dictionary that has node_id as the key and a dataframe as the value. The dataframe contains the distribution data for Nchooser.

Return type:

dict

classmethod add_historical_vmmc_nchooser(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'>, historical_vmmc_data_filepath: str, historical_vmmc_reduced_acquire: float = 0.6)

classmethod add_traditional_male_circumcision(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'>, traditional_male_circumcision_coverage: float = 0.5, traditional_male_circumcision_reduced_acquire: float = 0.6, node_ids: ~typing.List[int] | None = None)

classmethod add_vmmc_reference_tracking(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'>, tracking_vmmc_reduced_acquire: float = 0.6)

classmethod seed_infections(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'>, node_ids: ~typing.List[int] | None = None, seeding_start_year: float = 1982, seeding_coverage: float = 0.2, seeding_target_min_age: float = 0, seeding_target_max_age: float = 200, seeding_target_gender: ~emodpy_hiv.campaign.common.TargetGender = TargetGender.ALL)

classmethod add_csw(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'>, csw_male_uptake_coverage: float = 0.1, csw_female_uptake_coverage: float = 0.1, node_ids: ~typing.List[int] | None = None)

classmethod add_post_debut_coinfection(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'>, coinfection_coverage_HIGH: float = 0.3, coinfection_coverage_MEDIUM: float = 0.3, coinfection_coverage_LOW: float = 0.1, node_ids: ~typing.List[int] | None = None)

classmethod add_pmtct(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'>, node_ids: ~typing.List[int] | None = None)

classmethod add_health_care_testing(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'>, hct_delay_to_next_test: ~typing.List[float], hct_delay_to_next_test_node_ids: ~typing.List[~typing.List[int]], hct_delay_to_next_test_node_names: ~typing.List[str], hct_start_year: float = 1990, node_ids: ~typing.List[int] | None = None)

classmethod add_ART_cascade(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'>, art_cascade_start_year: float = 1990, cd4_retention_rate: float = 1, linking_to_pre_art_sigmoid_min: float = 0.7572242198, linking_to_pre_art_sigmoid_max: float = 0.9591484679, linking_to_pre_art_sigmoid_midyear: float = 2006.8336631523, linking_to_pre_art_sigmoid_rate: float = 1.0, pre_staging_retention: float = 0.85, pre_art_retention: float = 0.75, linking_to_art_sigmoid_min: float = 0.0, linking_to_art_sigmoid_max: float = 0.8507390283, linking_to_art_sigmoid_midyear: float = 1997.4462231708, linking_to_art_sigmoid_rate: float = 1.0, art_reenrollment_willingness: float = 0.9, immediate_art_rate: float = 0.1, node_ids: ~typing.List[int] | None = None)

classmethod add_state_TestingOnANC(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'>, node_ids: ~typing.List[int] | None = None)

classmethod add_state_TestingOnChild6w(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'>, node_ids: ~typing.List[int] | None = None)

classmethod add_state_HCTUptakeAtDebut(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'>, start_year: float, node_ids: ~typing.List[int] | None = None)

classmethod add_state_HCTUptakePostDebut(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'>, start_year: float, node_ids: ~typing.List[int] | None = None)

classmethod add_state_HCTTestingLoop(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'>, start_year: float, hct_delay_to_next_test: ~typing.List[float], hct_delay_to_next_test_node_ids: ~typing.List[~typing.List[int]], hct_delay_to_next_test_node_names: ~typing.List[str], node_ids: ~typing.List[int] | None = None)

classmethod add_state_TestingOnSymptomatic(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'>, start_year: float, node_ids: ~typing.List[int] | None = None)

classmethod add_state_ARTStagingDiagnosticTest(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'>, start_year: float, node_ids: ~typing.List[int] | None = None)

classmethod add_state_ARTStaging(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'>, start_year: float, cd4_retention_rate: float = 1, pre_staging_retention: float = 0.85, node_ids: ~typing.List[int] | None = None)

classmethod add_state_LinkingToPreART(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'>, start_year: float, sigmoid_min: float = 0.7572242198, sigmoid_max: float = 0.9591484679, sigmoid_midyear: float = 2006.8336631523, sigmoid_rate: float = 1.0, node_ids: ~typing.List[int] | None = None)

classmethod add_state_OnPreART(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'>, start_year: float, pre_art_retention: float = 0.75, node_ids: ~typing.List[int] | None = None)

classmethod add_state_LinkingToART(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'>, start_year: float, sigmoid_min: float = 0.0, sigmoid_max: float = 0.8507390283, sigmoid_midyear: float = 1997.4462231708, sigmoid_rate: float = 1.0, node_ids: ~typing.List[int] | None = None)

classmethod add_state_OnART(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'>, start_year: float, art_reenrollment_willingness: float = 0.9, immediate_art_rate: float = 0.1, node_ids: ~typing.List[int] | None = None)

classmethod add_state_LostForever(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'>, start_year: float, node_ids: ~typing.List[int] | None = None)