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

changelog/776.feature.md

@@ -0,0 +1,3 @@
+ESMValTool series now carry an explicit `kind` of either `model` or `reference`,
+so an observation curve can be distinguished from a model curve directly
+rather than inferred from the presence of a reference source.

packages/climate-ref-esmvaltool/src/climate_ref_esmvaltool/diagnostics/base.py

@@ -19,7 +19,7 @@
     ExecutionDefinition,
     ExecutionResult,
 )
-from climate_ref_core.metric_values.typing import SeriesMetricValue
+from climate_ref_core.metric_values.typing import MetricValueKind, SeriesMetricValue
 from climate_ref_core.pycmec.metric import CMECMetric, MetricCV
 from climate_ref_core.pycmec.output import CMECOutput, OutputCV
 from climate_ref_esmvaltool.recipe import (
@@ -517,9 +517,15 @@ def _extract_series_from_file(
                     # Convert byte strings from NetCDF to regular strings.
                     index = [v.decode().strip() for v in index]
 
+                # A reference (observation) series is signalled by ``reference_source_id`` in the
+                # definition's dimensions; everything else is a model series.
+                kind: MetricValueKind = (
+                    "reference" if "reference_source_id" in series_def.dimensions else "model"
+                )
                 series.append(
                     SeriesMetricValue(
                         dimensions={**input_selectors, **series_def.dimensions},
+                        kind=kind,
                         values=fillvalues_to_nan(dataset[series_def.values_name].values).tolist(),
                         index=index,
                         index_name=series_def.index_name,

packages/climate-ref-esmvaltool/tests/test-data/cloud-radiative-effects/cmip6/manifest.json

@@ -3,7 +3,7 @@
   "committed": {
     "diagnostic.json": "183d82f3963ad19b5a556b8025e6990c444f292adda1d464e12136d05a5ef3b3",
     "output.json": "4b9ebaf83c65b8e0718a84951502617a545fce6386cabe640de7ec406afe6509",
-    "series.json": "4ec8ab11924089ef7cba8bd16de237ad8431399caaef74c0a66e81fefee69ef3"
+    "series.json": "50c0cf4550d4ed6aaa42579957fa3603cfce3d2200bb7880bd7a7e66f09f5376"
   },
   "diagnostic_version": 1,
   "native": {
@@ -81,5 +81,5 @@
     }
   },
   "schema": 2,
-  "test_case_version": 1
+  "test_case_version": 2
 }

packages/climate-ref-esmvaltool/tests/test-data/cloud-radiative-effects/cmip6/regression/series.json

@@ -200,6 +200,7 @@
       89.5
     ],
     "index_name": "lat",
+    "kind": "reference",
     "values": [
       -1.102461,
       -0.6439076,
@@ -584,6 +585,7 @@
       89.5
     ],
     "index_name": "lat",
+    "kind": "reference",
     "values": [
       -2.597448,
       -2.985919,
@@ -968,6 +970,7 @@
       89.5
     ],
     "index_name": "lat",
+    "kind": "reference",
     "values": [
       6.785992,
       7.329451,
@@ -1352,6 +1355,7 @@
       89.5
     ],
     "index_name": "lat",
+    "kind": "reference",
     "values": [
       -9.128001,
       -8.946151,
@@ -1736,6 +1740,7 @@
       89.5
     ],
     "index_name": "lat",
+    "kind": "reference",
     "values": [
       5.890097,
       5.866584,
@@ -2120,6 +2125,7 @@
       89.5
     ],
     "index_name": "lat",
+    "kind": "reference",
     "values": [
       -0.5029026,
       -0.4262416,

packages/climate-ref-esmvaltool/tests/test-data/enso-basic-climatology/cmip6/manifest.json

@@ -3,7 +3,7 @@
   "committed": {
     "diagnostic.json": "183d82f3963ad19b5a556b8025e6990c444f292adda1d464e12136d05a5ef3b3",
     "output.json": "f1a62fdcea7c346688eb476587778df31bec3e0b457b8fb5b4aeb7d57d2bb63e",
-    "series.json": "2e7f6ee7162116378d21f0f405d639244ea8e53b74c2dfe2260ad0e1665b3ec9"
+    "series.json": "ad93b4525763b2e0070f0bf92a20d95ea77731b911e21da770d5fba7d13e7782"
   },
   "diagnostic_version": 1,
   "native": {
@@ -149,5 +149,5 @@
     }
   },
   "schema": 2,
-  "test_case_version": 1
+  "test_case_version": 2
 }

packages/climate-ref-esmvaltool/tests/test-data/enso-basic-climatology/cmip6/regression/series.json

@@ -50,6 +50,7 @@
       14.5
     ],
     "index_name": "lat",
+    "kind": "reference",
     "values": [
       0.8117609,
       0.9348878,
@@ -134,6 +135,7 @@
       14.5
     ],
     "index_name": "lat",
+    "kind": "reference",
     "values": [
       0.4165757,
       0.3797182,
@@ -218,6 +220,7 @@
       14.5
     ],
     "index_name": "lat",
+    "kind": "reference",
     "values": [
       1.640816,
       1.671181,
@@ -392,6 +395,7 @@
       269.5
     ],
     "index_name": "lon",
+    "kind": "reference",
     "values": [
       1.553391,
       1.584454,
@@ -656,6 +660,7 @@
       269.5
     ],
     "index_name": "lon",
+    "kind": "reference",
     "values": [
       0.4707869,
       0.448114,
@@ -920,6 +925,7 @@
       269.5
     ],
     "index_name": "lon",
+    "kind": "reference",
     "values": [
       14.90164,
       16.3394,
@@ -1184,6 +1190,7 @@
       269.5
     ],
     "index_name": "lon",
+    "kind": "reference",
     "values": [
       8.117987,
       8.118301,
@@ -1448,6 +1455,7 @@
       269.5
     ],
     "index_name": "lon",
+    "kind": "reference",
     "values": [
       1.553391,
       1.584454,
@@ -1712,6 +1720,7 @@
       269.5
     ],
     "index_name": "lon",
+    "kind": "reference",
     "values": [
       0.4707869,
       0.448114,
@@ -1976,6 +1985,7 @@
       269.5
     ],
     "index_name": "lon",
+    "kind": "reference",
     "values": [
       14.90164,
       16.3394,
@@ -2240,6 +2250,7 @@
       269.5
     ],
     "index_name": "lon",
+    "kind": "reference",
     "values": [
       29.65842,
       29.57058,
@@ -2504,6 +2515,7 @@
       269.5
     ],
     "index_name": "lon",
+    "kind": "reference",
     "values": [
       -4.569511,
       -5.326211,

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

@@ -3,7 +3,7 @@
   "committed": {
     "diagnostic.json": "183d82f3963ad19b5a556b8025e6990c444f292adda1d464e12136d05a5ef3b3",
     "output.json": "ece9f19183b1bede25cda85779d3eb905f51bc24615559dbcc2ac6688835cd92",
-    "series.json": "8ad040e4747b2fc954d9166da0e6a11749cf5f97efc51ea73e49b220b2062f8b"
+    "series.json": "7b48e1d8126b3c37a27eb167cdeebc00ca1d5a2c8f955e9362120dbedd84b926"
   },
   "diagnostic_version": 1,
   "native": {
@@ -65,5 +65,5 @@
     }
   },
   "schema": 2,
-  "test_case_version": 1
+  "test_case_version": 2
 }

packages/climate-ref-esmvaltool/tests/test-data/sea-ice-area-basic/cmip6/regression/series.json

@@ -32,6 +32,7 @@
       12
     ],
     "index_name": "month_number",
+    "kind": "reference",
     "values": [
       12.79599,
       13.63637,
@@ -113,6 +114,7 @@
       "2014-09-16T00:00:00"
     ],
     "index_name": "time",
+    "kind": "reference",
     "values": [
       6.301603,
       null,
@@ -193,6 +195,7 @@
       12
     ],
     "index_name": "month_number",
+    "kind": "reference",
     "values": [
       3.640914,
       2.252787,
@@ -282,6 +285,7 @@
       "2014-02-15T00:00:00"
     ],
     "index_name": "time",
+    "kind": "reference",
     "values": [
       2.269726,
       null,

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

@@ -3,10 +3,67 @@
   "committed": {
     "diagnostic.json": "183d82f3963ad19b5a556b8025e6990c444f292adda1d464e12136d05a5ef3b3",
     "output.json": "ece9f19183b1bede25cda85779d3eb905f51bc24615559dbcc2ac6688835cd92",
-    "series.json": "1535dab04428841a3ac32a30acaa7c78ce57d8035cd3671518c01ab1db9e52eb"
+    "series.json": "19a25697156765ef8707c5c28123bd22026c723faa38c998a94d8875f1e283c4"
   },
   "diagnostic_version": 1,
-  "native": {},
+  "native": {
+    "diagnostic.json": {
+      "sha256": "e52b1e19e1ed5a2a046bb8aa01c004240305fabfe69c4ffb4e64898b1b6bbb84",
+      "size": 128
+    },
+    "executions/recipe/index.html": {
+      "sha256": "321a97aa277c5da181df94fdc3840adc22ea39b1ce5e43abab25d63f369aca9c",
+      "size": 22118
+    },
+    "executions/recipe/plots/siarea_min/allplots/timeseries_sea_ice_area_nh_sep_ambiguous_dataset_ambiguous_mip_historical_r1i1p1f1.png": {
+      "sha256": "52481441afa31c1a002ab03eb80900405a67a987cad18f1182aaa095d905df3e",
+      "size": 169322
+    },
+    "executions/recipe/plots/siarea_min/allplots/timeseries_sea_ice_area_sh_feb_ambiguous_dataset_ambiguous_mip_historical_r1i1p1f1.png": {
+      "sha256": "52dcecbcc3eb1f3c97500c23f69641c6bcac92e572b5d10ddd14f50762bf19bb",
+      "size": 163218
+    },
+    "executions/recipe/plots/siarea_seas/allplots/annual_cycle_sea_ice_area_nh_ambiguous_dataset_ambiguous_mip_historical_r1i1p1f1.png": {
+      "sha256": "6a2642ed31b15c7e36d98110cc82efc0d45d9196624074ead4524ef6a8fa2017",
+      "size": 140446
+    },
+    "executions/recipe/plots/siarea_seas/allplots/annual_cycle_sea_ice_area_sh_ambiguous_dataset_ambiguous_mip_historical_r1i1p1f1.png": {
+      "sha256": "67c979fb197a047c47e6913cc718ea50933e035d68dbcf1660d061a4b036f4ea",
+      "size": 143298
+    },
+    "executions/recipe/run/siarea_min/allplots/diagnostic_provenance.yml": {
+      "sha256": "b4b29ffbbcba669c0f5db59f5bfccde0efcbdd4bd3b7e6adea0704fd4d49de28",
+      "size": 1716
+    },
+    "executions/recipe/run/siarea_seas/allplots/diagnostic_provenance.yml": {
+      "sha256": "7a5e82c3c81ca78ac651134ee4b75bb1ea102d4fe7fadcfbe8fd733c349c1120",
+      "size": 1696
+    },
+    "executions/recipe/work/siarea_min/allplots/timeseries_sea_ice_area_nh_sep_ambiguous_dataset_ambiguous_mip_historical_r1i1p1f1.nc": {
+      "sha256": "92d341d4800ae75ae226a14ccb79731ce870c2387396f96f9e9c72ab280de3cc",
+      "size": 10269
+    },
+    "executions/recipe/work/siarea_min/allplots/timeseries_sea_ice_area_sh_feb_ambiguous_dataset_ambiguous_mip_historical_r1i1p1f1.nc": {
+      "sha256": "c91af07478699a4a21f83819012f6685b13a01a1bacc70cca7df621da3546065",
+      "size": 10269
+    },
+    "executions/recipe/work/siarea_seas/allplots/annual_cycle_sea_ice_area_nh_ambiguous_dataset_ambiguous_mip_historical_r1i1p1f1.nc": {
+      "sha256": "3b6590bc8c9f0e4f00cd20b112490ada9eaf0aa80e520f73a8547e2a21d8ebb5",
+      "size": 10156
+    },
+    "executions/recipe/work/siarea_seas/allplots/annual_cycle_sea_ice_area_sh_ambiguous_dataset_ambiguous_mip_historical_r1i1p1f1.nc": {
+      "sha256": "510eb6fd6a0cd2735d7df544f704b3f8fde69e7fb4016421811d4fa9b2b58dbb",
+      "size": 10156
+    },
+    "output.json": {
+      "sha256": "451bcae9a54d7d358a750ef4910d33b1d6b68666596e863ecb897dc15ffd45d8",
+      "size": 5266
+    },
+    "series.json": {
+      "sha256": "8592f2df19bee6692dde1e8ee11d113b040766d2e2691da24bd1ba57e5eb1be7",
+      "size": 16724
+    }
+  },
   "schema": 2,
-  "test_case_version": 1
+  "test_case_version": 2
 }

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

@@ -32,6 +32,7 @@
       12
     ],
     "index_name": "month_number",
+    "kind": "reference",
     "values": [
       12.79599,
       13.63637,
@@ -113,6 +114,7 @@
       "2014-09-16T00:00:00"
     ],
     "index_name": "time",
+    "kind": "reference",
     "values": [
       6.301603,
       null,
@@ -193,6 +195,7 @@
       12
     ],
     "index_name": "month_number",
+    "kind": "reference",
     "values": [
       3.640914,
       2.252787,
@@ -282,6 +285,7 @@
       "2014-02-15T00:00:00"
     ],
     "index_name": "time",
+    "kind": "reference",
     "values": [
       2.269726,
       null,