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.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():
    """
    Build a campaign input file for the DTK using emod_api.

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:

  1. Import the art module for creating the ART intervention.

  2. Create the ART intervention the way you want it.

  3. import and emod_api.interventions.common module for distribution interventions.

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