Reporting

G-Cubed reporting turns baseline and experiment projections into complete CSV data files and focused HTML chart reports. A normal run writes both formats so the numbers can be analysed independently of the charts used to present them.

How a report is produced

Model projections
      ↓
Optional derived-variable calculations
      ↓
Complete level and deviation dataframes
      ├── CSV data files
      └── Chartpack selection + HTML template ──→ HTML charts

The maintained baseline or experiment run script passes its ordered projection objects to the reporting system. Reporting then:

validates and calculates any configured derived variables;
appends their rows to the ordinary model projections;
writes the complete projection or deviation dataframe as CSV;
uses the chartpack to select and organise series; and
renders the selected data with the report template as HTML charts and tables.

For an experiment with several simulation layers, reporting produces level projections for every layer. For each non-baseline layer it also produces deviations from the baseline and, after the first layer, deviations from the immediately preceding layer. These show the cumulative and incremental effects of an experiment respectively.

Report outputs

Results are normally written beneath:

results/<VERSION>/<BUILD>/<simulation>/
├── projections_data/
│   ├── <layer> <projection name>.csv
│   ├── <layer>-0 <projection> - <baseline>.csv
│   └── <layer>-<previous layer> <projection> - <previous>.csv
└── html_reports/
    ├── <layer> <projection name>.html
    ├── <layer>-0 <projection> deviations from <baseline>.html
    └── <layer>-<previous layer> <projection> deviations from <previous>.html

The exact set of files depends on the number of projections. A baseline has a level report only. An experiment adds baseline and incremental deviation reports where those comparisons exist.

CSV data files

The CSV files contain the complete reporting dataframe, not just the series in the chartpack. Each row is a model or derived variable. Metadata columns identify the prefix, description, units, vector, region and set members; four-digit columns contain the projection values by year. This makes the CSVs suitable for spreadsheets, statistical software and custom visualisations.

HTML charts

The chartpack selects rows from the reporting dataframe and groups them into charts. It also controls headings, labels, line styles, years and axis bounds. The report template controls the HTML presentation. A chartpack changes what is shown; it does not change the model projections.

See Charts for chartpack examples and links to the complete chartpack YAML recipes.

Add calculated reporting series

Derived variables calculate reporting series that are not produced directly by the model equations. The guide explains the subsystem, shows how to select existing definitions and provides a complete recipe for defining a new one.

For a direct catalogue, see Available derived variables. It lists every definition currently registered in the G-Cubed package, its generated row shape, calculation and required input prefixes.

Derived variables are optional. Without a derivations configuration, reporting retains the ordinary model-variable behaviour.