feat(esmvaltool): emit series kind (model vs reference)

[lewisjared]

Description

ESMValTool series now emit an explicit kind of either model or reference, so an observation curve can be distinguished from a model curve directly instead of being inferred from the presence of reference_source_id in the series dimensions.

The shared series extractor derives kind from whether the series definition carries reference_source_id; all series-emitting diagnostics already follow that convention. Since the default model is omitted from the serialised bundle, only reference series change on disk: the four affected regression baselines (cloud-radiative-effects, enso-basic-climatology, and sea-ice-area-basic for both cmip6 and cmip7) were re-minted, and every other committed bundle is unchanged and replays without drift. Scalars are unaffected, as ESMValTool emits no reference scalars.

A new contract test asserts, across every committed series.json, that each series carries the correct kind and a uniform presentation-attribute key set.

Checklist

Please confirm that this pull request has done the following:

• Tests added
• Documentation added (where applicable)
• Changelog item added to changelog/

Summary by CodeRabbit

• New Features

  • Series outputs now include an explicit kind field to distinguish model vs reference curves more reliably, improving how observation curves are presented.

• Bug Fixes

  • Corrected series labelling logic and updated impacted regression baselines/fixtures to align with the new series kind labelling.

• Tests

  • Added unit and contract tests to verify series kind assignment rules and consistent attribute coverage across committed series.json baselines.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2d2adb51-22d6-45ca-a560-f36f58f5c29e

📥 Commits

Reviewing files that changed from the base of the PR and between 0f3601a and a23644d.

📒 Files selected for processing (1)

• packages/climate-ref-esmvaltool/tests/test-data/sea-ice-area-basic/cmip7/manifest.json

---

📝 Walkthrough

Walkthrough

This PR adds an explicit kind field ("model" or "reference") to ESMValTool series extraction, derived from reference_source_id. Committed regression baselines and manifests are updated, and new unit and contract tests cover the new field.

Changes

Series kind field

Layer / File(s)	Summary
Core kind derivation logic and changelog packages/climate-ref-esmvaltool/src/climate_ref_esmvaltool/diagnostics/base.py, changelog/776.feature.md	Imports MetricValueKind and derives kind ("reference" if reference_source_id is in series_def.dimensions, else "model") when constructing SeriesMetricValue; the changelog documents the new field.
Unit and contract tests for kind packages/climate-ref-esmvaltool/tests/unit/diagnostics/test_base.py, packages/climate-ref-esmvaltool/tests/unit/test_series_contract.py	Adds a parametrised test verifying kind classification during series extraction, plus a contract test suite asserting kind correctness and attribute-key consistency across all committed baseline series.json files.
Cloud-radiative-effects baseline updates packages/climate-ref-esmvaltool/tests/test-data/cloud-radiative-effects/cmip6/manifest.json, packages/climate-ref-esmvaltool/tests/test-data/cloud-radiative-effects/cmip6/regression/series.json	Updates the manifest hash and test_case_version, and inserts "kind": "reference" into six regression series entries.
Enso-basic-climatology baseline updates packages/climate-ref-esmvaltool/tests/test-data/enso-basic-climatology/cmip6/manifest.json, packages/climate-ref-esmvaltool/tests/test-data/enso-basic-climatology/cmip6/regression/series.json	Updates the manifest hash and test_case_version, and inserts "kind": "reference" into twelve regression series entries.
Sea-ice-area-basic baseline updates (CMIP6/CMIP7) packages/climate-ref-esmvaltool/tests/test-data/sea-ice-area-basic/cmip6/manifest.json, packages/climate-ref-esmvaltool/tests/test-data/sea-ice-area-basic/cmip6/regression/series.json, packages/climate-ref-esmvaltool/tests/test-data/sea-ice-area-basic/cmip7/manifest.json, packages/climate-ref-esmvaltool/tests/test-data/sea-ice-area-basic/cmip7/regression/series.json	Updates CMIP6 and CMIP7 manifest hashes and versions, and inserts "kind": "reference" into the regression series baselines for both climatology versions.

Sequence Diagram(s)

sequenceDiagram
  participant base.py
  participant series_def
  participant SeriesMetricValue

  base.py->>series_def: inspect dimensions
  series_def-->>base.py: dimensions list
  base.py->>base.py: kind = "reference" if reference_source_id in dimensions else "model"
  base.py->>SeriesMetricValue: construct with kind

Loading

Possibly related PRs

• Climate-REF/climate-ref#772: Adds the same SeriesMetricValue.kind discriminator at the core series metric contract level.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the main change: emitting series kind as model/reference.
Description check	✅ Passed	The description covers the required sections and includes a filled checklist with tests and changelog items.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/layer-a-esmvaltool

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
core	92.35% <ø> (ø)
providers	86.31% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...ool/src/climate_ref_esmvaltool/diagnostics/base.py	89.63% <100.00%> (+0.06%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.