Experiment design

Table of contents

• The simulations folder and its contents
  • The experiment design file
    • The event year
    • The simulation layer data
  • The simulation layer file
• Experiment design
• The experiment baseline

The simulations folder and its contents

A G-Cubed model comes with a number of example experiments. Each experiment is in a folder under the model’s simulations folder. Explore (and run) these example experiments to become familiar with the files that define an experiment.

The simulations folder must be a child folder of the folder that contains the model configuration file.

<VERSION>
  ├── <BUILD>
    ├── <MODEL_CONFIGURATION>.csv
    ├── data
    │   │   ├── ...
    ├── diagnostics
    │   │   ├── ...
    ├── python
    │   │   ├── ...
    ├── simulations
    │   ├── <EXPERIMENT1>
    │   │   ├── <EXPERIMENT1_DESIGN>.csv
    │   │   ├── <LAYER1_DATA>.csv
    │   │   ├── ...
    │   ├── <EXPERIMENT2>
    │   │   ├── <EXPERIMENT2_DESIGN>.csv
    │   │   ├── <LAYER1_DATA>.csv
    │   │   ├── <LAYER2_DATA>.csv
    │   │   ├── ...
    │   ├── ...
    ├── sym
    │   │   ├── ...

The simulations folder contains one experiment folder for each simulation experiment being done using the model. The experiment folder names are user-determined.

The experiment design file

Each experiment folder contains at least one CSV experiment design file that configures the experiment, documenting the layers of adjustments to variables that are to be applied in specific years through the projections.

The experiment design file is comma delimited and the values in the file must not contain commas.

The first row of the design file contains column labels. They are, in order:

1. name
2. data
3. event_year
4. description

Each of the following rows in the design file sets out the definition of a single simulation layer. When running simulations, the details of the simulation layer are loaded into a simulation layer definition.

That simulation layer definition is used to create the simulation projections associated with the layer. The simulation projections are generated by the simulation layer.

The name and the description of a simulation layer are used for experiment documentation purposes. The effect of the simulation layer is determined by the event_year and the data values.

The event year

Each simulation has an event year. That is the year that the agents in the model become aware of the changes to their circumstances associated with the simulation layer. For example, if agents become aware, in 2025, that the new target inflation rate is 5% instead of 2.5% then the simulation layer that describes the changes to the new target inflation rate would have an event year of 2025. This is the case, even if the change in the target inflation rate only takes effect in a year after 2025.

The event year for each simulation layer must be contained in the event_year column of the experiment design file.

The event year must be after the first projection year, specified in the model configuration.

The simulation layer data

Each simulation layer involves applying changes to the circumstances of the agents in the model. These take the form of increments that are applied to exogenous variables in the event year or in any year thereafter.

The increments to exogenous variables set out in a single CSV file. The name of that CSV file is the value in the data column for the simulation layer in the experiment design file. Note that only the file name is required. The folder location of the file is assumed to be the same as the folder location of the experiment design file.

The increments to exogenous variables are in the same units as the data in the model database file.

The simulation layer file

There must be exactly one CSV file for each simulation layer.

The data file is a comma-delimited CSV file. The first column contains the full variable names for the exogenous or state variables that change.

The following columns are for the changes to the variables in each year from the simulation layer’s event year through to the last projection year.

The simulation layer file has column headings in the first row:

1. name for the full name of the variable
2. 2025 if the event year is 2025
3. 2026
4. …
5. 2100 if the last projection year is 2100.

The simulation layer file can contain just the column headings, in which case, the simulation layer should not alter projections at all because it implies no changes to the circumstances of the agents in the model. More typical data files involve changes to several exogenous variables.

After the column headings row, there is one row for each variable. That row contains the shocks to that variable in each of the simulation layer’s years. The rows for the variables can be in any order.

Note that the simulation layer data file must not include changes to variables that are not exogenous variables.

Experiment design

Experiments can involve applying more than one simulation layer as an overlay to the baseline projections. Each simulation layer has its own event year, identifying when the agents in the model become aware of the shocks in that simulation layer.

The simulation layers are run in the order they are specified in the experiment design file. The first row of the design file contains the design file column headings. The simulation layer in row 2 of the design file is applied first. If there is a simulation in row 3, then it is applied next, in a cumulative fashion, as an additional set of shocks.

For this reason, simulation layers must be specified in event-year order. If simulation layer A has event year 2025, and simulation B has event year 2030, then simulation layer A must be in a row above simulation layer B in the experiment design file. In that way, the information in simulation layer A becomes available to agents in 2025 and they adapt their behaviour to that information. Then, in 2030, the agents further adapt their behaviour to the information in simulation layer B.

It is possible to include multiple simulation layers with the same event year. The application of multiple simulation layers with the same event year is done in the row order of the simulation layers in the experiment design file.

The experiment baseline

Most experiments involve applying a set of shocks to baseline projections to assess the changes that are induced by those shocks. Careful consideration should be given to the projections of the exogenous variables that underpin the baseline projections. The various ways in which those exogenous projections can be set up are documented in detail.