fpsim.scenarios module

Class to define and run scenarios

make_scen(*args, **kwargs)

Alias for fp.Scenario().

Store the specification for a single scenario (which may consist of multiple interventions).

This function is intended to be as flexible as possible; as a result, it may be somewhat confusing. There are five different ways to call it – method efficacy, method probability, method initiation/discontinuation, parameter, and custom intervention.

Args (shared):

spec (dict): a pre-made specification of a scenario; see keyword explanations below (optional) args (list): additional specifications (optional) label (str): the sim label to use for this scenario pars (dict): optionally supply additional sim parameters to use with this scenario (that take effect at the beginning of the sim, not at the point of intervention) year (float): the year at which to activate efficacy and probability scenarios matrix (str): which set of probabilities to modify for probability scenarios (e.g. annual or postpartum) ages (str/list): the age groups to modify the probabilities for

Args (efficacy):

year (float): as above eff (dict): a dictionary of method names and new efficacy values

Args (probablity):

year (float): as above matrix (str): as above ages (str): as above source (str): the method to switch from dest (str): the method to switch to factor (float): if supplied, multiply the [source, dest] probability by this amount value (float): if supplied, instead of factor, replace the [source, dest] probability by this value copy_from (str): if supplied, copy probabilities from a different method

Args (initiation/discontinuation):

year (float): as above matrix (str): as above ages (str): as above method (str): the method for initiation/discontinuation init_factor (float): as with “factor” above, for initiation (None → method) discont_factor (float): as with “factor” above, for discontinuation (method → None) init_value (float): as with “value” above, for initiation (None → method) discont_value (float): as with “value” above, for discontinuation (method → None)

Args (parameter):

par (str): the parameter to modify par_years (float/list): the year(s) at which to apply the modifications par_vals (float/list): the value(s) of the parameter for each year

Args (custom):

interventions (Intervention/list): any custom intervention(s) to be applied to the scenario

Congratulations on making it this far.

Examples:

# Basic efficacy scenario
s1 = fp.make_scen(eff={'Injectables':0.99}, year=2020)

# Double rate of injectables initiation
s2 = fp.make_scen(source='None', dest='Injectables', factor=2)

# Double rate of injectables initiation -- alternate approach
s3 = fp.make_scen(method='Injectables', init_factor=2)

# More complex example: change condoms to injectables transition probability for 18-25 postpartum women
s4 = fp.make_scen(source='Condoms', dest='Injectables', value=0.5, ages='18-25', matrix='pp1to6')

# Parameter scenario: halve exposure
s5 = fp.make_scen(par='exposure_factor', years=2010, vals=0.5)

# Custom scenario
def update_sim(sim): sim.updated = True
s6 = fp.make_scen(interventions=update_sim)

# Combining multiple scenarios: change probabilities and exposure factor
s7 = fp.make_scen(
    dict(method='Injectables', init_value=0.1, discont_value=0.02, create=True),
    dict(par='exposure_factor', years=2010, vals=0.5)
)

# Scenarios can be combined
s8 = s1 + s2

class Scenario(spec=None, label=None, pars=None, year=None, matrix=None, ages=None, eff=None, probs=None, source=None, dest=None, factor=None, value=None, copy_from=None, method=None, init_factor=None, discont_factor=None, init_value=None, discont_value=None, par=None, par_years=None, par_vals=None, interventions=None)

Bases: prettyobj, dictobj

Store the specification for a single scenario (which may consist of multiple interventions).

This function is intended to be as flexible as possible; as a result, it may be somewhat confusing. There are five different ways to call it – method efficacy, method probability, method initiation/discontinuation, parameter, and custom intervention.

Args (shared):

spec (dict): a pre-made specification of a scenario; see keyword explanations below (optional) args (list): additional specifications (optional) label (str): the sim label to use for this scenario pars (dict): optionally supply additional sim parameters to use with this scenario (that take effect at the beginning of the sim, not at the point of intervention) year (float): the year at which to activate efficacy and probability scenarios matrix (str): which set of probabilities to modify for probability scenarios (e.g. annual or postpartum) ages (str/list): the age groups to modify the probabilities for

Args (efficacy):

year (float): as above eff (dict): a dictionary of method names and new efficacy values

Args (probablity):

year (float): as above matrix (str): as above ages (str): as above source (str): the method to switch from dest (str): the method to switch to factor (float): if supplied, multiply the [source, dest] probability by this amount value (float): if supplied, instead of factor, replace the [source, dest] probability by this value copy_from (str): if supplied, copy probabilities from a different method

Args (initiation/discontinuation):

year (float): as above matrix (str): as above ages (str): as above method (str): the method for initiation/discontinuation init_factor (float): as with “factor” above, for initiation (None → method) discont_factor (float): as with “factor” above, for discontinuation (method → None) init_value (float): as with “value” above, for initiation (None → method) discont_value (float): as with “value” above, for discontinuation (method → None)

Args (parameter):

par (str): the parameter to modify par_years (float/list): the year(s) at which to apply the modifications par_vals (float/list): the value(s) of the parameter for each year

Args (custom):

interventions (Intervention/list): any custom intervention(s) to be applied to the scenario

Congratulations on making it this far.

Examples:

# Basic efficacy scenario
s1 = fp.make_scen(eff={'Injectables':0.99}, year=2020)

# Double rate of injectables initiation
s2 = fp.make_scen(source='None', dest='Injectables', factor=2)

# Double rate of injectables initiation -- alternate approach
s3 = fp.make_scen(method='Injectables', init_factor=2)

# More complex example: change condoms to injectables transition probability for 18-25 postpartum women
s4 = fp.make_scen(source='Condoms', dest='Injectables', value=0.5, ages='18-25', matrix='pp1to6')

# Parameter scenario: halve exposure
s5 = fp.make_scen(par='exposure_factor', years=2010, vals=0.5)

# Custom scenario
def update_sim(sim): sim.updated = True
s6 = fp.make_scen(interventions=update_sim)

# Combining multiple scenarios: change probabilities and exposure factor
s7 = fp.make_scen(
    dict(method='Injectables', init_value=0.1, discont_value=0.02, create=True),
    dict(par='exposure_factor', years=2010, vals=0.5)
)

# Scenarios can be combined
s8 = s1 + s2

update_label(label=None)

Ensure all specs have the correct label

run(run_args=None, **kwargs)

Shortcut for creating and running a Scenarios object based on the current scenario.

Parameters

• run_args (dict) – passed to scens.run()

• kwargs (dict) – passed to Scenarios()

class Scenarios(pars=None, repeats=None, scens=None, **kwargs)

Bases: prettyobj

Run different intervention scenarios.

A “scenario” can be thought of as a list of sims, all with the same parameters except for the random seed. Usually, scenarios differ from each other only in terms of the interventions run (to compare other differences between sims, it’s preferable to use a MultiSim object).

Parameters

• pars (dict) – parameters to pass to the sim

• repeats (int) – how many repeats of each scenario to run (default: 1)

• scens (list) – the list of scenarios to run; see also fp.make_scen() and Scenarios.add_scen()

• kwargs (dict) – optional additional parameters to pass to the sim

Example:

scen1 = fp.make_scen(label='Baseline')
scen2 = fp.make_scen(year=2002, eff={'Injectables':0.99}) # Basic efficacy scenario
scens = fp.Scenarios(location='test', repeats=2, scens=[scen1, scen2])
scens.run()

add_scen(scen=None, label=None)

Add a scenario or scenarios to the Scenarios object

make_sims(scenlabel, **kwargs)

Create a list of sims that are all identical except for the random seed

make_scens()

Convert a scenario specification into a list of sims

run(recompute=True, *args, **kwargs)

Actually run a list of sims

check_run()

Give a meaningful error message if the scenarios haven’t been run

plot(to_plot=None, plot_sims=True, **kwargs)

Plot the scenarios with bands – see sim.plot() for args

plot_sims(to_plot=None, plot_sims=True, **kwargs)

Plot each sim as a separate line across all senarios – see sim.plot() for args

analyze_sims(start=None, end=None)

Take a list of sims that have different labels and extrapolate statistics from each