# F01 Chart Contracts

Delivery surface: deterministic standalone SVG figures stored in `FIGURES/`, generated by the local analysis pipeline from reviewed processed CSV. This is an explicit exported research-figure surface required by the F01 brief; no inline widget or HTML report is selected.

Palette: white background, charcoal text, quiet grey guides, blue root `#2563eb`, gold root `#c58a00`, orange root `#d97706`; every distinction also uses labels, line style, marker shape, or ordering. No green/red semantics.

## C1 — Vintage revision trajectories

- Question: how much do legitimate later vintages move the same observations?
- Takeaway sought: revisions are usually small relative to levels but can be large relative to period changes.
- Family/variant: trend; highlighted multi-series line or dumbbell by period, chosen after overlap count is known.
- Sufficiency: at least 8 comparable periods/entities; otherwise use a labeled grouped bar.
- Fields: dataset, observation period/entity, earlier value, later value, absolute revision, revision-to-level, revision-to-change.
- Scale: levels use an honest shared scale; revision panels show signed deltas around a visible zero line.
- Output: `FIGURES/revision_trajectories.svg` plus chart-ready CSV.

## C2 — Conclusion fragility by transformation

- Question: which transformations or decision labels are most sensitive to vintage choice?
- Takeaway sought: levels, growth, rank, sign, and threshold claims have different revision exposure.
- Family/variant: comparison; horizontal bars from zero with direct counts/rates and dataset strata.
- Sufficiency: at least 4 meaningful categories; otherwise use an exact table.
- Fields: transform class, comparison count, conclusion-flip count, flip rate, denominator notes.
- Output: `FIGURES/conclusion_fragility.svg` plus chart-ready CSV.

## C3 — Scenario and uncertainty layers

- Question: how do starting-vintage uncertainty and named-assumption scenario spread differ in a controlled population projection fixture?
- Takeaway sought: a scenario envelope is conditional and distinct from uncertainty in the starting published vintage.
- Family/variant: uncertainty and benchmark; explicit low/high assumption band, solid base path, and dashed alternative-vintage base path.
- Sufficiency: seven annual points are intentionally retained because this is a discrete 2024–2030 scenario fixture rather than a claimed long-run trend; exact values remain in the backing table.
- Fields: year, scenario, starting vintage, starting value, constant annual growth assumption, modeled value, units.
- Output: `FIGURES/scenario_uncertainty.svg` plus chart-ready CSV.

## C4 — Census vintage revision distribution

- Question: how are Vintage 2024-to-2025 changes distributed across state/DC population estimates for the common 2024 reference date?
- Takeaway sought: the distribution is concentrated but has named outliers; a single average hides them.
- Family/variant: distribution; histogram plus a ranked bar panel for the largest absolute revisions.
- Sufficiency: 51 same-grain state/DC observations.
- Fields: geography, earlier/later value, absolute revision, percent-of-level revision.
- Output: `FIGURES/census_vintage_revisions.svg` plus `ANALYSIS/processed/census_revision_metrics.csv`.

## C5 — EIA conditional scenario cases

- Question: how do the AEO2026 Counterfactual Baseline, High Economic Growth, and Low Economic Growth total-energy paths differ?
- Takeaway sought: the paths are conditional cases without assigned probabilities, not a forecast interval.
- Family/variant: uncertainty and benchmark; three directly labeled lines with distinct dash/marker patterns.
- Sufficiency: 27 annual points from 2024 through 2050 for each case.
- Fields: year, low, baseline, high, spread, units, publisher case identifier.
- Output: `FIGURES/eia_scenario_cases.svg` plus `ANALYSIS/processed/eia_scenario_values.csv`.

## C6 — BEA GDP vintage comparison

- Question: how do first-published and latest-available real GDP growth estimates differ across the most recent 20 complete quarters?
- Takeaway sought: percentage-point revisions can change threshold or sign conclusions even when the underlying stage labels differ by quarter.
- Family/variant: trend/comparison; paired lines with markers and a visible zero line.
- Sufficiency: 20 quarterly observations at a common concept and unit.
- Fields: quarter, initial stage/value, latest stage/value, percentage-point revision, sign and threshold flags.
- Output: `FIGURES/bea_gdp_vintage_revision.svg` plus `ANALYSIS/processed/bea_revision_metrics.csv`.

## Final QA

Inspect exported figures at full size and a mobile-width raster preview. Verify title/subtitle/units/source, honest axes, direct labels, no clipping/collision, non-color distinction, consistent data grain, and exact agreement with processed tables.

## Post-collection contract deviations

- **C3 rendering:** the final SVG draws all six vintage × assumption paths, using dashed V2024 and solid V2025 lines, rather than a filled low/high band. This preserves both uncertainty layers without implying probability mass inside a band.
- **C5 period count:** preregistration expected 27 annual points for 2024–2050 because each EIA record declares `start=2024` and `lastHistoricalPeriod=2024`. Direct inspection found 26 actual data pairs, 2025–2050, in every selected record. The chart uses only those observed keys, states the discrepancy, and does not fabricate 2024. This is logged as DQ06.