Chartpack validation and troubleshooting

Check a chartpack with the same projections CSV that the report will use. Correct YAML structure does not guarantee that its variables, dimensions, years or units match the experiment results.

Start with these checks

1. Begin with a - chartpack: item containing format: gcubed-chartpack, a supported version and a nonblank title. Include at least one - chart:.
2. Use version "1.4.0" for the new chart types and controls. Numeric 1 means 1.0.0. Both the reporting package and template must support the version; see compatibility.
3. Use one UTF-8 YAML document, spaces for indentation and the exact field names. Anchors, aliases, custom tags and extra documents are not accepted.
4. Give each chart a series list, directly or through its section. Exact variable names and selector codes must match the CSV, including capitals.
5. Check the units and whether the file contains levels, baseline deviations or deviations from the preceding simulation layer. A chart title does not transform the observations.
6. Check the selected years and the rules for the chosen chart type below. Missing values and zero have different meanings.
7. Quote colours beginning with #. Use a supported line style. Omit unused optional settings instead of supplying empty objects or null.

A copy of the matching JSON Schema is available for tools that check YAML structure. Checks involving actual results, reconciliation, grouped views and CSS colours also require the report’s data-aware validation.

When a particular chart fails

Symptom or chart	What to check
Selector finds no rows	Use a prefix without parentheses, dimension keys from set_member_descriptions, and raw member codes. Derived variables must already be in the CSV.
Unexpected series order	Selectors follow CSV row order. Use exact entries for a chosen order, or sort on comparison bars.
Gaps in a line or small multiple	Time windows may extend beyond available data. Missing observations remain gaps.
Missing delta bar	Both explicitly supplied or inherited endpoints must have finite numbers, with the start strictly before the end.
Invalid delta chart	Bars must share units, prefix and ordered dimensions, varying over at most one dimension.
Missing single-year bar or scatter point	Each selected value, or both members of a scatter pair, must be available and finite in year. Scatter units must match separately on X and Y.
Invalid heatmap	Axes must differ. Use year only for two model axes. Other dimensions must stay fixed; no two rows may occupy one cell. Blank cells are allowed, but at least one numeric value is needed.
Invalid small multiples	Facet and optional group must differ. Other dimensions stay fixed, and each facet/group combination must be unique. A group cannot have conflicting colours.
Invalid composition	Every component must be present, nonnegative and counted once. Components must share a prefix, units and ordered dimensions, varying across at most one set. They must add to the stated total in every displayed year. Check the total’s units and region too.
Invalid waterfall	Use one start, ordered contributions and one total, each once. All values must be finite, use the same units, have consistent region metadata and add to the final total.
Missing Year control	It needs at least two eligible years. It is automatic for series-value, opt-in for other supported types, and forbidden on time-axis heatmaps and delta charts.
Rejected heatmap group	Both group fields are required. Keep at least two complete views adjacent within one section, with unique labels.
Axis bounds do nothing	Numeric bounds do not apply to category axes. Horizontal bars use X bounds; heatmaps use color_axis for values.

For rounding differences in compositions or waterfalls, choose an absolute_tolerance justified by the units and precision of the results. Zero requires exact numerical equality. If omitted, the template uses a small relative-to-scale allowance (5e-9 times the larger of 1 and the sum of the absolute component/start and total values). A tolerance should not conceal missing sectors, inconsistent units or contributions counted twice.

Understand warnings and rejected files

The browser template can omit an invalid ordinary series or chart and draw those that remain valid. Check its warnings before relying on a report. A composition or waterfall is omitted in full if any required component or step fails. A grouped heatmap is omitted in full if one of its views cannot be resolved. Invalid file structure, an unsupported version, invalid chartpack selection metadata or malformed view grouping rejects the whole file.

A warning identifies the chart or section and its location in the YAML, for example [3].chart.series[0].variable. The bracketed numbers count from zero: this example refers to the first series in the fourth main item. Where the chart or section remains in the report, its warning links to it.

An empty, consecutive or final section is allowed. Its heading remains and a warning explains that it contains no charts. At least one chart is still required elsewhere in the file. A Python reporting or schema-validation step may reject a file before the browser’s partial-rendering behaviour applies.

If setup creates the chartpack, correct setup.yaml and regenerate it. Changes made only to its generated chartpack.yaml will be replaced on the next setup run.