G-Cubed chart types: sample and usage guide

Every name, prefix, region, value and policy layer in this guide is invented. Inspect your model’s charting_projections catalogue and replace all SYNTH… IDs. Do not assume guide variables exist in a G-Cubed model.

Download complete YAML Download complete CSV

The CSV is the complete reloadable wide projections source. Per-chart CSV exports from a report are long-form views for analysis; they are not replacements for this source file.

Chart chooser

Rendered examples

Use each Preview selector to compare exporter-rendered states offline. The YAML beneath a card is its authored initial state; import the complete YAML and CSV into a report to use the actual report controls, table and exports.

Illustrative activity paths

Synthetic regional activity paths use complete annual observations; real gaps remain gaps.

Illustrative preview SVG YAML Source CSV

When to use this chart

QuestionHow does one measure move through time across a few regions?

DataOne or more ordinary series with common units. Omit chart_type.

UnitsIndex (2025=100); lines compare paths, not additive parts.

Best default when timing and direction matter. Real gaps remain gaps.

Complete working YAML

- chartpack:
    format: gcubed-chartpack
    version: 1.4.0
    title: Illustrative activity paths
    sector_selection_dimensions:
    - sectors
    - layers
    defaults:
      start_year: 2025
      end_year: 2035
- chart:
    title: Illustrative activity paths
    caption: Synthetic regional activity paths use complete annual observations; real gaps remain gaps.
    x_axis:
      label: Year
    y_axis:
      label: Activity index (2025 = 100)
    series:
    - variable: SYNTHINDEX(USA)
      label: Illustrative North
    - variable: SYNTHINDEX(JPN)
      label: Illustrative East
    - variable: SYNTHINDEX(ROW)
      label: Illustrative Rest

Download YAML Download complete CSV

Activity change, 2025–2035

Teal marks positive change, rust negative change, and neutral zero; labels retain the authored units.

Illustrative preview SVG YAML Source CSV

When to use this chart

QuestionHow much did each series change between two years?

DataOne dataset, two explicit endpoint years, common units.

UnitsFinal minus initial index points inside the selected dataframe.

This example deliberately includes positive, negative and zero changes. color_by_sign gives them semantic colours.

Complete working YAML

- chartpack:
    format: gcubed-chartpack
    version: 1.4.0
    title: Activity change, 2025–2035
    sector_selection_dimensions:
    - sectors
    - layers
    defaults:
      start_year: 2025
      end_year: 2035
- chart:
    title: Activity change, 2025–2035
    chart_type: series-delta
    show_labels: true
    color_by_sign: true
    caption: Teal marks positive change, rust negative change, and neutral zero; labels retain the authored units.
    orientation: horizontal
    sort: value-descending
    x_axis:
      label: Change in activity index points
      min: -10
      max: 20
    y_axis:
      label: Region
    series:
    - variable: SYNTHINDEX(USA)
      label: Illustrative North
    - variable: SYNTHINDEX(JPN)
      label: Illustrative East
    - variable: SYNTHINDEX(ROW)
      label: Illustrative Rest

Download YAML Download complete CSV

Illustrative North sector output in 2030

A report card offers every eligible year and refreshes its title, table, and exports together.

Illustrative preview SVG YAML Source CSV

When to use this chart

QuestionHow do categories compare in one chosen year?

DataSeveral series, one year, common units; optional stable value sorting.

UnitsUS$ billion at 2025 prices in this synthetic example.

On a deviation CSV, bars are scenario deviations in the chosen year.

Complete working YAML

- chartpack:
    format: gcubed-chartpack
    version: 1.4.0
    title: Illustrative North sector output in 2030
    sector_selection_dimensions:
    - sectors
    - layers
    defaults:
      start_year: 2025
      end_year: 2035
- chart:
    title: Illustrative North sector output in 2030
    chart_type: series-value
    show_labels: true
    year: 2030
    caption: A report card offers every eligible year and refreshes its title, table, and exports together.
    sort: value-descending
    x_axis:
      label: Sector output (US$ billion, 2025 prices)
      min: 0
    y_axis:
      label: Sector
    series:
    - variable_prefix: SYNTHSECTOR
      selectors:
        sectors: all
        regions: USA

Download YAML Download complete CSV

Activity by region and year

A semantic diverging palette anchors the authored midpoint; a time-axis heatmap has no Year control.

Illustrative preview SVG YAML Source CSV

When to use this chart

QuestionWhere are high, low, or missing values across regions and time?

DataOne prefix varying by one model dimension and year.

UnitsOne colour scale; keep every cell in the same unit.

Preview Axes moves Year between X and Y. Year remains visible on an axis in both states, so this view has no separate Year control. Missing cells stay blank.

Complete working YAML

- chartpack:
    format: gcubed-chartpack
    version: 1.4.0
    title: Activity by region and year
    sector_selection_dimensions:
    - sectors
    - layers
    defaults:
      start_year: 2025
      end_year: 2035
- chart:
    title: Activity by region and year
    chart_type: heatmap
    show_labels: true
    x_dimension: year
    y_dimension: regions
    x_axis:
      label: Year
    y_axis:
      label: Region
    color_axis:
      min: 95
      max: 115
      midpoint: 100
      palette: semantic-diverging
    caption: A semantic diverging palette anchors the authored midpoint; a time-axis heatmap has no Year control.
    series:
    - variable_prefix: SYNTHINDEX
      selectors:
        regions: all

Download YAML Download complete CSV

Sector output by region in 2030

Two model dimensions form a matrix; the report Year control retains the authored measure and bounds.

Illustrative preview SVG YAML Source CSV

When to use this chart

QuestionHow does one measure vary across two model dimensions in one year?

DataA complete or intentionally sparse region × sector grid plus chart-level year.

UnitsUS$ billion at 2025 prices; both axes use catalogue dimension keys.

year_selector exposes only eligible years. Group complete adjacent heatmaps with view_group/view_label in a full report; this per-card YAML stays independently importable.

Complete working YAML

- chartpack:
    format: gcubed-chartpack
    version: 1.4.0
    title: Sector output by region in 2030
    sector_selection_dimensions:
    - sectors
    - layers
    defaults:
      start_year: 2025
      end_year: 2035
- chart:
    title: Sector output by region in 2030
    chart_type: heatmap
    show_labels: true
    x_dimension: regions
    y_dimension: sectors
    x_axis:
      label: Region
    y_axis:
      label: Sector
    year: 2030
    year_selector: true
    color_axis:
      min: 0
      palette: semantic-sequential
    caption: Two model dimensions form a matrix; the report Year control retains the authored measure and bounds.
    series:
    - variable_prefix: SYNTHSECTOR
      selectors:
        sectors: all
        regions: all

Download YAML Download complete CSV

Sector output paths by region

Small multiples share time and value scales so magnitude and shape remain comparable across facets.

Illustrative preview SVG YAML Source CSV

When to use this chart

QuestionHow do many related time paths compare without one crowded plot?

DataOne facet dimension, optional group dimension, common prefix and units.

UnitsUS$ billion at 2025 prices with shared scales across panels.

Use catalogue dimensions; other dimensions must stay fixed.

Complete working YAML

- chartpack:
    format: gcubed-chartpack
    version: 1.4.0
    title: Sector output paths by region
    sector_selection_dimensions:
    - sectors
    - layers
    defaults:
      start_year: 2025
      end_year: 2035
- chart:
    title: Sector output paths by region
    chart_type: small-multiples
    facet_dimension: regions
    group_dimension: sectors
    x_axis:
      label: Year
    y_axis:
      label: Sector output (US$ billion, 2025 prices)
      min: 0
    caption: Small multiples share time and value scales so magnitude and shape remain comparable across facets.
    series:
    - variable_prefix: SYNTHSECTOR
      selectors:
        sectors: all
        regions: all

Download YAML Download complete CSV

Activity and emissions in 2030

A report Year control moves every complete regional X/Y pair together while preserving fixed axes.

Illustrative preview SVG YAML Source CSV

When to use this chart

QuestionHow are two different measures positioned together in one year?

DataExplicit X/Y variable pairs whose shared dimension members match.

UnitsX is an index; Y is Mt CO2-e. Axes retain separate units.

year_selector moves every complete pair together. Points show association and position, not causality.

Complete working YAML

- chartpack:
    format: gcubed-chartpack
    version: 1.4.0
    title: Activity and emissions in 2030
    sector_selection_dimensions:
    - sectors
    - layers
    defaults:
      start_year: 2025
      end_year: 2035
- chart:
    title: Activity and emissions in 2030
    chart_type: paired-scatter
    show_labels: true
    year: 2030
    year_selector: true
    caption: A report Year control moves every complete regional X/Y pair together while preserving fixed axes.
    x_axis:
      label: Activity index (2025 = 100)
      min: 95
      max: 110
    y_axis:
      label: Emissions (Mt CO2-e)
      min: 0
      max: 65
    series:
    - x_variable: SYNTHINDEX(USA)
      y_variable: SYNTHEMISSIONS(USA)
      label: Illustrative North
    - x_variable: SYNTHINDEX(JPN)
      y_variable: SYNTHEMISSIONS(JPN)
      label: Illustrative East
    - x_variable: SYNTHINDEX(ROW)
      y_variable: SYNTHEMISSIONS(ROW)
      label: Illustrative Rest

Download YAML Download complete CSV

Illustrative North activity and emissions trajectory

Across years connects existing annual observations chronologically; Single year restores the authored point.

Illustrative preview SVG YAML Source CSV

When to use this chart

QuestionHow do two global or single-member measures move together through time?

DataExactly one authored X/Y pair with complete annual observations in the effective window.

UnitsX is an index; Y is Mt CO2-e. Existing year columns supply every trajectory point.

observation_mode: selectable defaults a report to Across years, then offers the authored single-year point. Connections are chronological, not causal.

Complete working YAML

- chartpack:
    format: gcubed-chartpack
    version: 1.4.0
    title: Illustrative North activity and emissions trajectory
    sector_selection_dimensions:
    - sectors
    - layers
    defaults:
      start_year: 2025
      end_year: 2035
- chart:
    title: Illustrative North activity and emissions trajectory
    chart_type: paired-scatter
    show_labels: true
    year: 2030
    observation_mode: selectable
    x_axis:
      label: Activity index (2025 = 100)
      min: 95
      max: 115
    y_axis:
      label: Emissions (Mt CO2-e)
      min: 0
      max: 65
    caption: Across years connects existing annual observations chronologically; Single year restores the authored point.
    series:
    - x_variable: SYNTHINDEX(USA)
      y_variable: SYNTHEMISSIONS(USA)
      label: Illustrative North

Download YAML Download complete CSV

Illustrative North sector output total

Complete additive levels reconcile to the authored total; Display switches area and bars without changing data.

Illustrative preview SVG YAML Source CSV

When to use this chart

QuestionHow does a reconciled total divide into components through time?

DataComplete nonnegative additive components and an authored total source.

UnitsUS$ billion at 2025 prices. Gross sector output is labelled sector output total, not GDP decomposition.

display_selector switches stacked area and bars without changing reconciliation. A filtered display may show only part of the complete source composition.

Complete working YAML

- chartpack:
    format: gcubed-chartpack
    version: 1.4.0
    title: Illustrative North sector output total
    sector_selection_dimensions:
    - sectors
    - layers
    defaults:
      start_year: 2025
      end_year: 2035
- chart:
    title: Illustrative North sector output total
    chart_type: composition-area
    show_labels: true
    display_selector: true
    x_axis:
      label: Year
    y_axis:
      label: Sector output (US$ billion, 2025 prices)
      min: 0
    caption: Complete additive levels reconcile to the authored total; Display switches area and bars without changing data.
    reconciliation:
      total_variable: SYNTHTOTAL(USA)
      absolute_tolerance: 0
    series:
    - variable_prefix: SYNTHSECTOR
      selectors:
        sectors: all
        regions: USA

Download YAML Download complete CSV

Illustrative North sector output shares in 2035

Choose one eligible year and either stacked display; the synthetic shares continue to reconcile to 100 percent.

Illustrative preview SVG YAML Source CSV

When to use this chart

QuestionWhat shares make up one reconciled whole in a chosen year?

DataComplete nonnegative shares with an authored initial year and eligible year window.

UnitsPercent, reconciling to the authored total of 100.

Year and Display controls retain reconciliation. Ordinary percentage deviations are not shares and are not additive.

Complete working YAML

- chartpack:
    format: gcubed-chartpack
    version: 1.4.0
    title: Illustrative North sector output shares in 2035
    sector_selection_dimensions:
    - sectors
    - layers
    defaults:
      start_year: 2025
      end_year: 2035
- chart:
    title: Illustrative North sector output shares in 2035
    chart_type: composition-bar
    show_labels: true
    year: 2035
    year_selector: true
    display_selector: true
    x_axis:
      label: Year
    y_axis:
      label: Share (%)
      min: 0
      max: 100
    caption: Choose one eligible year and either stacked display; the synthetic shares continue to reconcile to 100 percent.
    reconciliation:
      total: 100
      absolute_tolerance: 0
    series:
    - variable_prefix: SYNTHSHARE
      selectors:
        sectors: all
        regions: USA

Download YAML Download complete CSV

Ordered policy-layer contribution in 2030

Ordered contributions reconcile from zero; the report table derives an absolute level from base 100.

Illustrative preview SVG YAML Source CSV

When to use this chart

QuestionHow did ordered adjacent policy layers bridge baseline to the final package?

DataOne start, ordered contributions, one total, one year, identical additive units.

UnitsUS$ billion at 2025 prices; 0 − 12 − 9 + 10 + 3 = −8.

Preview the two populated contribution years, 2025 and 2030. level_base adds a derived absolute Level column to the report table without changing plotted contributions. Allocation still depends on layer order.

Complete working YAML

- chartpack:
    format: gcubed-chartpack
    version: 1.4.0
    title: Ordered policy-layer contribution in 2030
    sector_selection_dimensions:
    - sectors
    - layers
    defaults:
      start_year: 2025
      end_year: 2035
- chart:
    title: Ordered policy-layer contribution in 2030
    chart_type: waterfall
    show_labels: true
    year: 2030
    year_selector: true
    level_base: 100
    caption: Ordered contributions reconcile from zero; the report table derives an absolute level from base 100.
    x_axis:
      label: Policy layer
    y_axis:
      label: GDP change (US$ billion, 2025 prices)
      min: -25
      max: 5
    series:
    - variable: SYNTHGDPCHANGE(BASELINE,USA)
      label: Baseline
      role: start
    - variable_prefix: SYNTHGDPCONTRIBUTION
      selectors:
        regions: USA
      role: contribution
    - variable: SYNTHGDPCHANGE(PACKAGE,USA)
      label: Final package
      role: total

Download YAML Download complete CSV

Grouped heatmap view

Switch View from the time-axis heatmap to the region × sector matrix. Year then becomes a separate choice because it is no longer on either visible axis.

Activity by region and year

A semantic diverging palette anchors the authored midpoint; a time-axis heatmap has no Year control.

Illustrative preview SVG YAML Source CSV

Year appears only in the matrix view, where neither visible axis is year. Import the grouped YAML and CSV to use the report controls.

Complete grouped-view YAML

- chartpack:
    format: gcubed-chartpack
    version: 1.4.0
    title: Grouped heatmap views — synthetic guide
    sector_selection_dimensions:
    - sectors
    - layers
    defaults:
      start_year: 2025
      end_year: 2035
- chart:
    title: Activity by region and year
    chart_type: heatmap
    show_labels: true
    x_dimension: year
    y_dimension: regions
    x_axis:
      label: Year
    y_axis:
      label: Region
    color_axis:
      min: 95
      max: 115
      midpoint: 100
      palette: semantic-diverging
    caption: A semantic diverging palette anchors the authored midpoint; a time-axis heatmap has no Year control.
    series:
    - variable_prefix: SYNTHINDEX
      selectors:
        regions: all
    view_group: synthetic-guide-heatmaps
    view_label: Regions × years
- chart:
    title: Sector output by region in 2030
    chart_type: heatmap
    show_labels: true
    x_dimension: regions
    y_dimension: sectors
    x_axis:
      label: Region
    y_axis:
      label: Sector
    year: 2030
    year_selector: true
    color_axis:
      min: 0
      palette: semantic-sequential
    caption: Two model dimensions form a matrix; the report Year control retains the authored measure and bounds.
    series:
    - variable_prefix: SYNTHSECTOR
      selectors:
        sectors: all
        regions: all
    view_group: synthetic-guide-heatmaps
    view_label: Sectors × regions

Download grouped YAML Download complete CSV

Feature map and authoring rules

Preview Axes changes the authored heatmap dimension arrangement; axis selection is a YAML choice, not a report dropdown. Year, View, Observations and Display are report controls when enabled. Import the complete YAML and CSV to try live controls, current-view tables, filters and CSV/SVG/PNG actions.

Control or presentation	YAML	Authoring rule
Year	`year_selector: true`	Snapshot, matrix heatmap, paired scatter, one-year composition and waterfall examples preview eligible years. The waterfall source has contributions in 2025 and 2030; the report checks values and reconciliation before offering a year.
Heatmap View	`view_group` + `view_label`	Group adjacent heatmap definitions. Each view carries its own measure, axes, units, caption, palette and bounds. The grouped example includes independently importable YAML.
Observations	`observation_mode: selectable`	Exactly one paired X/Y pair defaults to its existing annual trajectory; Single year shows the selected point.
Display	`display_selector: true`	A reconciled composition switches between area and bars without changing component values.
Axis choice and labels	`x_dimension`, `y_dimension`, `x_axis`, `y_axis`	Choose heatmap dimensions or paired X/Y variables in YAML. Labels override inferred titles on every chart type; numeric min/max bounds apply only to numeric axes. The time heatmap preview moves Year from X to Y, so Year stays visible on an axis in both states; the grouped View example shows Year as a separate choice.
Bars and facets	`orientation`, `sort`, `facet_dimension`, `group_dimension`	Horizontal sorted delta bars, sorted snapshot bars and shared-scale facets show these authored choices.
Semantic presentation	`color_by_sign`, `color_axis.palette`, `show_labels`	Sign colours, heatmap palettes and value labels are explicit chart choices.
Filters and card outputs	`sector_selection_dimensions`, `caption`	The complete guide YAML configures sector/layer filters. Report cards show captions, current-view tables, CSV/SVG/PNG actions and source downloads.
Derived waterfall level	`level_base`	For a zero-start waterfall, add an absolute Level column to the report table without changing source or plotted contributions.

Preview selectors swap pre-rendered SVGs. The report controls recompute the chart, caption, table and exports from the downloaded YAML and CSV.

Use these with real G-Cubed results

Imports used below

from pathlib import Path

import pandas as pd

from gcubed.experiments import generate_setup_artefacts
from gcubed.reporting import generate_all_simulation_results, generate_html_report

1 · Start from the catalogue

Choose exact variables and the right dataframe

Inspect charting_projections, including exact IDs, prefix, dimension descriptions, units, vector and region.
Choose levels, shares or deviations deliberately. Confirm price basis and additivity before composition or waterfall work.
Quote CSV IDs and metadata containing commas. Keep year columns as strings when constructing a pandas dataframe.

catalogue = all_projections[0].charting_projections
print(catalogue[[
    "prefix", "set_member_descriptions", "description",
    "units", "vector", "region",
]].to_string())

2 · Select the runtime template

Keep setup authoring separate from reporting

setup.yaml can generate chartpack artefacts. This concise example uses a clearly marked placeholder; replace it with an exact ID from your catalogue.

# setup.yaml
schema_version: 1
kind: baseline
model:
  configuration_file_name: model_configuration.yaml
chartpack:
  title: Policy snapshot
  charts:
    - title: Selected result in 2030
      chart_type: series-value
      year: 2030
      series:
        - variable: "<exact variable ID from catalogue>"

# setup.py, beside setup.yaml
generate_setup_artefacts(Path(__file__))

setup.yaml does not select the runtime report template. Choose the built template in the run script.

SCRIPT_FOLDER = Path(__file__).resolve().parent
REPORT_TEMPLATE_FILE = Path(
    "/path/to/gcubed-results-charting-template-builder/"
    "production-output/template/chart-template.html"
)
CHARTPACK_FILES = ("chartpack.yaml",)

3 · Batch ordinary reports

Use one compatible pack across every generated dataframe

generate_all_simulation_results applies the same chartpack to levels, baseline deviations and incremental deviations. It raises if any dataframe is incompatible; it does not silently skip composition.

all_projections = list(runner.all_projections)  # baseline first
generate_all_simulation_results(
    chartpack_path=SCRIPT_FOLDER / "chartpack.yaml",
    documentation_path=SCRIPT_FOLDER / "documentation.md",
    template_path=REPORT_TEMPLATE_FILE,
    results_directory_path=RESULTS_FOLDER.resolve(),
    all_projections=all_projections,
    derivations=derivations,
    show_final_results=False,
)

Meaning: series-value on a deviation CSV compares the selected series’ deviations from the baseline in one chosen year. series-delta compares two years inside whichever dataframe was supplied.

4 · Report a chosen levels/share frame

Use the public single-report boundary for composition

Composition needs complete additive levels or shares. Pass that chosen dataframe directly instead of blindly using a composition omnibus pack for batch levels and percentage deviations.

generate_html_report(
    configuration=projection.configuration,
    title="Policy results",
    subtitle="Chosen level or share dataframe",
    documentation_path=documentation_path,
    projections=chosen_level_or_share_dataframe,
    chartpack_path=composition_chartpack_path,
    template_path=REPORT_TEMPLATE_FILE,
    output_path=report_path,
)

Ordinary percentage deviations are not additive. Never stack them as shares or levels.

5 · Export ordered contributions

Opt in with exact source level IDs

Select exact additive level IDs from the real catalogue. The producer writes projections_data/layer-contributions.csv after ordinary reports. Baseline must be first in ordered all_projections.

selected_additive_level_id = "<exact ID copied from catalogue>"
generate_all_simulation_results(
    chartpack_path=SCRIPT_FOLDER / "chartpack.yaml",
    documentation_path=SCRIPT_FOLDER / "documentation.md",
    template_path=REPORT_TEMPLATE_FILE,
    results_directory_path=RESULTS_FOLDER.resolve(),
    all_projections=all_projections,
    derivations=derivations,
    layer_contribution_variables=[selected_additive_level_id],
    show_final_results=False,
)

Illustrative naming: source SYNTHGDP(USA) at ordered cumulative levels 1000 → 988 → 979 → 989 → 992 produces SYNTHGDPCHANGE(BASELINE,USA), SYNTHGDPCONTRIBUTION(LAYER_1,USA) … and SYNTHGDPCHANGE(PACKAGE,USA), with layer labels from the ordered projections. Values are 0, −12, −9, +10, +3 and −8.

6 · Render the waterfall separately

Pair contribution CSV with waterfall YAML

The contribution export does not automatically create waterfall HTML. Drop the waterfall YAML and contribution CSV together into a report, use the SVG CLI, or make a second public report call.

contribution_path = (
    RESULTS_FOLDER / "projections_data" / "layer-contributions.csv"
)
generate_html_report(
    configuration=all_projections[0].configuration,
    title="Ordered layer contributions",
    subtitle="Additive change from baseline",
    documentation_path=SCRIPT_FOLDER / "documentation.md",
    projections=pd.read_csv(contribution_path, index_col=0),
    chartpack_path=SCRIPT_FOLDER / "waterfall.yaml",
    template_path=REPORT_TEMPLATE_FILE,
    output_path=RESULTS_FOLDER / "html_reports" / "layer-contributions.html",
)

Input contract

Wide projections CSV stays unchanged

Identity	Required metadata	Values
Exact variable ID in first column	`prefix`, `set_member_descriptions`, `description`, `units`, `vector`, `region`	One column per year

Complete composition sources reconcile before filtering. The visible table may show only selected components; the source CSV and per-chart export retain all source components under current export policy. Waterfalls filter atomically, require role order start → contribution… → total, and allow only the configured reconciliation tolerance.

Uncertainty remains deferred. Fan or interval charts need exported ensembles or interval bounds. A collection of deterministic scenarios is not a confidence band.

Generated from src/chart-types-guide/guide-chartpack.yaml and guide-projections.csv. SVGs come from the repository’s shared renderer CLI. Canonical behavior remains in docs/YAML-chartpack/SPECIFICATION.md and its schema.