Welcome to emodpy-hiv¶

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 and emodpy packages.

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.

Installation¶

You can install emodpy-hiv using the instructions in the GitHub repository README.

emodpy_hiv¶

emodpy_hiv package¶

Subpackages¶

emodpy_hiv.demographics package¶

Submodules¶

emodpy_hiv.demographics.DemographicsTemplates module¶

emodpy_hiv.demographics.DemographicsTemplates.set_society_configs(config)¶

emodpy_hiv.demographics.DemographicsTemplates.AddDefaultSociety(demog)¶: 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)¶

Bases: emod_api.demographics.Demographics.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)¶: 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=[1970, 1980], which_point='mid', predict_horizon=2050, csv_out=False, n=0, results_scale_factor=0.0027397260273972603)¶: Calculate and set the expected natural mortality by age, sex, and year from data, predicting what it would have been without HIV.

apply_assortivity(category, rowmale_colfemale_matrix)¶

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

Parameters

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

Returns

N/A.

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

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')¶

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')¶

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)¶: 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)¶: ART intervention as complete (scheduled) event.

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

emodpy_hiv.interventions.artdropout module¶

emodpy_hiv.interventions.artdropout.new_intervention(camp)¶: 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)¶: ARTDropout intervention as complete (scheduled) event.

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

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)¶

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)¶: Diagnostic as scheduled event.

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

emodpy_hiv.interventions.artstagingbycd4diag module¶

emodpy_hiv.interventions.artstagingbycd4diag.new_diagnostic(camp, Positive_Event, Negative_Event, Threshold_TVMap, IP_TVMap, IAT_TVMap)¶

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)¶: Diagnostic as scheduled event.

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

emodpy_hiv.interventions.cascade_helpers module¶

emodpy_hiv.interventions.cascade_helpers.reset(camp)¶

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)¶: Seed an infection by time and %age of population infected.

emodpy_hiv.interventions.cascade_helpers.triggered_event_common(camp, in_trigger, out_iv, event_name='')¶: Parameterized utility function used by rest of functions in this submodule that listen for a trigger and distribute an intervention (or list thereof) as a result.

emodpy_hiv.interventions.cascade_helpers.add_choice(camp, sympto_signal='HIVSymptomatic', get_tested_signal='GetTested')¶: Listen for HIVSymptomatic trigger. Then toss a coin (Random Choice), heads get tested, tails maybe it’s just a cold.

emodpy_hiv.interventions.cascade_helpers.add_test(camp, get_tested_signal='GetTested')¶: Listen for GetTested signal. Then get HIV RapidDiagnostic test after a delay of 30 days.

emodpy_hiv.interventions.cascade_helpers.trigger_art_from_pos_test(camp, input_signal='HIVPositiveTest', output_signal='StartTreatment', lag_time=30)¶: 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')¶: 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')¶: 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='')¶

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)¶: Delay as scheduled event.

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

emodpy_hiv.interventions.drawblood module¶

emodpy_hiv.interventions.drawblood.new_diagnostic(camp, Positive_Event, Base_Sensitivity=1, Base_Specificity=1, Days_To_Diagnosis=0, Treatment_Fraction=1)¶

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)¶: Diagnostic as scheduled event.

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

emodpy_hiv.interventions.malecirc module¶

emodpy_hiv.interventions.malecirc.new_intervention(camp)¶: 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)¶: VMMC intervention as complete (scheduled) event.

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

emodpy_hiv.interventions.modcoinf module¶

emodpy_hiv.interventions.modcoinf.new_intervention(camp)¶: 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)¶: ModifySTICoInfection intervention as complete (scheduled) event.

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

emodpy_hiv.interventions.outbreak module¶

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

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.pmtct module¶

emodpy_hiv.interventions.pmtct.new_intervention(camp, efficacy=1.0)¶: 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)¶: PMTCT intervention as complete (scheduled) event.

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

emodpy_hiv.interventions.prep module¶

emodpy_hiv.interventions.prep.new_intervention(camp)¶: PrEP intervention wrapper. Just the intervention. No configuration yet.

emodpy_hiv.interventions.prep.new_intervention_event(camp, start_day=1, coverage=1.0, node_ids=None)¶: PrEP intervention as complete (scheduled) event.

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

emodpy_hiv.interventions.random module¶

emodpy_hiv.interventions.random.new_diagnostic(camp, choices)¶

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

Returns

Schema-based smart dictionary representing a new

Return type

ReadOnlyDict

emodpy_hiv.interventions.random.new_intervention_event(camp, choices, start_day=1, coverage=1.0, node_ids=None)¶: Diagnostic as scheduled event.

emodpy_hiv.interventions.random.new_intervention_as_file(camp, start_day, choices, filename=None)¶

emodpy_hiv.interventions.rapiddiag module¶

emodpy_hiv.interventions.rapiddiag.new_diagnostic(camp, Positive_Event, Negative_Event)¶

Wrapper function to create and return a HIVRapidHIVDiagnostic 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.rapiddiag.new_intervention_event(camp, pos_event, neg_event, start_day=1, coverage=1.0, node_ids=None)¶: Diagnostic as scheduled event.

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

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_Demographic='Everyone', Target_Age_Min=0, Target_Age_Max=45625, Target_Gender='All')¶

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.
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.

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)¶

emodpy_hiv.interventions.sigmoiddiag module¶

emodpy_hiv.interventions.sigmoiddiag.new_diagnostic(camp, Positive_Event, Negative_Event, ramp_min, ramp_max, ramp_midyear, ramp_rate)¶

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)¶: Diagnostic as scheduled event.

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

emodpy_hiv.interventions.stipostdebut module¶

emodpy_hiv.interventions.stipostdebut.new_diagnostic(camp, Positive_Event, Negative_Event, Base_Sensitivity=1, Base_Specificity=1, Days_To_Diagnosis=0, Treatment_Fraction=1)¶

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)¶: Diagnostic as scheduled event.

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

emodpy_hiv.interventions.utils module¶

emodpy_hiv.interventions.utils.set_tvmap_lists_from_map(tvmap, param)¶

emodpy_hiv.interventions.utils.declutter(event)¶: 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.yearandsexdiag module¶

emodpy_hiv.interventions.yearandsexdiag.new_diagnostic(camp, Positive_Event, Negative_Event, TVMap)¶

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)¶: Diagnostic as scheduled event.

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