emodpy-hiv documentation¶

emodpy-hiv is a collection of Python scripts and utilities created to streamline user interactions with EMOD and idmtools for modeling generic diseases. Much of the functionality is inherited from the emod_api package and emodpy package.

Additional information about how to use idmtools can be found at in Welcome to idmtools. Additional information about EMOD HIV parameters can be found in EMOD parameter reference.

If you have questions, see Frequently asked questions for general questions about all emodpy functionality or Frequently asked questions for functionality specific to emodpy-hiv.

See Welcome to idmtools for a diagram showing how idmtools and each of the related packages are used in an end-to-end workflow using EMOD as the disease transmission model.

emodpy-hiv installation¶

Follow the steps below to install emodpy-hiv.

Prerequisites¶

First, ensure the following prerequisites are met.

Windows 10 Pro or Enterprise, Linux, or Mac
Python 3.9 64-bit (https://www.python.org/downloads/release)

A file that indicates the pip index-url:

Windows

Linux
In C:\Users\Username\pip\pip.ini, containing the following:
[global]
index-url = https://packages.idmod.org/api/pypi/pypi-production/simple
In $HOME/.config/pip/pip.conf, containing the following:
[global]
index-url = https://packages.idmod.org/api/pypi/pypi-production/simple

Installation instructions¶

Open a command prompt and create a virtual environment in any directory you choose. The command below names the environment “v-emodpy-hiv”, but you may use any desired name:
```
python -m venv v-emodpy-hiv
```
Activate the virtual environment:
- Windows
- Linux
Enter the following:
v-emodpy-hiv\Scripts\activate
Enter the following:
source v-emodpy-hiv/bin/activate
Install emodpy-hiv packages:
```
pip install emodpy-hiv
```
If you are on Linux, also run:
```
pip install keyrings.alt
```
When you are finished, deactivate the virtual environment by entering the following at a command prompt:
```
deactivate
```

Frequently asked questions¶

As you get started with emodpy-hiv, you may have questions. The most common questions are answered below. For questions related to functionality in related packages, see Frequently asked questions for idmtools, Frequently asked questions for emod-api, and Frequently asked questions for emodpy.

How do I set configuration parameters?¶

Define your own parameter-setting function such as set_param_fn and pass that function to the emodpy task creator as the param_custom_cb parameter. In that function, you can set the parameters directly. For example:

    config.parameters.Enable_Demographics_Reporting = 0  # just because I don't like our default for this

    # config hacks until schema fixes arrive
    config.parameters.Incubation_Period_Exponential = 30 # this should NOT be necessary
    config.parameters.pop( "Serialized_Population_Filenames" )
    config.parameters.pop( "Serialization_Time_Steps" )
    config.parameters.Report_HIV_Event_Channels_List = []
    config.parameters.Male_To_Female_Relative_Infectivity_Ages = [] # 15,25,35 ]
    config.parameters.Male_To_Female_Relative_Infectivity_Multipliers = [] # 5, 1, 0.5 ]
    # This one is crazy! :(
    config.parameters.Maternal_Infection_Transmission_Probability = 0
    config.parameters['logLevel_default'] = "WARNING" # 'LogLevel_Default' is not in scheme, so need to use the old style dict keys
    

    return config


def build_camp():

See examples/start_here/example.py. for additional information.

If you prefer something more modular, you can call a function in a standalone script/file that sets the configuration parameters.

Are there parameter defaults?¶

Great question. If you don’t set any configuration parameters, they will have defaults based on the schema. There are not yet configuration parameter defaults specific to HIV.

The HIV team has some demographic parameter defaults set using emodpy_hiv.demographics.DemographicsTemplates.AddDefaultSociety(). They can be seen in demographics/DemographicsTemplates.py.

How do I create a minimal campaign that just seeds an outbreak?¶

You can use the following code:

def build_campaign():
    import emod_api.campaign as camp
    camp.set_schema( manifest.schema_path ) # don't worry about this for now
    import emodpy_hiv.interventions.outbreak as ob

    event = ob.new_intervention( timestep=365, camp=camp, coverage=0.01 )
    camp.add( event )
    return camp

The code above creates a new intervention from the outbreak submodule that causes 1% of the population to get an infection at timestep 365, and then adds that to the campaign. The only remaining thing to do is pass the ‘build_campaign’ function to the task creator function (‘from_default2’ ). To see the documentation for the hiv outbreak module go here.

How do I give a therapeutic intervention, like ART, to people?¶

We’re going to divide this into 4 steps:

Import the art module for creating the ART intervention.
Create the ART intervention the way you want it.
import and emod_api.interventions.common module for distribution interventions.
Invoke the ScheduledCampaignEvent function.

Let’s look at the code that will go into your build_campaign function::

def build_campaign():
    import emod_api.campaign as camp
    camp.set_schema( manifest.schema_path ) # don't worry about this for now
    import emodpy_hiv.interventions.art as art
    import emod_api.interventions.common as com

    art_iv = art.new_intervention( camp )
    event1 = com.ScheduledCampaignEvent( camp, Start_Day=123, Intervention_List=[ art_iv ] )
    camp.add( event )

    event2 = com.ScheduledCampaignEvent( camp, Start_Day=366, Node_Ids=[ 1 ], Number_Repetitions = 10 Timesteps_Between_Repetitions = 14, Property_Restrictions = "Risk=High",
                                         Demographic_Coverage = 0.04, Target_Age_Min=20*365, Target_Age_Max=25*365, Target_Gender = "Male", Intervention_List=[ art_iv ]) )
    camp.add( event )

The first 4 lines take care of our imports and initializating the campaign module with the schema. The next line creates the simplest possible intervention. Then we create a campaign event that distributes the ART intervention at timestep 123, and we add this to the campaign. Because we leave all the targeting parameters unspecified, the function uses the defaults, which basically means “everybody”. In event2, we use all of the targeting and scheduling parameters to distributing ART every 2 weeks, 10 times in a row, starting at t=366, just in node 1, to 4% of the males between the ages of 20 and 25 in the “High Risk” group based on individual properties. Now in practice the repetitions don’t make much sense because we’re targeting the same people each rep as we got the first time, but it makes the point.

How do I give out an intervention to people based on a trigger instead of at a particular time?¶

The key part here is to use the TriggeredCampaignEvent function instead of ScheduledCampaignEvent. Let’s look at the code::

def build_campaign():
    import emod_api.campaign as camp
    camp.set_schema( manifest.schema_path ) # don't worry about this for now
    import emodpy_hiv.interventions.art as art
    import emod_api.interventions.common as com

    art_iv = art.new_intervention( camp )
    event1 = com.TriggeredCampaignEvent( camp, Start_Day=123, Event_Trigger="NewInfection", Intervention_List=[ art_iv ] )
    camp.add( event )

So we can see that the code is very similar, but we pass a new parameter to this new function, Event_Trigger. This can be any built-in event known to the model – usually related to health events – or an ad-hoc one you publish from another campaign event.

Are there are any helper functions to make this a little more concise?¶

Yes. There is a function to do most of the above for you. But you still create and pass the intervention itself.

What if I want to broadcast an event when I distribute the intervention?¶

You can use the BroadcastEvent function and use that as the intervention or just one of multiple interventions.

What if I want to have a delay between the trigger (signal) and when the intervention is actually distributed?¶

You may want to use this function.

What if I want to change someone’s Individual Property?¶

That’s actually just an intervention, PropertyValueChanger. See an example of this in action.

Now I want to distribute tests and distribute interventions to only those who test positive?¶

First, find the test intervention. This code should now seem unsurprising.:

def build_campaign():
    import emod_api.campaign as camp
    camp.set_schema( manifest.schema_path )
    import emodpy_hiv.interventions.art as art
    import emodpy_hiv.interventions.rapiddiag as diag
    import emod_api.interventions.common as com

    diagnostic = diag.new_intervention( camp )
    art_iv = art.new_intervention( camp )
    test_event = com.TriggeredCampaignEvent( camp, Start_Day=1, Event_Trigger="NewInfection", Intervention_List=[ diagnostic ] )
    treat_event = com.TriggeredCampaignEvent( camp, Start_Day=1, Event_Trigger="TestedPositive", Intervention_List=[ art_iv ] )
    camp.add( test_event )
    camp.add( treat_event )

Testing everyone who is infected is obviously a bit naive but it just shows the idea.

I see lots of HIV_SIM examples. Are there any STI_SIM examples?¶

Not at this time.

I pip installed emodpy-hiv, but I want to make changes. How should I do that?¶

Install at a command prompt using the following:

python package_setup.py develop

This method is the most popular and proven, though there are some other options. Installing this way means that the emodpy-hiv module in site-packages actually points to the same code as you have checked out in git. For more detail, see this Stack Overflow post.

However, we aim to get the desired changes quickly tested and included in the versioned module we release via pip install.

What’s the command to get all the latest (stable) Python packages?¶

::: pip install emodpy_hiv –upgrade –upgrade-strategy eager

How do I install from conda?¶

Once you have a conda environment created and activated, go ahead and conda install pip:

conda install -n emodpy_env pip

And then pip install:

pip install emodpy-hiv -i https://packages.idmod.org/api/pypi/pypi-production/simple

What is the difference between “Transitory” and “Informal” Relationships?¶

See Relationship types and durations. (Transitory relationships are like “one night stands” or commercial relationships whereas Informal are generally intended to represent pre-marital or extra-marital relationships of some length.)

How do Individual Properties like “Risk” change model behaviour if they are just tags?¶

The Demographics parameters docs (Individual and node properties) say that Individual Properties, such as risk and accessibility, do not add logic, in and of themselves. Then how does one make people at “high risk” actually have more sexual partners and other actually more risky behaviors?

The answer is two-fold: 1) Risk is actually a “special IP” in HIV_SIM that we use in PFA configuration. See the set_concurrency_params_by_type_and_risk function for example; and 2) Behavioral interventions can be targeted to people based on Risk.

What is the difference between Individual-Targeted interventions and Node-Targeted interventions?¶

See Individual-level interventions and Node-level interventions. Node interventions tend to be much rarer and are usually “meta-interventions” that are really ways of distributing individual interventions.

API reference¶

emodpy_hiv package¶

Subpackages¶

emodpy_hiv.demographics package¶

Submodules¶

emodpy_hiv.demographics.DemographicsTemplates module¶

emodpy_hiv.demographics.DemographicsTemplates.add_society_from_template(demog, key='default')[source]¶

emodpy_hiv.demographics.DemographicsTemplates.add_default_society(demog)[source]¶: Adds a PFA config based on IDM defaults.

emodpy_hiv.demographics.HIVDemographics module¶

This module contains the classes and functions for creating demographics files for HIV simulations. For more information on EMOD demographics files, see Demographics file.

class emodpy_hiv.demographics.HIVDemographics.HIVDemographics(nodes, idref='Gridded world grump2.5arcmin', base_file=None)[source]¶

Bases: Demographics

This class is derived from emod_api.demographics.Demographics.Demographics and sets certain defaults for HIV in construction.

Parameters:

nodes – The number of nodes to create.
idref – Method describing how the latitude and longitude values are created for each of the nodes in a simulation. “Gridded world” values use a grid overlaid across the globe at some arcsec resolution. You may also generate the grid using another tool or coordinate system. For more information, see Metadata.
base_file – A basic demographics file used as a starting point for creating more complicated demographics files. For example, using a single node file to create a multi-node file for spatial simulations.
init_prev – The initial HIV prevalence of the population.

Returns:

None

fertility(path_to_csv, verbose=False)[source]¶: Set fertility based on data. Simulation shall concist of individual pregnancies with rates by woman’s age and year-of-simulation using data from provided csv.

mortality(file_male, file_female, interval_fit=None, which_point='mid', predict_horizon=2050, csv_out=False, n=0, results_scale_factor=0.0027397260273972603)[source]¶: For back-compat. This function can go away.

apply_assortivity(rel_type, matrix=None)[source]¶

Add an assortivity matrix to Pair-Forming Algo. Right now only applies to RISK IP.

Parameters:

rel_type – “COMMERCIAL”, “INFORMAL”, “MARITAL”, or “TRANSITORY”
matrix – 3x3 matrix of assortivity values, row represents male, column represents female.

Returns:

N/A.

set_concurrency_params_by_type_and_risk(rel_type, ip_value, max_simul_rels_male=None, max_simul_rels_female=None, prob_xtra_rel_male=None, prob_xtra_rel_female=None)[source]¶

Set concurrent relationship formation params for a given relationship type and risk group.

Parameters:

rel_type – Relationship category: “COMMERCIAL”, “MARITAL”, “INFORMAL” or “TRANS”
ip_value – Usually Risk Group but based on defined IP. “High”, “Medium”, or “Low”
max_simul_rels_male – Sets Max_Simultaneous_Relationships_Male.
max_simul_rels_female – Sets Max_Simultaneous_Relationships_Female.
prob_xtra_rel_male – Sets Prob_Extra_Relationship_Male.
prob_xtra_rel_female – Sets Prob_Extra_Relationship_Female.

Returns:

Nothing.

set_pair_form_params(rel_type, new_constant_rate=None)[source]¶

Set Formation_Rate_Constant value for the specified relationship type.

Parameters:

rel_type – Relationship Type. E.g., “MARITAL”
new_constant_rate – New value for Formation_Rate_Constant for the relationship type.

set_coital_act_rate(rel_type, rate=None)[source]¶

Set Coital_Act_Rate value for the specified relationship type.

Parameters:

rel_type – Relationship Type. E.g., “MARITAL”
rate – New value for Coital_Act_Rate for the relationship type.

set_condom_usage_probs(rel_type, min=None, mid=None, max=None, rate=None)[source]¶

Set Condom_Usage_Probability values for the specified relationship type using 4 values to configure a sigmoid.

Parameters:

rel_type – Relationship Type. E.g., “MARITAL”
min – “Min” (a probability)
mid – “Mid” (a year)
max – “Max” (a probability)
rate – “Rate” (a probability)

set_relationship_duration(rel_type, weibull_scale=None, weibull_heterogeneity=None)[source]¶

Set the Weibull configuration values for the draw that determines the duration of relationships of the specified type.

Parameters:

rel_type – Relationship Type. E.g., “MARITAL”
weibull_scale – value of Duration_Weibull_Scale
weibull_heterogeneity – value of Duration_Weibull_Heterogeneity

add_or_update_initial_risk_distribution(distribution=None)[source]¶

emodpy_hiv.demographics.HIVDemographics.from_template_node(lat=0, lon=0, pop=1000000.0, name=1, forced_id=1)[source]¶

Create a single-node HIVDemographics instance from the parameters you supply.

Parameters:

lat – Latitude of the centroid of the node to create.
lon – Longitude of the centroid of the node to create.
pop – Human population of the node.
name – The name of the node. This may be a characteristic of the node, such as “rural” or “urban”, or an identifying integer.
forced_id – The node ID for the single node.

Returns:

A HIVDemographics instance.

emodpy_hiv.demographics.HIVDemographics.from_pop_csv(pop_filename_in, pop_filename_out='spatial_gridded_pop_dir', site='No_Site')[source]¶

Create a multi-node HIVDemographics instance from a CSV file describing a population.

Parameters:

pop_filename_in – The path to the demographics file to ingest.
pop_filename_out – The path to the file to output.
site – A string to identify the country, village, or trial site.

Returns:

A HIVDemographics instance.

emodpy_hiv.demographics.HIVDemographics.from_params(tot_pop=1000000.0, num_nodes=100, frac_rural=0.3, id_ref='from_params')[source]¶

Create a multi-node HIVDemographics instance as a synthetic population based on a few parameters.

Parameters:

tot_pop – The total human population in the node.
num_nodes – The number of nodes to create.
frac_rural – The fraction of the population that is rural.
id_ref – Method describing how the latitude and longitude values are created for each of the nodes in a simulation. “Gridded world” values use a grid overlaid across the globe at some arcsec resolution. You may also generate the grid using another tool or coordinate system. For more information, see Metadata.

Returns:

A HIVDemographics instance.

emodpy_hiv.interventions package¶

Submodules¶

emodpy_hiv.interventions.art module¶

emodpy_hiv.interventions.art.new_intervention(camp, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: AntiRetroviralTherapy intervention wrapper. Just the intervention. No configuration yet.

emodpy_hiv.interventions.art.new_intervention_event(camp, start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: ART intervention as complete (scheduled) event.

emodpy_hiv.interventions.art.new_intervention_as_file(camp, start_day, filename=None)[source]¶

emodpy_hiv.interventions.artdropout module¶

emodpy_hiv.interventions.artdropout.new_intervention(camp, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: ARTDropout intervention wrapper. Just the intervention. No configuration yet.

emodpy_hiv.interventions.artdropout.new_intervention_event(camp, start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: ARTDropout intervention as complete (scheduled) event.

emodpy_hiv.interventions.artdropout.new_intervention_as_file(camp, start_day, filename=None)[source]¶

emodpy_hiv.interventions.artstagingbycd4agnosticdiag module¶

emodpy_hiv.interventions.artstagingbycd4agnosticdiag.new_diagnostic(camp, Positive_Event, Negative_Event, abp_tvmap, abt_tvmap, abw_tvmap, cua_tvmap, cbt_tvmap, cbw_tvmap, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Wrapper function to create and return a HIVARTStagingCD4AgnosticDiagnostic intervention.

Parameters:: camp – emod_api.campaign object with schema_path set.
Returns:: Schema-based smart dictionary representing a new
Return type:: ReadOnlyDict

emodpy_hiv.interventions.artstagingbycd4agnosticdiag.new_intervention_event(camp, pos_event, neg_event, abp_tvmap, abt_tvmap, abw_tvmap, cua_tvmap, cbt_tvmap, cbw_tvmap, start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: Diagnostic as scheduled event.

emodpy_hiv.interventions.artstagingbycd4agnosticdiag.new_intervention_as_file(camp, start_day, filename=None)[source]¶

emodpy_hiv.interventions.artstagingbycd4diag module¶

emodpy_hiv.interventions.artstagingbycd4diag.new_diagnostic(camp, Positive_Event, Negative_Event, Threshold_TVMap, IP_TVMap, IAT_TVMap, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Wrapper function to create and return a HIVARTStagingByCD4Diagnostic intervention.

Parameters:: camp – emod_api.campaign object with schema_path set.
Returns:: Schema-based smart dictionary representing a new
Return type:: ReadOnlyDict

emodpy_hiv.interventions.artstagingbycd4diag.new_intervention_event(camp, pos_event, neg_event, thresh_tvmap, pregnant_tvmap, tb_tvmap, start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: Diagnostic as scheduled event.

emodpy_hiv.interventions.artstagingbycd4diag.new_intervention_as_file(camp, start_day, filename=None)[source]¶

emodpy_hiv.interventions.cascade_helpers module¶

emodpy_hiv.interventions.cascade_helpers.reset(camp)[source]¶

Utility function to clear out the campaign object, mostly useful to test. This function is not auto-imported with the module like the rest of the functions in this submodule. Caller has to explicitly import emodpy_hiv.interventions.cascade_helpers. :param camp: emod_api.campaign object.

Returns:: None.

emodpy_hiv.interventions.cascade_helpers.seed_infection(camp, timestep, coverage)[source]¶: Seed an infection by time and %age of population infected.

emodpy_hiv.interventions.cascade_helpers.triggered_event_common(camp, in_trigger, out_iv, coverage=1.0, target_sex='All', property_restrictions: List[str] | None = None, event_name='', node_ids: List[int] | None = None, start_day: int = 1, target_age_min: float = 0, target_age_max: float = 73000, delay: float | None = None)[source]¶

Parameterized utility function used by rest of functions in this submodule; listens for a trigger (signal) and distributes an intervention (or list thereof) as a result, based on coverage and targeting.

Parameters:

camp – The central campaign accumulator, from emod_api.campaign.
in_trigger – The trigger aka signal for the event. E.g., “NewInfection”
out_iv – The output intervention of the event.
coverage (float) – The coverage of the event (default is 1.0).
target_sex (str) – The target sex for the event (default is “All”).
property_restrictions (list[str]) – A list of IP restrictions in “Risk:HIGH” format. None means no restrictions.
event_name (str) – The name of the event (default is an empty string).
node_ids – (list[int]) A list of node ids to apply the event to. None means all nodes.
start_day – (int) The model simulation time to start the event.

Returns:

New campaign event.

emodpy_hiv.interventions.cascade_helpers.add_triggered_event(camp, in_trigger, out_iv, coverage=1.0, target_sex='All', property_restrictions: List[str] | None = None, event_name='', node_ids: List[int] | None = None, start_day: int = 1, target_age_min: float = 0, target_age_max: float = 73000, delay: float | None = None)¶

Parameterized utility function used by rest of functions in this submodule; listens for a trigger (signal) and distributes an intervention (or list thereof) as a result, based on coverage and targeting.

Parameters:

camp – The central campaign accumulator, from emod_api.campaign.
in_trigger – The trigger aka signal for the event. E.g., “NewInfection”
out_iv – The output intervention of the event.
coverage (float) – The coverage of the event (default is 1.0).
target_sex (str) – The target sex for the event (default is “All”).
property_restrictions (list[str]) – A list of IP restrictions in “Risk:HIGH” format. None means no restrictions.
event_name (str) – The name of the event (default is an empty string).
node_ids – (list[int]) A list of node ids to apply the event to. None means all nodes.
start_day – (int) The model simulation time to start the event.

Returns:

New campaign event.

emodpy_hiv.interventions.cascade_helpers.add_scheduled_event(camp, out_iv, coverage=1.0, target_sex='All', property_restrictions: List[str] | None = None, event_name='', node_ids: List[int] | None = None, start_day: int = 1)[source]¶

emodpy_hiv.interventions.cascade_helpers.add_reference_tracked_event(camp, out_iv, time_value_map: dict, event_name: str = '', target_min_age: float = 0, target_max_age: float = 200, target_sex: str = 'All', target_disease_state: str | None = None, update_period: float = 30.4166666666667, start_day: float = 1960.5, node_ids: List[int] | None = None)[source]¶

emodpy_hiv.interventions.cascade_helpers.add_choice(camp, sympto_signal='NewlySymptomatic', get_tested_signal='GetTested')[source]¶

Listen for a trigger. Defaults to ‘NewlySymptomatic’. Then toss a fair coin; in case of heads, Distribute diagnostic (and publish signal – default is ‘GetTested’; tails maybe it’s just a cold (‘Ignore’).

Parameters:

camp – The central campaign accumulator, from emod_api.campaign.
sympto_signal (str) – The signal or trigger we are listening for. Doesn’t have to be anything to do with

symptomaticity but defaults to “NewlySymptomatic”.: get_tested_signal (str): The signal/trigger published if coin toss is heads and person gets tested.

emodpy_hiv.interventions.cascade_helpers.add_test(camp, get_tested_signal='GetTested')[source]¶: Listen for get_tested_signal signal (defaults to “GetTested”). Then give HIV RapidDiagnostic test after a delay of 30 days. Publish ‘HIVPositiveTest’ on +ve or ‘HIVNegativeTest’ on -ve.

emodpy_hiv.interventions.cascade_helpers.trigger_art_from_pos_test(camp, input_signal='HIVPositiveTest', output_signal='StartTreatment', lag_time=30)[source]¶: Listen for HIVPositiveTest trigger. Then Trigger ART. Note that Trigger ART isn’t same as starting it.

emodpy_hiv.interventions.cascade_helpers.add_art_from_trigger(camp, signal='StartTreatment')[source]¶: Actually distribute ART if a StartTreatment signal/trigger is observed. Broadcast a StartedART signal synchronously.

emodpy_hiv.interventions.cascade_helpers.trigger_art(camp, timestep, coverage, trigger='StartTreatment')[source]¶: Schedule a broadcast of StartTreatment (or equivalent), not based on any observed signals.

emodpy_hiv.interventions.delay module¶

emodpy_hiv.interventions.delay.new_delay(camp, Bcast_Event, Expire_Event='', Coverage=1, Delay=1, Shelf_Life=36500, Name='', intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Wrapper function to create and return a HIVDelayedIntervention intervention.

Parameters:: camp – emod_api.campaign object with schema_path set.
Returns:: Schema-based smart dictionary representing a new
Return type:: ReadOnlyDict

emodpy_hiv.interventions.delay.new_intervention_event(camp, bcast_event, expire_event='', coverage=1, delay=1, shelf_life=0, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: Delay as scheduled event.

emodpy_hiv.interventions.delay.new_intervention_as_file(camp, start_day, filename=None)[source]¶

emodpy_hiv.interventions.drawblood module¶

emodpy_hiv.interventions.drawblood.new_diagnostic(camp, Positive_Event, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Wrapper function to create and return a HIVDrawBlood intervention.

Parameters:: camp – emod_api.campaign object with schema_path set.
Returns:: Schema-based smart dictionary representing a new
Return type:: ReadOnlyDict

emodpy_hiv.interventions.drawblood.new_intervention_event(camp, pos_event, start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: Diagnostic as scheduled event.

emodpy_hiv.interventions.drawblood.new_intervention_as_file(camp, start_day, filename=None)[source]¶

emodpy_hiv.interventions.hivmuxer module¶

emodpy_hiv.interventions.hivmuxer.new_intervention(camp: <module 'emod_api.campaign' from '/home/docs/checkouts/readthedocs.org/user_builds/institute-for-disease-modeling-emodpy-hiv/envs/stable/lib/python3.9/site-packages/emod_api/campaign.py'>, muxer_name: str, delay_complete_event: str, delay_distribution: str, delay_period_exponential: float | None = None, delay_period_kappa: float | None = None, delay_period_lambda: float | None = None, delay_period_constant: float | None = None, disqualifying_properties: ~typing.List[str] | None = None, max_entries: float = 1, new_property_value: str | None = None)[source]¶

Create a HIVMuxer intervention object and return it. Please refer to the documentation for HIVMuxer at the following link: HIVMuxer

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.
muxer_name (str) – A name used to identify the delay and check whether individuals have entered it multiple times. If the same name is used at multiple points in the health care process, then the number of entries is combined when Max_Entries is applied.
delay_complete_event (str) – The event that should occur at the end of the delay period.
delay_distribution (str) – The delay distribution type for the event. Possible values are CONSTANT_DISTRIBUTION, EXPONENTIAL_DISTRIBUTION and WEIBULL_DISTRIBUTION.
delay_period_exponential (float, optional) – The mean for an exponential distribution. Required for delay_distribution = EXPONENTIAL_DISTRIBUTION. Defaults to None.
delay_period_kappa (float, optional) – The shape value in a Weibull distribution. Required for delay_distribution = WEIBULL_DISTRIBUTION. Defaults to None.
delay_period_lambda (float, optional) – The scale value in a Weibull distribution. Required for delay_distribution = WEIBULL_DISTRIBUTION. Defaults to None.
delay_period_constant (float, optional) – The constant delay period. Required for delay_distribution = CONSTANT_DISTRIBUTION. Defaults to None.
disqualifying_properties (List[str], optional) – A list of IndividualProperty key:value pairs that cause an intervention to be aborted. 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.
max_entries (float, optional) – The maximum number of times the individual can be registered with the HIVMuxer delay. Determines what should happen if an individual reaches the HIVMuxer stage of health care multiple times. Defaults to 1.
new_property_value (str, optional) – An optional IndividualProperty key:value pair that will be assigned when the intervention is first updated. 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.

Returns:

intervention

Raises:

ValueError – If invalid input is provided.

emodpy_hiv.interventions.hivmuxer.add_hiv_muxer_event_with_trigger(camp: <module 'emod_api.campaign' from '/home/docs/checkouts/readthedocs.org/user_builds/institute-for-disease-modeling-emodpy-hiv/envs/stable/lib/python3.9/site-packages/emod_api/campaign.py'>, start_day: int, event_trigger_list: ~typing.List[str], muxer_name: str, delay_complete_event: str, delay_distribution: str, delay_period_exponential: float | None = None, delay_period_kappa: float | None = None, delay_period_lambda: float | None = None, delay_period_constant: float | None = None, disqualifying_properties: ~typing.List[str] | None = None, demographic_coverage: float = 1, event_name: str = 'HIVMuxer with NLHTI', new_property_value: str | None = None, node_ids: ~typing.List[int] | None = None) → None[source]¶

Add HIVMuxer intervention with NodeLevelHealthTriggeredIV to campaign object Please refer to the documentation for HIVMuxer at the following link: HIVMuxer

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.
start_day (int) – The starting day for the event.
event_trigger_list (list) – A list of triggers for the event.
muxer_name (str) – A name used to identify the delay and check whether individuals have entered it multiple times. If the same name is used at multiple points in the health care process, then the number of entries is combined when Max_Entries is applied.
delay_complete_event (str) – The event that should occur at the end of the delay period.
delay_distribution (str) – The delay distribution type for the event. Possible values are CONSTANT_DISTRIBUTION, EXPONENTIAL_DISTRIBUTION and WEIBULL_DISTRIBUTION.
delay_period_exponential (float, optional) – The mean for an exponential distribution. Required for delay_distribution = EXPONENTIAL_DISTRIBUTION. Defaults to None.
delay_period_kappa (float, optional) – The shape value in a Weibull distribution. Required for delay_distribution = WEIBULL_DISTRIBUTION. Defaults to None.
delay_period_lambda (float, optional) – The scale value in a Weibull distribution. Required for delay_distribution = WEIBULL_DISTRIBUTION. Defaults to None.
delay_period_constant (float, optional) – The constant delay period. Required for delay_distribution = CONSTANT_DISTRIBUTION. Defaults to None.
disqualifying_properties (List[str], optional) – A list of IndividualProperty key:value pairs that cause an intervention to be aborted. 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.
demographic_coverage (float, optional) – The demographic coverage for the event. Defaults to 1.
event_name (str, optional) – The name of the event. Defaults to ‘HIVMuxer with NLHTI’.
new_property_value (str, optional) – An optional IndividualProperty key:value pair that will be assigned when the intervention is first updated. 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.
node_ids (List[int], optional) – A list of node IDs. Defaults to None.

Returns:

None

Raises:

ValueError – If invalid input is provided.

Example

>>> add_hiv_muxer_event_with_trigger(
>>>     camp,
>>>     start_day=10,
>>>     event_trigger_list=['HCTUptakePostDebut1'],
>>>     muxer_name='HCTUptakePostDebut',
>>>     new_property_value='CascadeState:HCTUptakePostDebut',
>>>     delay_complete_event='HCTUptakePostDebut2',
>>>     delay_distribution='EXPONENTIAL_DISTRIBUTION',
>>>     delay_period_exponential=0.5,
>>>     disqualifying_properties=[
>>>                     "CascadeState:LostForever",
>>>                     "CascadeState:OnART",
>>>                     "CascadeState:LinkingToART",
>>>                     "CascadeState:OnPreART",
>>>                     "CascadeState:LinkingToPreART",
>>>                     "CascadeState:ARTStaging",
>>>                     "CascadeState:HCTTestingLoop"],
>>>     demographic_coverage=0.5,
>>>     node_ids=[1, 2, 3]
>>> )

emodpy_hiv.interventions.malecirc module¶

emodpy_hiv.interventions.malecirc.new_intervention(camp, reduced_acquire=0.6, distributed_event='', intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: MaleCircumcision intervention wrapper. Just the intervention. No configuration yet.

emodpy_hiv.interventions.malecirc.new_intervention_event(camp, start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: VMMC intervention as complete (scheduled) event.

emodpy_hiv.interventions.malecirc.new_intervention_as_file(camp, start_day, filename=None)[source]¶

emodpy_hiv.interventions.modcoinf module¶

emodpy_hiv.interventions.modcoinf.new_intervention(camp)[source]¶: ModifySTICoInfection intervention wrapper. Just the intervention. No configuration yet.

emodpy_hiv.interventions.modcoinf.new_intervention_event(camp, start_day=1, coverage=1.0, node_ids=None)[source]¶: ModifySTICoInfection intervention as complete (scheduled) event.

emodpy_hiv.interventions.modcoinf.new_intervention_as_file(camp, start_day, filename=None)[source]¶

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/stable/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/stable/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/stable/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])

emodpy_hiv.interventions.outbreak module¶

emodpy_hiv.interventions.outbreak.new_intervention(timestep, camp, coverage=0.01)[source]¶

Seed HIV infection at a certain timestep, with a certain prevalence.

Parameters:

timestep (float) – When? Timestep at which outbreak should occur.
camp – emod_api.campaign object that has schema_path.
coverage – How Much? The intended level of initial prevalance.

Returns:

event as dict

Return type:

event

emodpy_hiv.interventions.outbreak.seed_infections(camp: <module 'emod_api.campaign' from '/home/docs/checkouts/readthedocs.org/user_builds/institute-for-disease-modeling-emodpy-hiv/envs/stable/lib/python3.9/site-packages/emod_api/campaign.py'>, start_day: int = 365, coverage: float = 0.075, target_properties: list | None = None, target_min_age: float = 0, target_max_age: float = 125, target_gender: str = 'All', node_ids: ~typing.List[int] | None = None, event_name='')[source]¶: Create outbreak event with more targeting than ‘new_intervention’.

emodpy_hiv.interventions.pmtct module¶

emodpy_hiv.interventions.pmtct.new_intervention(camp, efficacy=1.0, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: PMTCT intervention wrapper. Just the intervention. No configuration yet.

emodpy_hiv.interventions.pmtct.new_intervention_event(camp, start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: PMTCT intervention as complete (scheduled) event.

emodpy_hiv.interventions.pmtct.new_intervention_as_file(camp, start_day, filename=None)[source]¶

emodpy_hiv.interventions.prep module¶

emodpy_hiv.interventions.prep.new_intervention(camp, efficacy_times=[0, 365], efficacy_values=[0.5, 0], intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Create a new PrEP (Pre-Exposure Prophylaxis) intervention.

This function creates and configures a new PrEP intervention using the provided efficacy times and values.

Parameters:

camp (emod_api.campaign) – The central campaign builder object.
efficacy_times (list of float) – A list of times at which the PrEP efficacy changes. Times must be > 0 and in ascending order.
efficacy_values (list of float) – A list of efficacy values corresponding to the times. Values must be between 0 and 1.
intervention_name (str) – The name of the intervention.
disqualifying_properties (list of str) – A list of IndividualProperty key:value pairs that cause an intervention to be aborted
new_property_value (str) – An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed.

Returns:

A new PrEP intervention with the specified efficacy configuration, which can be passed to a scheduled or triggered campaign event function.

Raises:

ValueError – If the lengths of efficacy_times and efficacy_values do not match.
ValueError – If any time value in efficacy_times is not greater than 0.
ValueError – If the time values in efficacy_times are not in ascending order.
ValueError – If any value in efficacy_values is not between 0 and 1.

Example:

camp.set_schema("path/to/schema.json")
times = [1, 2, 3, 4, 5, 6, 7]
values = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7]
intervention = new_intervention(camp, times, values)

emodpy_hiv.interventions.prep.new_intervention_event(camp, efficacy_times=[0, 365], efficacy_values=[0.5, 0], start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Create a new PrEP (Pre-Exposure Prophylaxis) intervention as complete (scheduled) event.

This function creates and configures a new PrEP intervention using the provided efficacy times and values, and adds it to a scheduled event. You need to add it to the campaign.

Parameters:

camp (emod_api.campaign) – The central campaign builder object.
efficacy_times (list of float) – A list of times at which the PrEP efficacy changes. Times must be > 0 and in ascending order.
efficacy_values (list of float) – A list of efficacy values corresponding to the times. Values must be between 0 and 1.
start_day (int) – When this campaign event should occur.
coverage (float) – Who should get this – i.e., what percentage of the population.
node_ids (list of integers) – Where this campaign event should be distributed. Leave as default if ‘everywhere’.
intervention_name (str) – The name of the intervention.
disqualifying_properties (list of str) – A list of IndividualProperty key:value pairs that cause an intervention to be aborted
new_property_value (str) – An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed.

Returns:

A new PrEP intervention with the specified efficacy configuration, which can be passed to a scheduled or triggered campaign event function.

Raises:

ValueError – If the lengths of efficacy_times and efficacy_values do not match.
ValueError – If any time value in efficacy_times is not greater than 0.
ValueError – If the time values in efficacy_times are not in ascending order.
ValueError – If any value in efficacy_values is not between 0 and 1.

Example:

camp.set_schema("path/to/schema.json")
times = [1, 2, 3, 4, 5, 6, 7]
values = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7]
event = new_intervention_event(camp, times, values, start_day=730, coverage=0.33, node_ides[ 1, 4, 5 ])

emodpy_hiv.interventions.prep.new_intervention_as_file(camp, start_day, filename=None)[source]¶

emodpy_hiv.interventions.randomchoice module¶

emodpy_hiv.interventions.randomchoice.new_diagnostic(camp, choices, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Wrapper function to create and return a HIVRandomChoice intervention.

Parameters:

camp – emod_api.campaign object with schema_path set.
choices – dict of events:probability, with probs summing up to 1.0
intervention_name (str) – The name of the intervention.
disqualifying_properties (list of str) – A list of IndividualProperty key:value pairs that cause an intervention to be aborted
new_property_value (str) – An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed.

Returns:

Schema-based smart dictionary representing a new

Return type:

ReadOnlyDict

emodpy_hiv.interventions.randomchoice.new_intervention_event(camp, choices, start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: Diagnostic as scheduled event.

emodpy_hiv.interventions.randomchoice.new_intervention_as_file(camp, start_day, choices, filename=None)[source]¶

emodpy_hiv.interventions.rapiddiag module¶

emodpy_hiv.interventions.rapiddiag.new_diagnostic(camp, Positive_Event, Negative_Event, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Wrapper function to create and return a HIVRapidHIVDiagnostic intervention.

Parameters:

camp – emod_api.campaign object with schema_path set.
intervention_name (str) – The name of the intervention.
disqualifying_properties (list of str) – A list of IndividualProperty key:value pairs that cause an intervention to be aborted
new_property_value (str) – An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed.

Returns:

Schema-based smart dictionary representing a new

Return type:

ReadOnlyDict

emodpy_hiv.interventions.rapiddiag.new_intervention_event(camp, pos_event, neg_event, start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: Diagnostic as scheduled event.

emodpy_hiv.interventions.rapiddiag.new_intervention_as_file(camp, start_day, filename=None)[source]¶

emodpy_hiv.interventions.reftracker module¶

emodpy_hiv.interventions.reftracker.DistributeIVByRefTrack(camp, Start_Day, Intervention, TVMap, node_ids=None, Event_Name='Scheduled_Campaign_Event', Property_Restrictions=None, Target_Age_Min=0, Target_Age_Max=45625, Target_Gender='All', Update_Period=None, IV_Tracking_Name=None, Target_Disease_State=None)[source]¶

Wrapper function to create and return a ScheduledCampaignEvent intervention. The alternative to a ScheduledCampaignEvent is a TriggeredCampaignEvent.

Parameters:

camp – emod_api.campaign object with schema_path set.
Start_Day – When to start.
Intervention – Valid intervention to be distributed together as necessary to track coverage targets. Can be single intervention or list (list is useful where you want a co-event). If list, actual intervention should be first.
Event_Name – Name for overall campaign event, of not functional meaning.
node_ids – Nodes to target with this intervention, return from utils.do_nodes().
Property_Restrictions – Individual Properties a person must have to receive the intervention(s).
Number_Repetitions – N/A
Timesteps_Between_Repetitions – N/A
Target_Demographic – Everyone, ExplicitAgeRanges, etc.
Target_Age_Min – Minimum age (in years).
Target_Age_Max – Maximum age (in years).
Target_Gender – All, Male, or Female.
Update_Period – Number representing how frequently the distributions are done.
IV_Tracking_Name – Optional string parameter to distinguish one intervention from another if you’re doing multiple campaigns with the same underlying intervention.
Target_Disease_State – Optional string parameter to specify the disease state to target with this intervention. Default to None which means Everyone. Possible values are: “Everyone”, “HIV_Positive”, “HIV_Negative”, “Tested_Positive”, “Tested_Negative”, “Not_Tested_Or_Tested_Negative”.

Returns:

Schema-based smart dictionary representing a new ScheduledCampaignEvent intervention ready to be added to a campaign.

Return type:

ReadOnlyDict

emodpy_hiv.interventions.reftracker.new_intervention_as_file(camp, actual_intervention, start_day=1, filename=None)[source]¶

emodpy_hiv.interventions.reftrackercoord module¶

emodpy_hiv.interventions.reftrackercoord.DistributeIVByRefTrackCoord(camp, Start_Year, Intervention_Config, Time_Value_Map, Tracking_Config, Targeting_Config=None, End_Year=None, node_ids=None, Node_Property_Restrictions=None, Property_Restrictions=None, Property_Restrictions_Within_Node=None, Target_Age_Max=None, Target_Age_Min=None, Target_Demographic='Everyone', Target_Gender='All', Target_Residents_Only=None, Update_Period=365)[source]¶

Create and return a ReferenceTrackingEventCoordinatorTrackingConfig EventCoordinator.

Parameters:

camp – emod_api.campaign object with schema_path set.
Start_Year – When to start.
Intervention_Config – Valid intervention to be distributed together as necessary to track coverage targets. Can be single intervention or list (list is useful where you want a co-event). If list, actual intervention should be first.
Time_Value_Map – A pairing of time (in years) and the fraction of the targeted group to have the attribute specified by Tracking_Config at that time. E.g. {“1960”: 0.1, “1970”: 0.2, “1980”: 0.3}
Tracking_Config – Defines the attribute to be tracked within the targeted group; the intervention will be distributed to people without the attribute, if coverage is below the target level the time of polling.
Targeting_Config – Allows you to specify more detail on the targeted group that you want to have the given attribute.
End_Year – When to end.
node_ids – Nodes to target with this intervention, return from utils.do_nodes().
Node_Property_Restrictions – A list of NodeProperty key:value pairs. A node must have the value for the given key in order for its humans to be considered.
Property_Restrictions – Individual Properties a person must have to receive the intervention(s).
Property_Restrictions_Within_Node – A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention.
Target_Age_Max – Maximum age (in years).
Target_Age_Min – Minimum age (in years).
Target_Demographic – Everyone, ExplicitAgeRanges, ExplicitAgeRangesAndGender, etc.
Target_Gender – All, Male, or Female.
Target_Residents_Only – Distribute intervention only to individuals that began the simulation in the node.
Update_Period – This duration between distributions is used to calculate the number of timesteps between distributions (= lower_bound ( Update_Period / dt )). Values < 2*dt result in one distribution per time step, to get one distribution every two timesteps set 3*dt > Update_Period > 2*dt.

Returns:

ReferenceTrackingEventCoordinatorTrackingConfig EventCoordinator ready to be added to a campaign.

Return type:

ReadOnlyDict

emodpy_hiv.interventions.setsexualdebut module¶

emodpy_hiv.interventions.setsexualdebut.track_sexual_debut_intervention(camp, YearSexualDebutRatios, Start_Year=1960.5, End_Year=2050, node_ids=None, Target_Age_Max=125, Target_Age_Min=0, Target_Demographic='Everyone', Target_Gender='All', Update_Period=30.416667, Distributed_Event_Trigger='Setting_Age_Sexual_Debut', Setting_Type='CURRENT_AGE', Age_Years=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Return a campaign event with an intervention that sets target values for sexual debuts for different points in time.

Parameters:

camp – emod_api.campaign object with schema_path set.
YearSexualDebutRatios – A map that maps time to values e.g. {“1960”: 0.1, “1970”: 0.2, “1980”: 0.3}
Start_Year – When to start.
End_Year – When to end.
node_ids – Nodes to target with this intervention, return from utils.do_nodes().
Target_Age_Max – Maximum age (in years).
Target_Age_Min – Minimum age (in years).
Target_Demographic – Everyone, ExplicitAgeRanges, etc.
Target_Gender – All, Male, or Female.
Update_Period – Number representing how frequently the distributions are done.
Distributed_Event_Trigger – Event that is broadcasted when the intervention is distributed to the individual.
Setting_Type – “CURRENT_AGE” lets individuals debut at their current age, “USER_SPECIFIED” uses Age_Years to set the age of sexual debut.
Age_Years – Age of sexual debut.

Returns:

Schema-based smart dictionary representing a new ReferenceTrackingEventCoordinatorTrackingConfig intervention ready to be added to a campaign.

Return type:

ReadOnlyDict

emodpy_hiv.interventions.setsexualdebut.new_intervention_event(camp, Event_Start_Day=1, Coverage=1.0, Target_Age_Max=None, Target_Age_Min=None, Target_Gender='All', Target_Demographic='Everyone', node_ids=None, Setting_Type=None, Age_Years=None, Distributed_Event_Trigger=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

SetSexualDebutAge campaign event to set the age of sexual debut. :param camp: emod_api.campaign object with schema_path set.camp (): :param Event_Start_Day: When to start. :param Coverage: Coverage of the intervention. :param Target_Age_Max: Maximum age (in years). :param Target_Age_Min: Minimum age (in years). :param Target_Gender: All, Male, or Female. :param Target_Demographic: Everyone, ExplicitAgeRanges, etc. :param node_ids: Nodes to target with this intervention, return from utils.do_nodes(). :param Setting_Type: “USER_SPECIFIED” or “CURRENT_AGE”. “USER_SPECIFIED” needs Age_Years to be set. :param Age_Years: Age at what on individuals will debut. :param Distributed_Event_Trigger: Event that is distributed when the intervention is applied. :param intervention_name: The name of the intervention. :type intervention_name: str :param disqualifying_properties: A list of IndividualProperty key:value pairs that cause an intervention to be aborted :type disqualifying_properties: list of str :param new_property_value: An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. :type new_property_value: str

Returns:: Schema-based smart dictionary representing a new SetSexualDebutAge event that can be added to a campaign.
Return type:: ReadOnlyDict

emodpy_hiv.interventions.setsexualdebut.new_intervention_as_file(camp, start_day, filename='SexualDebut.json')[source]¶

Adds the SetSexualDebutAge event to the emod_api.campaign object and saves the campaign to a file. :param camp: emod_api.campaign object :param start_day: start day of the event :param filename: output file name

Returns:: name of the file
Return type:: filename

emodpy_hiv.interventions.sigmoiddiag module¶

emodpy_hiv.interventions.sigmoiddiag.new_diagnostic(camp, Positive_Event, Negative_Event, ramp_min, ramp_max, ramp_midyear, ramp_rate, female_multiplier: float = 1.0, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Wrapper function to create and return a HIVSigmoidByYearAndSexDiagnostic intervention.

Parameters:: camp – emod_api.campaign object with schema_path set.
Returns:: Schema-based smart dictionary representing a new
Return type:: ReadOnlyDict

emodpy_hiv.interventions.sigmoiddiag.new_intervention_event(camp, pos_event, neg_event, ramp_min=0, ramp_max=1, ramp_midyear=2000, ramp_rate=1, start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: Diagnostic as scheduled event.

emodpy_hiv.interventions.sigmoiddiag.new_intervention_as_file(camp, start_day, filename=None)[source]¶

emodpy_hiv.interventions.stipostdebut module¶

emodpy_hiv.interventions.stipostdebut.new_diagnostic(camp, Positive_Event, Negative_Event, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Wrapper function to create and return a STIIsPostDebut intervention.

Parameters:: camp – emod_api.campaign object with schema_path set.
Returns:: Schema-based smart dictionary representing a new
Return type:: ReadOnlyDict

emodpy_hiv.interventions.stipostdebut.new_intervention_event(camp, pos_event, neg_event, start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: Diagnostic as scheduled event.

emodpy_hiv.interventions.stipostdebut.new_intervention_as_file(camp, start_day, filename=None)[source]¶

emodpy_hiv.interventions.utils module¶

emodpy_hiv.interventions.utils.set_tvmap_lists_from_map(tvmap, param)[source]¶

emodpy_hiv.interventions.utils.declutter(event)[source]¶: These are mostly temporary hacks that clean up the output json; should go away with subsequent cherry-picks of schema enhancements from other branches.

emodpy_hiv.interventions.utils.broadcast_event_immediate(camp, event_trigger: str = 'Births')[source]¶

emodpy_hiv.interventions.utils.broadcast_event_delayed(camp, event_trigger, delay=None)[source]¶

emodpy_hiv.interventions.utils.set_intervention_properties(iv, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Set properties of an intervention.

Parameters:

iv – an intervention object.
intervention_name (str) – The optional name used to refer to this intervention as a means to differentiate it from others that use the same class. The default name is the name of the class, but providing a unique name allows for distinguishing different configurations. For example, if you were distributing two vaccines where one had a higher efficacy than the other, you could use this parameter to call one ‘HighEfficacyVaccine’ and the other ‘LowEfficacyVaccine’. Doing this would allow you to collect data in reports on each version.
disqualifying_properties (List[str]) – A list of IndividualProperty key:value pairs that cause an intervention to be aborted. Right before an intervention is updated, it will check to see if the individual has one of the property values defined in this list. If it does, the intervention will not update and immediately expire.
new_property_value (str) – An optional IndividualProperty key:value pair that will be assigned when the intervention is first updated. After the individual gets the intervention and goes to update/apply it for the first time, the intervention first checks to see if the individual has any disqualifying properties. If they do not, then this property value will be assigned.

Returns:

None, but the intervention object is modified in place.

emodpy_hiv.interventions.yearandsexdiag module¶

emodpy_hiv.interventions.yearandsexdiag.new_diagnostic(camp, Positive_Event, Negative_Event, TVMap, interpolation_order: int | None = None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶

Wrapper function to create and return a HIVPiecewiseByYearAndSexDiagnostic intervention.

Parameters:: camp – emod_api.campaign object with schema_path set.
Returns:: Schema-based smart dictionary representing a new
Return type:: ReadOnlyDict

emodpy_hiv.interventions.yearandsexdiag.new_intervention_event(camp, pos_event, neg_event, tvmap, start_day=1, coverage=1.0, node_ids=None, intervention_name: str | None = None, disqualifying_properties: List[str] | None = None, new_property_value: str | None = None)[source]¶: Diagnostic as scheduled event.

emodpy_hiv.interventions.yearandsexdiag.new_intervention_as_file(camp, start_day, tvmap, filename=None)[source]¶

Submodules¶

emodpy_hiv.download module¶

emodpy_hiv.download.download(experiment_id, local_output_path='', files_to_get=None)[source]¶: Download HIV output file(s) to local disk. Just gets ReportHIVByAgeAndGender.csv. Intended to be used command line: python -m emopyhiv.download <COMPS Experiment ID> <Optional Output Path> <Files To Get> Note that target files need to include “output/” if that’s where they are.

emodpy_hiv.utils module¶

emodpy_hiv.utils.non_schema_checks(config)[source]¶: Do additional voluntary checks for config consistency. There’s no real fixed list for what should be here.