atomica.scenarios

Define classes for handling scenarios

This module implements the classes used to represent the four main types of scenarios in Atomica:

  • Parameter scenarios
  • Budget scenarios
  • Capacity scenarios
  • Coverage scenarios

There are broadly two kinds of scenario

  • Parameter scenarios which involve modifying a ParameterSet instance
  • Program scenarios (budget, capacity, coverage) which involve modifying a ProgramInstructions instance

Classes

BudgetScenario([name, active, parsetname, …])
CombinedScenario([name, active, parsetname, …]) Define combined (budget+program) scenario
CoverageScenario([name, active, parsetname, …])
ParameterScenario([name, scenario_values, …]) Define and run parameter scenarios
Scenario(name[, active, parsetname, progsetname]) Base scenario class
class atomica.scenarios.BudgetScenario(name=None, active=True, parsetname=None, progsetname=None, alloc=None, start_year=2019)[source]
get_instructions(progset, project)[source]

Get scenario instructions

If the derived scenario class produces program instructions, return them here.

Parameters:progset (ProgramSet) – Input ProgramSet
Return type:ProgramInstructions
Returns:ProgramInstructions instance, or None if no instructions (in which case, programs will not be used)
class atomica.scenarios.CombinedScenario(name=None, active=True, parsetname=None, progsetname=None, scenario_values=None, instructions=None, interpolation='linear')[source]

Define combined (budget+program) scenario

This object stores both a set of scenario values and a set of program instructions. This allows it to simultaneously apply parameter, budget, and coverage overwrites.

As usual, parameter values from programs take precedence over parameter values from parsets, and within programs, coverage takes precedence ovetoxr budgets.

Parameters:
  • name (Optional[str]) – The name of the scenario. This will also be used to name the result
  • active (bool) – If running via Project.run_scenarios this flags whether to run the scenario
  • parsetname (Optional[str]) – If running via Project.run_scenarios this identifies which parset to use from the project
  • progsetname (Optional[str]) – If running via Project.run_scenarios this identifies which progset to use. If set to None then programs will not be used
  • scenario_values (Optional[dict]) – Parameter value overwrites, used as input to ParameterScenario
  • instructions (Optional[ProgramInstructions]) – A :class`ProgramInstructions` instance containing required program overwrites (budget, capacity, coverage)
get_instructions(progset, project)[source]

Get scenario instructions

If the derived scenario class produces program instructions, return them here.

Parameters:progset (ProgramSet) – Input ProgramSet
Return type:ProgramInstructions
Returns:ProgramInstructions instance, or None if no instructions (in which case, programs will not be used)
get_parset(parset, project)[source]

Get scenario parset

If the derived scenario class modifies the parset, return the modified version

Parameters:parset – Input ParameterSet
Return type:ParameterSet
Returns:Modified parset for use in the simulation
instructions = None

Program instructions for budget scenario (should already contain required overwrites)

interpolation = None

Interpolation method to use for parameter overwrite

scenario_values = None

Parameter scenario values (see ParameterScenario)

class atomica.scenarios.CoverageScenario(name=None, active=True, parsetname=None, progsetname=None, coverage=None, start_year=2019)[source]
get_instructions(progset, project)[source]

Get scenario instructions

If the derived scenario class produces program instructions, return them here.

Parameters:progset (ProgramSet) – Input ProgramSet
Return type:ProgramInstructions
Returns:ProgramInstructions instance, or None if no instructions (in which case, programs will not be used)
class atomica.scenarios.ParameterScenario(name=None, scenario_values=None, active=True, parsetname=None, interpolation='linear')[source]

Define and run parameter scenarios

This object stores overwrites to parameter values that are used to modify a ParameterSet instance before running a simulation.

Example usage:

>>> scvalues = dict()
>>> param = 'birth_transit'
>>> scvalues[param] = dict()
>>> scvalues[param]['Pop1'] = dict()
>>> scvalues[param]['Pop1']['y'] = [3e6, 1e4, 1e4, 2e6]
>>> scvalues[param]['Pop1']['t'] = [2003.,2004.,2014.,2015.]
>>> pscenario = ParameterScenario(name="examplePS",scenario_values=scvalues)
Parameters:
  • name (Optional[str]) – The name of the scenario. This will also be used to name the result
  • scenario_values (Optional[dict]) –

    A dict of overwrites to parameter values. The structure is {parameter_label: {pop_label: dict o} where the overwrite o contains keys

    • t : np.array or list with year values
    • y : np.array or list with corresponding parameter values
  • active (bool) – If running via Project.run_scenarios this flags whether to run the scenario
  • parsetname (Optional[str]) – If running via Project.run_scenarios this identifies which parset to use from the project
  • interpolation (str) – The specified interpolation method will be used to interpolate scenario values onto simulation times. Common options are ‘linear’ (smoothly change) and ‘previous’ (stepped)
add(par_name, pop_name, t, y)[source]

Add overwrite to scenario

This method adds a TimeSeries with parameter overwrite values to the ParameterSet

Example usage:

>>> pscenario = ParameterScenario(name="examplePS")
>>> pscenario.add('rec_rate','Pop1',[2004.,2014],[3e6, 1e4])

This can provide a more readable way to define a parameter scenario, without having to assemble a dict of the overwrites in advance.

Parameters:
  • par_name (str) – Name of the parameter to overwrite
  • pop_name (str) – Population to overwrite values for
  • t – scalar, list, or array of times
  • y – scalar, list, or array of overwrite values
  • end_overwrite – If True, after the final overwrite, the parameter will revert to its baseline value
Return type:

None

get_parset(parset, project)[source]

Return modified parset

This method takes in a ParameterSet and modifies it by applying the overwrites present in the scenario. This can thus be used to return the ParameterSet for use in other simulations that are manually run, or to do things like perform a budget scenario simulation in conjunction with a parameter scenario.

The returned ParameterSet will have been pre-interpolated onto the simulation times.

Parameters:
  • parset (ParameterSet) – A ParameterSet instance
  • project – A Project instance (required for simulation times and to identify function parameters)
Return type:

ParameterSet

Returns:

A new ParameterSet object

interpolation = None

Stores the name of a supported interpolation method

scenario_values = None

Store dictionary containing the overwrite values

class atomica.scenarios.Scenario(name, active=True, parsetname=None, progsetname=None)[source]

Base scenario class

All Scenario objects share this type. It is a NamedItem that also has an active property which represents whether the scenario should be run as part of project.Project.run_scenarios()

The optional variables parsetname and progsetname reference the name of parsets and progsets to use via Scenario.run(). These should match the names of objects in the project passed into Scenario.run(). However, Scenario.run() can also take in a parset and/or progset directly, allowing the scenario to be used with other parsets and progsets on the fly. If parsetname and progsetname are not set in the Scenario then they must be passed into Scenario.run().

Parameters:
  • name (str) – The name of the scenario - also sets the result name via Scenario.run()
  • parsetname (Optional[str]) – If running via Project.run_scenarios this identifies which parset to use from the project
  • progsetname (Optional[str]) – If running via Project.run_scenarios this identifies which progset to use. If set to None then programs will not be used
  • active (bool) – If running via Project.run_scenarios this flags whether to run the scenario
active = None

Flag whether the scenario should be run via Project.run_scenarios

get_instructions(progset, project)[source]

Get scenario instructions

If the derived scenario class produces program instructions, return them here.

Parameters:progset (ProgramSet) – Input ProgramSet
Return type:ProgramInstructions
Returns:ProgramInstructions instance, or None if no instructions (in which case, programs will not be used)
get_parset(parset, project)[source]

Get scenario parset

If the derived scenario class modifies the parset, return the modified version

Parameters:parset – Input ParameterSet
Return type:ParameterSet
Returns:Modified parset for use in the simulation
get_progset(progset, project)[source]

Get scenario progset

If the derived scenario class modifies the progset, return the modified version

Parameters:progset (ProgramSet) – Input ProgramSet
Return type:ProgramSet
Returns:Modified progset for use in the simulation
parsetname = None

Specify parset name when run via Project.run_scenarios

progsetname = None

Specify progset name when run via Project.run_scenarios

run(project, parset=None, progset=None, store_results=True)[source]

Run scenario

Parameters:
  • project – A Project instance
  • parset (Optional[ParameterSet]) – Optionally a ParameterSet instance, otherwise will use self.parsetname
  • progset (Optional[ProgramSet]) – Optionally a ProgramSet instance, otherwise will use self.progsetname
  • store_results (bool) – If True, the results will be copied into the project
Return type:

Result

Returns:

A Result object