Chart display options

These recipes extend the chart types. Put each option under an individual chart, with version: "1.4.0" in the file’s first chartpack item. The examples are chart entries to add after that item. Use actual variable IDs and dimension names from your projections.

Explain a chart with a caption

Use caption for a short note below the plot. It is plain text, so write the explanation directly rather than HTML.

- chart:
    title: Inflation
    caption: Percentage-point deviation from the baseline.
    series:
      - variable: INFL(USA)

Captions work with every chart type. They appear in the report card; image exports keep the chart title. Each card also offers its current data table and CSV, SVG and PNG actions.

Set show_labels: true when readers need values without hovering. For example, label the ends of comparison bars:

- chart:
    chart_type: series-value
    year: 2030
    show_labels: true
    series:
      - variable: INFL(USA)
      - variable: INFL(CHN)

This also labels delta bars, heatmap cells, scatter points, waterfall steps and composition bars. It works on composition-area only when display_selector: true allows a switch to bars. It is not available on line or small-multiple charts. Missing heatmap cells stay blank; zero is labelled. Labels show up to four significant digits, with % for percentages and pp for percentage points. Tables and downloads retain the underlying numbers.

Order and colour comparison bars

Use these options on series-value or series-delta:

- chart:
    chart_type: series-value
    year: 2030
    orientation: horizontal
    sort: value-descending
    color_by_sign: true
    x_axis:
      label: Inflation rate
      min: -5
      max: 10
    series:
      - variable: INFL(USA)
      - variable: INFL(CHN)

orientation is horizontal or vertical. Delta bars start vertical; single-year value bars start horizontal. sort can be value-ascending or value-descending. Without it, the YAML/selector order remains. Equal values keep their original order. color_by_sign: true uses one colour for positive values, another for negative values and a neutral colour for zero; it replaces per-series bar colours. On horizontal bars, numeric bounds belong in x_axis. On vertical bars, put them in y_axis.

Let readers choose a year

A series-value report shows a Year control by default when more than one valid year is available. Set year_selector: false to keep its authored year. Other supported charts need year_selector: true to offer the control:

- chart:
    chart_type: heatmap
    x_dimension: regions
    y_dimension: sectors
    year: 2030
    year_selector: true
    series:
      - variable_prefix: OUP
        selectors:
          regions: [USA, CHN]
          sectors: all

The optional control also works for paired-scatter, composition-area, composition-bar and waterfall. It offers only years for which that chart has valid data within its effective start/end range, together with the valid initial year even if that year lies outside the range. The control is hidden when fewer than two years qualify. Heatmaps may have blank cells, but need at least one numeric cell. Compositions and waterfalls must add to their totals. On a composition, year may be set only with year_selector: true; with both fields the report starts with one year. Without year, a composition still begins with its full year range. A heatmap with year on an axis has no Year control. A delta chart uses its two endpoints and cannot use this control. Choosing another year updates the plot, visible table and per-chart CSV and image exports. The downloaded source projections and chartpack files remain the ones supplied to the report.

Heatmap colours and views

Use color_axis to keep the same colour scale across filters and, when both limits are specified, across selected years. Without explicit limits, the scale is based on the selected source values before filtering. A midpoint is useful for deviations around zero:

- chart:
    chart_type: heatmap
    x_dimension: year
    y_dimension: regions
    color_axis:
      min: -5
      midpoint: 0
      max: 5
      palette: semantic-diverging
    series:
      - variable_prefix: INFL
        selectors:
          regions: [USA, CHN]

semantic-diverging colours values on either side of a midpoint differently. semantic-sequential runs from pale to dark for values that increase in one direction. Without palette, the standard scale is pale blue to blue, or blue through light grey to red when midpoint is supplied. A semantic diverging palette uses the scale centre when no midpoint is supplied. If you set a midpoint, it must lie strictly between the scale’s minimum and maximum.

To put several heatmaps in one report card, give adjacent chart entries the same view_group and different view_label values:

- chart:
    title: Inflation
    chart_type: heatmap
    view_group: regional-results
    view_label: Inflation
    x_dimension: year
    y_dimension: regions
    series:
      - variable_prefix: INFL
        selectors:
          regions: [USA, CHN]
- chart:
    title: Interest rate
    chart_type: heatmap
    view_group: regional-results
    view_label: Interest rate
    x_dimension: year
    y_dimension: regions
    series:
      - variable_prefix: INTN
        selectors:
          regions: [USA, CHN]

Each view remains a complete heatmap with its own title, units, caption and colour settings. Use at least two views, keep their labels unique, and do not place a chart or section between them. The report shows one card with a View control and one table-of-contents entry. The first definition is the initial view. Changing View restores that definition’s initial year and settings; only eligible single-year views show Year. Incorrect grouping rejects the file. If one grouped heatmap cannot be resolved against the data, the whole group is omitted with warnings.

Show a pair’s path over time

For one X/Y pair, observation_mode: selectable starts with a path through the annual observations for which both values are available. Readers can switch to a single-year point.

- chart:
    chart_type: paired-scatter
    year: 2030
    start_year: 2025
    end_year: 2035
    observation_mode: selectable
    show_labels: true
    series:
      - x_variable: GDPR(USA)
        y_variable: EM(CO2,USA)

The path shows years beside its points when labels are enabled. This mode requires exactly one pair and at least one complete annual observation. Missing or non-finite pairs of values are omitted from the path. Do not set year_selector: false with it.

Switch between stacked areas and bars

display_selector: true lets readers switch a reconciled composition between an area chart and stacked bars. The authored type is the initial view.

- chart:
    chart_type: composition-area
    display_selector: true
    reconciliation:
      total_variable: TOTAL_OUTPUT(USA)
    series:
      - variable_prefix: OUP
        selectors:
          regions: [USA]
          sectors: all

Use exactly one of reconciliation.total or reconciliation.total_variable. An optional nonnegative absolute_tolerance permits a small rounding difference. Every component must be present, nonnegative and reconcile in each displayed year. Hiding a component in the report produces a partial-composition notice; it does not change the source total or the per-chart CSV.

Show a waterfall level

If a waterfall’s start value is exactly zero, level_base adds a derived absolute Level column to its visible table:

- chart:
    chart_type: waterfall
    year: 2030
    level_base: 100
    series:
      - variable: START_CHANGE(USA)
        role: start
      - variable: DEMAND_CONTRIBUTION(USA)
        role: contribution
      - variable: TOTAL_CHANGE(USA)
        role: total

The Level column is level_base + Cumulative, in the same units as the contributions. Only years with a zero start qualify for its Year control. The plot, source contribution values and per-chart CSV stay the same. A waterfall can also set reconciliation.absolute_tolerance when tiny rounding differences keep otherwise valid contributions from adding to the total.

Tables and downloads

Each report chart has a table and CSV, SVG and PNG actions. Year, View, Observations and Display choices update the chart, its table and exports together. Captions appear beneath plots in the report; images retain the chart title, but do not include the caption.

The table reflects visible series. Per-chart CSV includes the chart’s full selected data, including series hidden by filters, for the current year or observation mode. It does not reproduce the complete projections CSV. For example, a heatmap has a matrix table but downloads one CSV row per cell; a trajectory downloads one row per retained annual pair. Composition CSVs contain components, not an extra copy of the total. Waterfall CSVs contain source values and cumulative changes, but not the optional derived Level column.

Use the page’s Download CSV data and Download chartpack YAML actions to keep the complete input files. These preserve the files supplied to the report, including accepted replacements. Per-chart analysis CSVs have a different column structure and cannot replace the input projections CSV.

In a generated report made with the latest template, the input controls also accept replacement YAML and projections CSV. Replace both together when a chartpack uses variables from a different dataset. If validation rejects the replacement, the last accepted sources remain available.