climate-ref-esmvaltool 0.7.0__tar.gz → 0.8.0__tar.gz

{climate_ref_esmvaltool-0.7.0 → climate_ref_esmvaltool-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: climate-ref-esmvaltool
-Version: 0.7.0
+Version: 0.8.0
 Summary: ESMValTool diagnostic provider for the Rapid Evaluation Framework
 Author-email: ESMValTool development team <esmvaltool-dev@listserv.dfn.de>, Jared Lewis <jared.lewis@climate-resource.com>
 License-Expression: Apache-2.0
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.11
 Requires-Dist: climate-ref-core
+Requires-Dist: netcdf4>=1.7.2
 Requires-Dist: pooch>=1.8
 Requires-Dist: pyyaml
 Requires-Dist: xarray>=2023.3.0

{climate_ref_esmvaltool-0.7.0 → climate_ref_esmvaltool-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "climate-ref-esmvaltool"
-version = "0.7.0"
+version = "0.8.0"
 description = "ESMValTool diagnostic provider for the Rapid Evaluation Framework"
 readme = "README.md"
 authors = [
@@ -24,6 +24,7 @@ classifiers = [
 ]
 dependencies = [
     "climate-ref-core",
+    "netcdf4>=1.7.2",
     "pooch >= 1.8",
     "pyyaml",
     "xarray >= 2023.3.0",

{climate_ref_esmvaltool-0.7.0 → climate_ref_esmvaltool-0.8.0}/src/climate_ref_esmvaltool/diagnostics/base.py

@@ -4,6 +4,8 @@ from collections.abc import Iterable
 from pathlib import Path
 from typing import ClassVar
 
+import netCDF4
+import numpy as np
 import pandas
 import xarray as xr
 import yaml
@@ -23,6 +25,18 @@ from climate_ref_esmvaltool.recipe import load_recipe, prepare_climate_data
 from climate_ref_esmvaltool.types import MetricBundleArgs, OutputBundleArgs, Recipe
 
 
+def mask_fillvalues(array: np.ndarray) -> np.ma.MaskedArray:  # type: ignore[type-arg]
+    """Convert netCDF4 fill values in an array to a mask."""
+    # Workaround for https://github.com/pydata/xarray/issues/2742
+    defaults = {np.dtype(k): v for k, v in netCDF4.default_fillvals.items()}
+    return np.ma.masked_equal(array, defaults[array.dtype])  # type: ignore[no-untyped-call,no-any-return]
+
+
+def fillvalues_to_nan(array: np.ndarray) -> np.ndarray:  # type: ignore[type-arg]
+    """Convert netCDF4 fill values in an array to NaN."""
+    return mask_fillvalues(array).filled(np.nan)  # type: ignore[no-untyped-call,no-any-return]
+
+
 class ESMValToolDiagnostic(CommandLineDiagnostic):
     """ESMValTool Diagnostic base class."""
 
@@ -213,7 +227,9 @@ class ESMValToolDiagnostic(CommandLineDiagnostic):
         # Add the plots and data files
         series = []
         plot_suffixes = {".png", ".jpg", ".pdf", ".ps"}
-        for metadata_file in result_dir.glob("run/*/*/diagnostic_provenance.yml"):
+        # Sort metadata files for stable processing
+        metadata_files = sorted(result_dir.glob("run/*/*/diagnostic_provenance.yml"))
+        for metadata_file in metadata_files:
             metadata = yaml.safe_load(metadata_file.read_text(encoding="utf-8"))
             for filename in metadata:
                 caption = metadata[filename].get("caption", "")
@@ -300,6 +316,7 @@ class ESMValToolDiagnostic(CommandLineDiagnostic):
                         attributes[f"value_{attr}"] = dataset[series_def.values_name].attrs[attr]
                     if attr in dataset[series_def.index_name].attrs:
                         attributes[f"index_{attr}"] = dataset[series_def.index_name].attrs[attr]
+                # TODO: Handle masked values in the index
                 index = dataset[series_def.index_name].values.tolist()
                 if hasattr(index[0], "calendar"):
                     attributes["calendar"] = index[0].calendar
@@ -310,7 +327,7 @@ class ESMValToolDiagnostic(CommandLineDiagnostic):
                 series.append(
                     SeriesMetricValue(
                         dimensions={**input_selectors, **series_def.dimensions},
-                        values=dataset[series_def.values_name].values.tolist(),
+                        values=fillvalues_to_nan(dataset[series_def.values_name].values).tolist(),
                         index=index,
                         index_name=series_def.index_name,
                         attributes=attributes,

{climate_ref_esmvaltool-0.7.0 → climate_ref_esmvaltool-0.8.0}/src/climate_ref_esmvaltool/diagnostics/cloud_radiative_effects.py

@@ -61,13 +61,26 @@ class CloudRadiativeEffects(ESMValToolDiagnostic):
     series = tuple(
         SeriesDefinition(
             file_pattern=f"plot_profiles/plot/variable_vs_lat_{var_name}_*.nc",
-            sel={"dim0": 0},  # Select the model and not the observations.
-            dimensions={"statistic": f"{var_name} zonal mean"},
+            sel={"dim0": 0},  # Select the model.
+            dimensions={"variable_id": var_name, "statistic": "zonal mean"},
             values_name=var_name,
             index_name="lat",
             attributes=[],
         )
         for var_name in ["lwcre", "swcre"]
+    ) + tuple(
+        SeriesDefinition(
+            file_pattern=f"plot_profiles/plot/variable_vs_lat_{var_name}_*.nc",
+            sel={"dim0": i},  # Select the observation.
+            dimensions={"variable_id": var_name, "statistic": "zonal mean", "reference_source_id": source_id},
+            values_name=var_name,
+            index_name="lat",
+            attributes=[],
+        )
+        for var_name in ["lwcre", "swcre"]
+        for i, source_id in enumerate(
+            ["CERES-EBAF-Ed4.2", "ESACCI-CLOUD-AVHRR-AMPM-fv3.0", "ISCCP-FH"], start=1
+        )
     )
 
     @staticmethod

{climate_ref_esmvaltool-0.7.0 → climate_ref_esmvaltool-0.8.0}/src/climate_ref_esmvaltool/diagnostics/ecs.py

@@ -14,7 +14,7 @@ from climate_ref_core.diagnostics import DataRequirement
 from climate_ref_core.metric_values.typing import SeriesDefinition
 from climate_ref_core.pycmec.metric import CMECMetric, MetricCV
 from climate_ref_core.pycmec.output import CMECOutput
-from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic
+from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic, fillvalues_to_nan
 from climate_ref_esmvaltool.recipe import dataframe_to_recipe
 from climate_ref_esmvaltool.types import MetricBundleArgs, OutputBundleArgs, Recipe
 
@@ -139,9 +139,9 @@ class EquilibriumClimateSensitivity(ESMValToolDiagnostic):
     ) -> tuple[CMECMetric, CMECOutput]:
         """Format the result."""
         ecs_ds = xarray.open_dataset(result_dir / "work" / "ecs" / "calculate" / "ecs.nc")
-        ecs = float(ecs_ds["ecs"].values[0])
+        ecs = float(fillvalues_to_nan(ecs_ds["ecs"].values)[0])
         lambda_ds = xarray.open_dataset(result_dir / "work" / "ecs" / "calculate" / "lambda.nc")
-        lambda_ = float(lambda_ds["lambda"].values[0])
+        lambda_ = float(fillvalues_to_nan(lambda_ds["lambda"].values)[0])
 
         # Update the diagnostic bundle arguments with the computed diagnostics.
         metric_args[MetricCV.DIMENSIONS.value] = {

{climate_ref_esmvaltool-0.7.0 → climate_ref_esmvaltool-0.8.0}/src/climate_ref_esmvaltool/diagnostics/enso.py

@@ -67,55 +67,75 @@ class ENSOBasicClimatology(ESMValToolDiagnostic):
     series = (
         tuple(
             SeriesDefinition(
-                file_pattern=f"diagnostic_metrics/plot_script/{{source_id}}_eq_{var_name}_bias.nc",
-                dimensions={
-                    "statistic": (
-                        f"zonal bias in the time-mean {var_name} structure across the equatorial Pacific"
-                    ),
-                },
+                file_pattern=f"diagnostic_metrics/plot_script/{source_id}_eq_{var_name}_bias.nc",
+                dimensions=(
+                    {
+                        "statistic": (
+                            f"zonal bias in the time-mean {var_name} structure across the equatorial Pacific"
+                        ),
+                    }
+                    | ({} if source_id == "{source_id}" else {"reference_source_id": source_id})
+                ),
                 values_name="tos" if var_name == "sst" else var_name,
                 index_name="lon",
                 attributes=[],
             )
-            for var_name in ["pr", "sst", "tauu"]
+            for var_name in ("pr", "sst", "tauu")
+            for source_id in ("{source_id}", "GPCP-V2.3", "TROPFLUX")
         )
         + tuple(
             SeriesDefinition(
                 file_pattern=f"diagnostic_metrics/plot_script/{{source_id}}_eq_{var_name}_seacycle.nc",
-                dimensions={
-                    "statistic": (
-                        "zonal bias in the amplitude of the mean seasonal cycle of "
-                        f"{var_name} in the equatorial Pacific"
-                    ),
-                },
+                dimensions=(
+                    {
+                        "statistic": (
+                            "zonal bias in the amplitude of the mean seasonal cycle of "
+                            f"{var_name} in the equatorial Pacific"
+                        ),
+                    }
+                    | ({} if source_id == "{source_id}" else {"reference_source_id": source_id})
+                ),
                 values_name="tos" if var_name == "sst" else var_name,
                 index_name="lon",
                 attributes=[],
             )
-            for var_name in ["pr", "sst", "tauu"]
+            for var_name in ("pr", "sst", "tauu")
+            for source_id in ("{source_id}", "GPCP-V2.3", "TROPFLUX")
         )
-        + (
+        + tuple(
             SeriesDefinition(
                 file_pattern="diagnostic_metrics/plot_script/{source_id}_pr_double.nc",
-                dimensions={
-                    "statistic": ("meridional bias in the time-mean pr structure across the eastern Pacific"),
-                },
+                dimensions=(
+                    {
+                        "statistic": (
+                            "meridional bias in the time-mean pr structure across the eastern Pacific"
+                        ),
+                    }
+                    | ({} if source_id == "{source_id}" else {"reference_source_id": source_id})
+                ),
                 values_name="pr",
                 index_name="lat",
                 attributes=[],
-            ),
+            )
+            for source_id in ("{source_id}", "GPCP-V2.3")
+        )
+        + tuple(
             SeriesDefinition(
                 file_pattern="diagnostic_metrics/plot_script/*_pr_double_seacycle.nc",
-                dimensions={
-                    "statistic": (
-                        "meridional bias in the amplitude of the mean seasonal "
-                        "pr cycle in the eastern Pacific"
-                    ),
-                },
+                dimensions=(
+                    {
+                        "statistic": (
+                            "meridional bias in the amplitude of the mean seasonal "
+                            "pr cycle in the eastern Pacific"
+                        ),
+                    }
+                    | ({} if source_id == "{source_id}" else {"reference_source_id": source_id})
+                ),
                 values_name="pr",
                 index_name="lat",
                 attributes=[],
-            ),
+            )
+            for source_id in ("{source_id}", "GPCP-V2.3")
         )
     )
 

{climate_ref_esmvaltool-0.7.0 → climate_ref_esmvaltool-0.8.0}/src/climate_ref_esmvaltool/diagnostics/regional_historical_changes.py

@@ -16,7 +16,7 @@ from climate_ref_core.diagnostics import DataRequirement
 from climate_ref_core.metric_values.typing import SeriesDefinition
 from climate_ref_core.pycmec.metric import CMECMetric, MetricCV
 from climate_ref_core.pycmec.output import CMECOutput
-from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic
+from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic, fillvalues_to_nan
 from climate_ref_esmvaltool.recipe import dataframe_to_recipe
 from climate_ref_esmvaltool.types import MetricBundleArgs, OutputBundleArgs, Recipe
 
@@ -87,6 +87,15 @@ def normalize_region(region: str) -> str:
     return region.replace("&", "-and-").replace("/", "-and-")
 
 
+REFERENCE_DATASETS = {
+    "hus": "ERA-5",
+    "pr": "GPCP-V2.3",
+    "psl": "ERA-5",
+    "tas": "HadCRUT5-5.0.1.0-analysis",
+    "ua": "ERA-5",
+}
+
+
 class RegionalHistoricalAnnualCycle(ESMValToolDiagnostic):
     """
     Plot regional historical annual cycle of climate variables.
@@ -166,13 +175,21 @@ class RegionalHistoricalAnnualCycle(ESMValToolDiagnostic):
         SeriesDefinition(
             file_pattern=f"anncyc-{region}/allplots/*_{var_name}_*.nc",
             sel={"dim0": 0},  # Select the model and not the observation.
-            dimensions={"region": region, "statistic": f"{var_name} regional mean"},
+            dimensions=(
+                {
+                    "region": region,
+                    "variable_id": var_name,
+                    "statistic": "mean",
+                }
+                | ({} if i == 0 else {"reference_source_id": REFERENCE_DATASETS[var_name]})
+            ),
             values_name=var_name,
             index_name="month_number",
             attributes=[],
         )
         for var_name in variables
         for region in REGIONS
+        for i in range(2)
     )
 
     @staticmethod
@@ -292,15 +309,15 @@ class RegionalHistoricalTimeSeries(RegionalHistoricalAnnualCycle):
     series = tuple(
         SeriesDefinition(
             file_pattern=f"{diagnostic}-{region}/allplots/*_{var_name}_*.nc",
-            sel={"dim0": 0},  # Select the model and not the observation.
-            dimensions={
-                "region": region,
-                "statistic": (
-                    f"{var_name} regional mean"
-                    if diagnostic == "timeseries_abs"
-                    else f"{var_name} regional mean anomaly"
-                ),
-            },
+            sel={"dim0": i},
+            dimensions=(
+                {
+                    "region": region,
+                    "variable_id": var_name,
+                    "statistic": ("mean" if diagnostic == "timeseries_abs" else "mean anomaly"),
+                }
+                | ({} if i == 0 else {"reference_source_id": REFERENCE_DATASETS[var_name]})
+            ),
             values_name=var_name,
             index_name="time",
             attributes=[],
@@ -308,6 +325,7 @@ class RegionalHistoricalTimeSeries(RegionalHistoricalAnnualCycle):
         for var_name in variables
         for region in REGIONS
         for diagnostic in ["timeseries_abs", "timeseries"]
+        for i in range(2)
     )
 
 
@@ -425,7 +443,9 @@ class RegionalHistoricalTrend(ESMValToolDiagnostic):
             variable_id = next(iter(ds.data_vars.keys()))
             metric_args[MetricCV.DIMENSIONS.value]["variable_id"][variable_id] = {}
             metric_args[MetricCV.RESULTS.value][variable_id] = {}
-            for region_value, trend_value in zip(ds.shape_id.astype(str).values, ds[variable_id].values):
+            for region_value, trend_value in zip(
+                ds.shape_id.astype(str).values, fillvalues_to_nan(ds[variable_id].values)
+            ):
                 region = region_value.strip()
                 trend = float(trend_value)
                 if region not in metric_args[MetricCV.DIMENSIONS.value]["region"]:

{climate_ref_esmvaltool-0.7.0 → climate_ref_esmvaltool-0.8.0}/src/climate_ref_esmvaltool/diagnostics/sea_ice_area_basic.py

@@ -13,6 +13,16 @@ from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic
 from climate_ref_esmvaltool.recipe import dataframe_to_recipe
 from climate_ref_esmvaltool.types import Recipe
 
+REGIONS = {
+    "nh": "Northern Hemisphere",
+    "sh": "Southern Hemisphere",
+}
+
+MONTHS = {
+    "nh": "September",
+    "sh": "February",
+}
+
 
 class SeaIceAreaBasic(ESMValToolDiagnostic):
     """
@@ -49,51 +59,40 @@ class SeaIceAreaBasic(ESMValToolDiagnostic):
         # TODO: Use OSI-450-nh and OSI-450-sh from obs4MIPs once available.
     )
     facets = ()
-    series = (
+    series = tuple(
         SeriesDefinition(
-            file_pattern="siarea_min/allplots/timeseries_sea_ice_area_nh_*.nc",
-            sel={"dim0": 0},  # Select the model and not the observations.
-            dimensions={
-                "region": "Northern Hemisphere",
-                "statistic": "September sea ice area",
-            },
-            values_name="siconc",
-            index_name="time",
-            attributes=[],
-        ),
-        SeriesDefinition(
-            file_pattern="siarea_min/allplots/timeseries_sea_ice_area_sh_*.nc",
-            sel={"dim0": 0},  # Select the model and not the observations.
-            dimensions={
-                "region": "Southern Hemisphere",
-                "statistic": "February sea ice area",
-            },
+            file_pattern=f"siarea_min/allplots/timeseries_sea_ice_area_{region}_*.nc",
+            sel={"dim0": i},
+            dimensions=(
+                {
+                    "region": REGIONS[region],
+                    "statistic": f"{MONTHS[region]} sea ice area",
+                }
+                | ({} if i == 0 else {"reference_source_id": f"OSI-450-{region}"})
+            ),
             values_name="siconc",
             index_name="time",
             attributes=[],
-        ),
+        )
+        for region in REGIONS
+        for i in range(2)
+    ) + tuple(
         SeriesDefinition(
-            file_pattern="siarea_seas/allplots/annual_cycle_sea_ice_area_nh_*.nc",
-            sel={"dim0": 0},  # Select the model and not the observations.
-            dimensions={
-                "region": "Northern Hemisphere",
-                "statistic": "20-year average seasonal cycle of the sea ice area",
-            },
-            values_name="siconc",
-            index_name="month_number",
-            attributes=[],
-        ),
-        SeriesDefinition(
-            file_pattern="siarea_seas/allplots/annual_cycle_sea_ice_area_sh_*.nc",
-            sel={"dim0": 0},  # Select the model and not the observations.
-            dimensions={
-                "region": "Southern Hemisphere",
-                "statistic": "20-year average seasonal cycle of the sea ice area,",
-            },
+            file_pattern=f"siarea_seas/allplots/annual_cycle_sea_ice_area_{region}_*.nc",
+            sel={"dim0": i},
+            dimensions=(
+                {
+                    "region": REGIONS[region],
+                    "statistic": "20-year average seasonal cycle of the sea ice area",
+                }
+                | ({} if i == 0 else {"reference_source_id": f"OSI-450-{region}"})
+            ),
             values_name="siconc",
             index_name="month_number",
             attributes=[],
-        ),
+        )
+        for region in REGIONS
+        for i in range(2)
     )
 
     @staticmethod

{climate_ref_esmvaltool-0.7.0 → climate_ref_esmvaltool-0.8.0}/src/climate_ref_esmvaltool/diagnostics/tcr.py

@@ -14,7 +14,7 @@ from climate_ref_core.diagnostics import DataRequirement
 from climate_ref_core.metric_values.typing import SeriesDefinition
 from climate_ref_core.pycmec.metric import CMECMetric, MetricCV
 from climate_ref_core.pycmec.output import CMECOutput
-from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic
+from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic, fillvalues_to_nan
 from climate_ref_esmvaltool.recipe import dataframe_to_recipe
 from climate_ref_esmvaltool.types import MetricBundleArgs, OutputBundleArgs, Recipe
 
@@ -117,7 +117,7 @@ class TransientClimateResponse(ESMValToolDiagnostic):
     ) -> tuple[CMECMetric, CMECOutput]:
         """Format the result."""
         tcr_ds = xarray.open_dataset(result_dir / "work" / "tcr" / "calculate" / "tcr.nc")
-        tcr = float(tcr_ds["tcr"].values[0])
+        tcr = float(fillvalues_to_nan(tcr_ds["tcr"].values)[0])
 
         # Update the diagnostic bundle arguments with the computed diagnostics.
         metric_args[MetricCV.DIMENSIONS.value] = {

{climate_ref_esmvaltool-0.7.0 → climate_ref_esmvaltool-0.8.0}/src/climate_ref_esmvaltool/diagnostics/tcre.py

@@ -13,7 +13,7 @@ from climate_ref_core.datasets import ExecutionDatasetCollection, FacetFilter, S
 from climate_ref_core.diagnostics import DataRequirement
 from climate_ref_core.pycmec.metric import CMECMetric, MetricCV
 from climate_ref_core.pycmec.output import CMECOutput
-from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic
+from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic, fillvalues_to_nan
 from climate_ref_esmvaltool.recipe import dataframe_to_recipe
 from climate_ref_esmvaltool.types import MetricBundleArgs, OutputBundleArgs, Recipe
 
@@ -123,7 +123,7 @@ class TransientClimateResponseEmissions(ESMValToolDiagnostic):
     ) -> tuple[CMECMetric, CMECOutput]:
         """Format the result."""
         tcre_ds = xarray.open_dataset(result_dir / "work" / "tcre" / "calculate_tcre" / "tcre.nc")
-        tcre = float(tcre_ds["tcre"].values[0])
+        tcre = float(fillvalues_to_nan(tcre_ds["tcre"].values)[0])
 
         # Update the diagnostic bundle arguments with the computed diagnostics.
         metric_args[MetricCV.DIMENSIONS.value] = {

{climate_ref_esmvaltool-0.7.0 → climate_ref_esmvaltool-0.8.0}/src/climate_ref_esmvaltool/diagnostics/zec.py

@@ -14,7 +14,7 @@ from climate_ref_core.diagnostics import DataRequirement
 from climate_ref_core.metric_values.typing import SeriesDefinition
 from climate_ref_core.pycmec.metric import CMECMetric, MetricCV
 from climate_ref_core.pycmec.output import CMECOutput
-from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic
+from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic, fillvalues_to_nan
 from climate_ref_esmvaltool.recipe import dataframe_to_recipe
 from climate_ref_esmvaltool.types import MetricBundleArgs, OutputBundleArgs, Recipe
 
@@ -104,7 +104,7 @@ class ZeroEmissionCommitment(ESMValToolDiagnostic):
     ) -> tuple[CMECMetric, CMECOutput]:
         """Format the result."""
         zec_ds = xarray.open_dataset(result_dir / "work" / "zec" / "zec" / "zec_50.nc")
-        zec = float(zec_ds["zec"].values[0])
+        zec = float(fillvalues_to_nan(zec_ds["zec"].values)[0])
 
         # Update the diagnostic bundle arguments with the computed diagnostics.
         metric_args[MetricCV.DIMENSIONS.value] = {