Scenarios

This section has been written with the assumption that Automating the Execution of Models has already been read, and the reader is familiar with the term option, as described in Converting TO the Collins Economics Result Object (CERO) format and Converting FROM the Collins Economics Result Object (CERO) format, with respect to YAML files.

Scenarios are generally run by using a scenario definition file, and like all other configuration files used with ConCERO, this file must be of YAML format.

Scenario Definition Files

At the highest level (i.e. no indentation) in a scenario definition file can be either a single scenario definition object, or a list of scenario definition objects.

Scenario Definition Objects

A scenario definition object must have the options:

  • models: list[model objects] - the structure of model objects are described here - Model Objects.

And may have the options:

  • name: (str) - the name of the scenario. For example, 'A1' or 'ExistingTrends'.
  • input_conf: (str) - an input configuration file that defines all of the scenario inputs. See Converting TO the Collins Economics Result Object (CERO) format for more information.
  • output_conf: (str) - an output configuration file that defines outputs from the scenario. See Converting FROM the Collins Economics Result Object (CERO) format for more information.
  • run_no: (int) - An integer numbering the execution run of the scenario. By default is 1. This integer will appear in the filenames of any files output as intermediate steps.
  • export_mod_xlsx: (bool) - Exports the returned output from each of the models as an xlsx file, which allows the user to easily analyse whether results are sensible. The output file will have a name of the format <scenario_name>_<run_no>_<model["name"]>.xlsx. The default is True.
  • export_int_xlsx: (bool) - Exports the returned output from each of the intermediate steps in the scenario execution as an xlsx file, which allows the user to easily analyse whether results are sensible. Conceptually, the output is the CERO before the previous model execution, updated with the output of the previous model execution. The output file will have a name of the format <scenario_name>_<run_no>_step_<execution_step>.xlsx, where execution_step is the (1-indexed) number of model executions. The default is True.

Scenario Example

An example scenario definition file that demonstrates all options is:

name: A1
run_no: 1
input_conf: data/test_scen_inputs.yaml
export_mod_xlsx: False
export_int_xlsx: False
models:
  - name: example_model
    cmds: python dummy_model.py
    input_conf: data/test_model_input.yaml
    output_conf: data/test_model_output.yaml
    export_xlsx: False
output_conf: data/test_scen_outputs.yaml

In the first run (run_no: 1) of scenario A1, scenario inputs are imported into a scenario level CERO, as defined by data/test_scen_inputs.yaml. example_model is the first (and only) model to be run. data/test_model_input.yaml defines the data series of the CERO that are of interest to example_model and exports these data series into the input files for example_model. The single command python dummy_model.py, which defines the execution of example_model is then run from the command line in the current working directory. The relevant output data is defined by data/test_model_output.yaml - this output data is then converted into a CERO, which then updates the scenario-level CERO (overwriting any data series with the same identifier). Given that example_model is the last model to be run, the file data/test_scen_outputs.yaml defines the CERO data series of interest for export into files.

Scenario Technical Reference

class scenario.Scenario(sc_def: dict, *args, parent: dict = None, **kwargs)[source]
Parameters:
  • sc_def – A scenario definition object.
  • args – Passed to the superclass (dict) as positional arguments at initialisation.
  • kwargs – Passed to the superclass (dict) as keyword arguments at initialisation.
get_linked_scenarios()[source]
Return “List[‘ScenariosSet’]”:
 A list of linked ScenariosSet.
get_name(long_form: bool = True, raise_exception=False) → str[source]

Returns the name of the Scenario, which is dependent on the first linked ScenariosSet object. :param long_form: If True (default) return a long-form of the name. If False, return a short form. :return: The name of the Scenario.

is_valid(raise_exception=True) → bool[source]

Performs static checks on self to ensure it is a valid Scenario object.

static load_scenario(scen_def: str, parent=None)[source]
Parameters:scen_def – The file containing a single scenario definition, or a scenario definition dict .
Return ‘Scenario’:
 A single Scenario object.
static load_scenarios(scen_def: str, parent=None)[source]

Load one or more scenarios from a file.

Parameters:scen_def – The file containing one or more scenario definitions.
Return “Union[‘Scenario’,List[‘Scenario’]]”:
 Either a single Scenario , or a list of Scenario s.
run() → None[source]

Execute a scenario run.

run_checks(raise_exception=True)[source]

Performs runtime checks on self to ensure it is a valid Scenario object. Failure of runtime checks indicates that the scenario is not ready to run.

Parameters:raise_exception (bool) –
Returns: