Experiment design

A G-Cubed experiment compares projections produced with one or more simulation layers with the baseline projections. A simulation layer is a CSV file of adjustments to model variables. A design YAML file names those layers, gives their event years and fixes their application order.

Related YAML documentation: design YAML, simulation layers, layer order and event years, generated layers and shock projections.

The two parts of a simulation layer

Keep these responsibilities distinct:

1. Setup YAML can specify how shocks project through time and generate the simulation-layer CSV.
2. Design YAML names and orders the layer; it does not contain shock values.

The layer CSV has a name column followed by year columns. Each number is an additive change in database units, whether the model variable is logged or unlogged. For example, +1 to a percentage variable at 5 gives 6; +10 to an index at 120 gives 130. The runtime handles the coordinate transformation; do not put log ratios into the CSV. A shortened example has this tabular form:

name	2023	2024	2025	2026	2027
INFX(USA)	0	0	0	1	1

Only exogenous variables, and state variables where the experiment explicitly supports them, may be adjusted. See layer filenames and CSV data for filename, layout, unit-conversion and migration rules.

For example, setup can generate a permanent inflation-target adjustment:

layers:
  - id: inflation_target
    name: Inflation-target adjustment
    data_file_name: inflation_target.csv
    event_year: 2026
    description: Raise the USA inflation target
    shocks:
      - variable_prefix: INFX
        selectors:
          - dimension: regions
            members: [USA]
        value_path:
          type: permanent_constant
          value: 1.0
          units: percentage points

Setup then writes a design containing the generated layer:

schema_version: 1
layers:
  - name: Inflation-target adjustment
    data_file: inflation_target.csv
    event_year: 2026
    description: Raise the USA inflation target

Event years and ordering

The event year is when information in a layer becomes known. Event years must stay the same or increase down the design. Layers with the same event year are applied in the sequence shown.

schema_version: 1
layers:
  - name: Tariff announcement
    data_file: tariffs.csv
    event_year: 2026
  - name: Retaliation
    data_file: retaliation.csv
    event_year: 2026
  - name: Later policy response
    data_file: policy_response.csv
    event_year: 2027

Standard and custom layers

Use setup-generated layers for the six supported shock projections. Use a maintained layer when a run script, optimisation or external fixed-point calculation owns the values.

• Permanent, temporary and explicit shock projections
• Combining shock projections
• Maintained simulation layers

Continue with running experiments.

Explain the experiment

Keep a README.md in the experiment folder to explain its purpose, economic assumptions and instructions. A separate documentation.md can provide the text inserted into generated HTML reports. These maintained files are not generated by setup and should cite the sources used for the experiment’s assumptions.