fpsim.scenarios module¶
Class to define and run scenarios
- fpsim.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 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
- 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 years (float/list): the year(s) at which to apply the modifications 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: increase injectables initiation and reduce exposure factor s7 = fp.make_scen( dict(method='Injectables', init_factor=2), dict(par='exposure_factor', years=2010, vals=0.5) ) # Scenarios can be combined s8 = s1 + s2
- class fpsim.scenarios.Scenario(spec=None, *args, label=None, year=None, matrix=None, ages=None, eff=None, probs=None, source=None, dest=None, factor=None, value=None, method=None, init_factor=None, discont_factor=None, init_value=None, discont_value=None, par=None, years=None, vals=None, interventions=None)¶
Bases:
sciris.sc_utils.prettyobj
,sciris.sc_settings.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 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
- 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 years (float/list): the year(s) at which to apply the modifications 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: increase injectables initiation and reduce exposure factor s7 = fp.make_scen( dict(method='Injectables', init_factor=2), 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
- class fpsim.scenarios.Scenarios(pars=None, repeats=None, scens=None, **kwargs)¶
Bases:
sciris.sc_utils.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
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(*args, **kwargs)¶
Actually run a list of sims
- check_run()¶
Give a meaningful error message if the scenarios haven’t been run
- plot_sims(**kwargs)¶
Plot each sim as a separate line across all senarios
- plot_scens(**kwargs)¶
Plot the scenarios with bands
- plot_cpr(**kwargs)¶
Plot the CPR with bands
- analyze_sims(start=None, end=None)¶
Take a list of sims that have different labels and count the births in each