climate-ref-esmvaltool 0.5.0__py3-none-any.whl

climate_ref_esmvaltool/diagnostics/sea_ice_area_seasonal_cycle.py

@@ -0,0 +1,78 @@
+import pandas
+
+from climate_ref_core.constraints import (
+    AddSupplementaryDataset,
+    RequireContiguousTimerange,
+)
+from climate_ref_core.datasets import FacetFilter, SourceDatasetType
+from climate_ref_core.diagnostics import DataRequirement
+from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic
+from climate_ref_esmvaltool.recipe import dataframe_to_recipe
+from climate_ref_esmvaltool.types import Recipe
+
+
+class SeaIceAreaSeasonalCycle(ESMValToolDiagnostic):
+    """
+    Calculate seasonal cycle and time series of NH and SH sea ice area.
+    """
+
+    name = "Sea ice area seasonal cycle"
+    slug = "sea-ice-area-seasonal-cycle"
+    base_recipe = "ref/recipe_ref_sea_ice_area_basic.yml"
+
+    data_requirements = (
+        DataRequirement(
+            source_type=SourceDatasetType.CMIP6,
+            filters=(
+                FacetFilter(
+                    facets={
+                        "variable_id": "siconc",
+                        "experiment_id": "historical",
+                    },
+                ),
+            ),
+            group_by=("instance_id",),
+            constraints=(
+                RequireContiguousTimerange(group_by=("instance_id",)),
+                AddSupplementaryDataset.from_defaults("areacello", SourceDatasetType.CMIP6),
+            ),
+        ),
+        # TODO: Use OSI-450-nh and OSI-450-sh from obs4MIPs once available.
+    )
+    facets = ("model", "metric")
+
+    @staticmethod
+    def update_recipe(recipe: Recipe, input_files: pandas.DataFrame) -> None:
+        """Update the recipe."""
+        # Overlap between observations and historical experiment.
+        timerange = "1995/2014"
+
+        # Update datasets
+        recipe_variables = dataframe_to_recipe(input_files)
+        recipe["datasets"] = recipe_variables["siconc"]["additional_datasets"]
+        for dataset in recipe["datasets"]:
+            dataset["timerange"] = timerange
+
+        # Update observational datasets
+        nh_obs = {
+            "dataset": "OSI-450-nh",
+            "mip": "OImon",
+            "project": "OBS",
+            "supplementary_variables": [
+                {
+                    "short_name": "areacello",
+                    "mip": "fx",
+                },
+            ],
+            "tier": 2,
+            "timerange": timerange,
+            "type": "reanaly",
+            "version": "v3",
+        }
+        sh_obs = nh_obs.copy()
+        sh_obs["dataset"] = "OSI-450-sh"
+        diagnostics = recipe["diagnostics"]
+        diagnostics["siarea_min"]["variables"]["sea_ice_area_nh_sep"]["additional_datasets"] = [nh_obs]
+        diagnostics["siarea_min"]["variables"]["sea_ice_area_sh_feb"]["additional_datasets"] = [sh_obs]
+        diagnostics["siarea_seas"]["variables"]["sea_ice_area_nh"]["additional_datasets"] = [nh_obs]
+        diagnostics["siarea_seas"]["variables"]["sea_ice_area_sh"]["additional_datasets"] = [sh_obs]

climate_ref_esmvaltool/diagnostics/tcr.py

@@ -0,0 +1,130 @@
+from pathlib import Path
+
+import pandas
+import xarray
+
+from climate_ref_core.constraints import (
+    AddSupplementaryDataset,
+    RequireContiguousTimerange,
+    RequireFacets,
+    RequireOverlappingTimerange,
+)
+from climate_ref_core.datasets import ExecutionDatasetCollection, FacetFilter, SourceDatasetType
+from climate_ref_core.diagnostics import DataRequirement
+from climate_ref_core.pycmec.metric import MetricCV
+from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic
+from climate_ref_esmvaltool.recipe import dataframe_to_recipe
+from climate_ref_esmvaltool.types import MetricBundleArgs, OutputBundleArgs, Recipe
+
+
+class TransientClimateResponse(ESMValToolDiagnostic):
+    """
+    Calculate the global mean transient climate response for a dataset.
+    """
+
+    name = "Transient Climate Response"
+    slug = "transient-climate-response"
+    base_recipe = "recipe_tcr.yml"
+
+    experiments = (
+        "1pctCO2",
+        "piControl",
+    )
+    data_requirements = (
+        DataRequirement(
+            source_type=SourceDatasetType.CMIP6,
+            filters=(
+                FacetFilter(
+                    facets={
+                        "variable_id": ("tas",),
+                        "experiment_id": experiments,
+                    },
+                ),
+            ),
+            group_by=("source_id", "member_id", "grid_label"),
+            constraints=(
+                RequireFacets("experiment_id", experiments),
+                RequireContiguousTimerange(group_by=("instance_id",)),
+                RequireOverlappingTimerange(group_by=("instance_id",)),
+                AddSupplementaryDataset.from_defaults("areacella", SourceDatasetType.CMIP6),
+            ),
+        ),
+    )
+    facets = ("source_id", "region", "metric")
+
+    @staticmethod
+    def update_recipe(recipe: Recipe, input_files: pandas.DataFrame) -> None:
+        """Update the recipe."""
+        # Only run the diagnostic that computes TCR for a single model.
+        recipe["diagnostics"] = {
+            "cmip6": {
+                "description": "Calculate TCR.",
+                "variables": {
+                    "tas": {
+                        "preprocessor": "spatial_mean",
+                    },
+                },
+                "scripts": {
+                    "tcr": {
+                        "script": "climate_metrics/tcr.py",
+                        "calculate_mmm": False,
+                    },
+                },
+            },
+        }
+
+        # Prepare updated datasets section in recipe. It contains two
+        # datasets, one for the "1pctCO2" and one for the "piControl"
+        # experiment.
+        recipe_variables = dataframe_to_recipe(input_files)
+        recipe_variables = {k: v for k, v in recipe_variables.items() if k != "areacella"}
+
+        # Select a timerange covered by all datasets.
+        start_times, end_times = [], []
+        for variable in recipe_variables.values():
+            for dataset in variable["additional_datasets"]:
+                start, end = dataset["timerange"].split("/")
+                start_times.append(start)
+                end_times.append(end)
+        timerange = f"{max(start_times)}/{min(end_times)}"
+
+        datasets = recipe_variables["tas"]["additional_datasets"]
+        for dataset in datasets:
+            dataset["timerange"] = timerange
+
+        recipe["datasets"] = datasets
+
+    @staticmethod
+    def format_result(
+        result_dir: Path,
+        execution_dataset: ExecutionDatasetCollection,
+        metric_args: MetricBundleArgs,
+        output_args: OutputBundleArgs,
+    ) -> tuple[MetricBundleArgs, OutputBundleArgs]:
+        """Format the result."""
+        input_files = next(c.datasets for _, c in execution_dataset.items())
+        source_id = input_files.iloc[0].source_id
+
+        tcr_ds = xarray.open_dataset(result_dir / "work" / "cmip6" / "tcr" / "tcr.nc")
+        tcr = float(tcr_ds["tcr"].values[0])
+
+        # Update the diagnostic bundle arguments with the computed diagnostics.
+        metric_args[MetricCV.DIMENSIONS.value] = {
+            "json_structure": [
+                "source_id",
+                "region",
+                "metric",
+            ],
+            "source_id": {source_id: {}},
+            "region": {"global": {}},
+            "metric": {"tcr": {}},
+        }
+        metric_args[MetricCV.RESULTS.value] = {
+            source_id: {
+                "global": {
+                    "tcr": tcr,
+                },
+            },
+        }
+
+        return metric_args, output_args

climate_ref_esmvaltool/diagnostics/tcre.py

@@ -0,0 +1,136 @@
+from pathlib import Path
+
+import pandas
+import xarray
+
+from climate_ref_core.constraints import (
+    AddSupplementaryDataset,
+    RequireContiguousTimerange,
+    RequireFacets,
+    RequireOverlappingTimerange,
+)
+from climate_ref_core.datasets import ExecutionDatasetCollection, FacetFilter, SourceDatasetType
+from climate_ref_core.diagnostics import DataRequirement
+from climate_ref_core.pycmec.metric import MetricCV
+from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic
+from climate_ref_esmvaltool.recipe import dataframe_to_recipe
+from climate_ref_esmvaltool.types import MetricBundleArgs, OutputBundleArgs, Recipe
+
+
+class TransientClimateResponseEmissions(ESMValToolDiagnostic):
+    """
+    Calculate the global mean Transient Climate Response to Cumulative CO2 Emissions.
+    """
+
+    name = "Transient Climate Response to Cumulative CO2 Emissions"
+    slug = "transient-climate-response-emissions"
+    base_recipe = "recipe_tcre.yml"
+
+    experiments = (
+        "esm-1pctCO2",
+        "esm-piControl",
+    )
+    variables = (
+        "tas",
+        "fco2antt",
+    )
+    data_requirements = (
+        DataRequirement(
+            source_type=SourceDatasetType.CMIP6,
+            filters=(
+                FacetFilter(
+                    facets={
+                        "variable_id": variables,
+                        "frequency": "mon",
+                        "experiment_id": experiments,
+                    },
+                ),
+                FacetFilter(
+                    facets={
+                        "variable_id": "fco2antt",
+                        "experiment_id": "esm-piControl",
+                    },
+                    keep=False,
+                ),
+            ),
+            group_by=("source_id", "member_id", "grid_label"),
+            constraints=(
+                RequireFacets("experiment_id", experiments),
+                RequireFacets("variable_id", variables),
+                RequireContiguousTimerange(group_by=("instance_id",)),
+                RequireOverlappingTimerange(group_by=("instance_id",)),
+                AddSupplementaryDataset.from_defaults("areacella", SourceDatasetType.CMIP6),
+            ),
+        ),
+    )
+    facets = ("source_id", "region", "metric")
+
+    @staticmethod
+    def update_recipe(recipe: Recipe, input_files: pandas.DataFrame) -> None:
+        """Update the recipe."""
+        # Prepare updated datasets section in recipe. It contains three
+        # datasets, "tas" and "fco2antt" for the "esm-1pctCO2" and just "tas"
+        # for the "esm-piControl" experiment.
+        recipe_variables = dataframe_to_recipe(input_files)
+        tas_esm_1pctCO2 = next(
+            ds for ds in recipe_variables["tas"]["additional_datasets"] if ds["exp"] == "esm-1pctCO2"
+        )
+        fco2antt_esm_1pctCO2 = next(
+            ds for ds in recipe_variables["fco2antt"]["additional_datasets"] if ds["exp"] == "esm-1pctCO2"
+        )
+        tas_esm_piControl = next(
+            ds for ds in recipe_variables["tas"]["additional_datasets"] if ds["exp"] == "esm-piControl"
+        )
+        tas_esm_piControl["timerange"] = tas_esm_1pctCO2["timerange"]
+
+        recipe["diagnostics"]["tcre"]["variables"] = {
+            "tas_esm-1pctCO2": {
+                "short_name": "tas",
+                "preprocessor": "global_annual_mean_anomaly",
+                "additional_datasets": [tas_esm_1pctCO2],
+            },
+            "tas_esm-piControl": {
+                "short_name": "tas",
+                "preprocessor": "global_annual_mean_anomaly",
+                "additional_datasets": [tas_esm_piControl],
+            },
+            "fco2antt": {
+                "preprocessor": "global_cumulative_sum",
+                "additional_datasets": [fco2antt_esm_1pctCO2],
+            },
+        }
+        recipe["diagnostics"].pop("barplot")
+
+    @staticmethod
+    def format_result(
+        result_dir: Path,
+        execution_dataset: ExecutionDatasetCollection,
+        metric_args: MetricBundleArgs,
+        output_args: OutputBundleArgs,
+    ) -> tuple[MetricBundleArgs, OutputBundleArgs]:
+        """Format the result."""
+        input_files = next(c.datasets for _, c in execution_dataset.items())
+        source_id = input_files.iloc[0].source_id
+
+        tcre_ds = xarray.open_dataset(result_dir / "work" / "tcre" / "calculate_tcre" / "tcre.nc")
+        tcre = float(tcre_ds["tcre"].values[0])
+
+        # Update the diagnostic bundle arguments with the computed diagnostics.
+        metric_args[MetricCV.DIMENSIONS.value] = {
+            "json_structure": [
+                "source_id",
+                "region",
+                "metric",
+            ],
+            "source_id": {source_id: {}},
+            "region": {"global": {}},
+            "metric": {"tcre": {}},
+        }
+        metric_args[MetricCV.RESULTS.value] = {
+            source_id: {
+                "global": {
+                    "tcre": tcre,
+                },
+            },
+        }
+        return metric_args, output_args

climate_ref_esmvaltool/diagnostics/zec.py

@@ -0,0 +1,109 @@
+from pathlib import Path
+
+import pandas
+import xarray
+
+from climate_ref_core.constraints import (
+    AddSupplementaryDataset,
+    RequireContiguousTimerange,
+    RequireFacets,
+    RequireOverlappingTimerange,
+)
+from climate_ref_core.datasets import ExecutionDatasetCollection, FacetFilter, SourceDatasetType
+from climate_ref_core.diagnostics import DataRequirement
+from climate_ref_core.pycmec.metric import MetricCV
+from climate_ref_esmvaltool.diagnostics.base import ESMValToolDiagnostic
+from climate_ref_esmvaltool.recipe import dataframe_to_recipe
+from climate_ref_esmvaltool.types import MetricBundleArgs, OutputBundleArgs, Recipe
+
+
+class ZeroEmissionCommitment(ESMValToolDiagnostic):
+    """
+    Calculate the global mean Zero Emission Commitment (ZEC) temperature.
+    """
+
+    name = "Zero Emission Commitment"
+    slug = "zero-emission-commitment"
+    base_recipe = "recipe_zec.yml"
+
+    experiments = (
+        "1pctCO2",
+        "esm-1pct-brch-1000PgC",
+    )
+    data_requirements = (
+        DataRequirement(
+            source_type=SourceDatasetType.CMIP6,
+            filters=(
+                FacetFilter(
+                    facets={
+                        "variable_id": ("tas",),
+                        "experiment_id": experiments,
+                    },
+                ),
+            ),
+            group_by=("source_id", "member_id", "grid_label"),
+            constraints=(
+                RequireFacets("experiment_id", experiments),
+                RequireContiguousTimerange(group_by=("instance_id",)),
+                RequireOverlappingTimerange(group_by=("instance_id",)),
+                AddSupplementaryDataset.from_defaults("areacella", SourceDatasetType.CMIP6),
+            ),
+        ),
+    )
+    facets = ("source_id", "region", "metric")
+
+    @staticmethod
+    def update_recipe(recipe: Recipe, input_files: pandas.DataFrame) -> None:
+        """Update the recipe."""
+        # Prepare updated datasets section in recipe. It contains two
+        # datasets, one for the "esm-1pct-brch-1000PgC" and one for the "piControl"
+        # experiment.
+        datasets = dataframe_to_recipe(input_files)["tas"]["additional_datasets"]
+        base_dataset = next(ds for ds in datasets if ds["exp"] == "1pctCO2")
+        dataset = next(ds for ds in datasets if ds["exp"] == "esm-1pct-brch-1000PgC")
+        start = dataset["timerange"].split("/")[0]
+        base_start = f"{int(start[:4]) - 10:04d}{start[4:]}"
+        base_end = f"{int(start[:4]) + 10:04d}{start[4:]}"
+        base_dataset["timerange"] = f"{base_start}/{base_end}"
+        variables = recipe["diagnostics"]["zec"]["variables"]
+        variables["tas_base"] = {
+            "short_name": "tas",
+            "preprocessor": "anomaly_base",
+            "additional_datasets": [base_dataset],
+        }
+        variables["tas"] = {
+            "preprocessor": "spatial_mean",
+            "additional_datasets": [dataset],
+        }
+
+    @classmethod
+    def format_result(
+        cls,
+        result_dir: Path,
+        execution_dataset: ExecutionDatasetCollection,
+        metric_args: MetricBundleArgs,
+        output_args: OutputBundleArgs,
+    ) -> tuple[MetricBundleArgs, OutputBundleArgs]:
+        """Format the result."""
+        input_files = next(c.datasets for _, c in execution_dataset.items())
+        source_id = input_files.iloc[0].source_id
+
+        zec_ds = xarray.open_dataset(result_dir / "work" / "zec" / "zec" / "zec_50.nc")
+        zec = float(zec_ds["zec"].values[0])
+
+        # Update the diagnostic bundle arguments with the computed diagnostics.
+        metric_args[MetricCV.DIMENSIONS.value] = {
+            "json_structure": cls.facets,
+            "source_id": {source_id: {}},
+            "region": {"global": {}},
+            "metric": {"zec": {}},
+        }
+        metric_args[MetricCV.RESULTS.value] = {
+            source_id: {
+                "global": {
+                    "zec": zec,
+                },
+            },
+        }
+
+        return metric_args, output_args

climate_ref_esmvaltool/recipe.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import pooch
+from ruamel.yaml import YAML
+
+from climate_ref_esmvaltool.types import Recipe
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+yaml = YAML()
+
+FACETS = {
+    "CMIP6": {
+        "activity": "activity_id",
+        "dataset": "source_id",
+        "ensemble": "member_id",
+        "institute": "institution_id",
+        "exp": "experiment_id",
+        "grid": "grid_label",
+        "mip": "table_id",
+        "short_name": "variable_id",
+    },
+}
+
+
+def as_isodate(timestamp: pd.Timestamp) -> str:
+    """Format a timestamp as an ISO 8601 datetime.
+
+    For example, '2014-12-16 12:00:00' will be formatted as '20141216T120000'.
+
+    Parameters
+    ----------
+    timestamp
+        The timestamp to format.
+
+    """
+    return str(timestamp).replace(" ", "T").replace("-", "").replace(":", "")
+
+
+def as_timerange(group: pd.DataFrame) -> str | None:
+    """Format the timeranges from a dataframe as an ESMValTool timerange.
+
+    Parameters
+    ----------
+    group
+        The dataframe describing a single dataset.
+
+    Returns
+    -------
+        A timerange.
+    """
+    # TODO: apply some rounding to avoid problems?
+    # https://github.com/ESMValGroup/ESMValCore/issues/2048
+    start_times = group.start_time.dropna()
+    if start_times.empty:
+        return None
+    end_times = group.end_time.dropna()
+    if end_times.empty:
+        return None  # pragma: no cover
+    return f"{as_isodate(start_times.min())}/{as_isodate(end_times.max())}"
+
+
+def as_facets(
+    group: pd.DataFrame,
+) -> dict[str, Any]:
+    """Convert a group from the datasets dataframe to ESMValTool facets.
+
+    Parameters
+    ----------
+    group:
+        A group of datasets representing a single instance_id.
+
+    Returns
+    -------
+        A :obj:`dict` containing facet-value pairs.
+
+    """
+    facets = {}
+    first_row = group.iloc[0]
+    project = first_row.instance_id.split(".", 2)[0]
+    facets["project"] = project
+    for esmvaltool_name, ref_name in FACETS[project].items():
+        facets[esmvaltool_name] = getattr(first_row, ref_name)
+    timerange = as_timerange(group)
+    if timerange is not None:
+        facets["timerange"] = timerange
+    return facets
+
+
+def dataframe_to_recipe(files: pd.DataFrame) -> dict[str, Any]:
+    """Convert the datasets dataframe to a recipe "variables" section.
+
+    Parameters
+    ----------
+    files
+        The pandas dataframe describing the input files.
+
+    Returns
+    -------
+        A "variables" section that can be used in an ESMValTool recipe.
+    """
+    variables: dict[str, Any] = {}
+    # TODO: refine to make it possible to combine historical and scenario runs.
+    for _, group in files.groupby("instance_id"):
+        facets = as_facets(group)
+        short_name = facets.pop("short_name")
+        if short_name not in variables:
+            variables[short_name] = {"additional_datasets": []}
+        variables[short_name]["additional_datasets"].append(facets)
+    return variables
+
+
+_ESMVALTOOL_COMMIT = "a759ce46d5185e3784997ce38a3956e39322cdac"
+_ESMVALTOOL_VERSION = f"2.13.0.dev27+g{_ESMVALTOOL_COMMIT[:9]}"
+
+_RECIPES = pooch.create(
+    path=pooch.os_cache("climate_ref_esmvaltool"),
+    # TODO: use a released version
+    # base_url="https://raw.githubusercontent.com/ESMValGroup/ESMValTool/refs/tags/v{version}/esmvaltool/recipes/",
+    # version=_ESMVALTOOL_VERSION,
+    base_url=f"https://raw.githubusercontent.com/ESMValGroup/ESMValTool/{_ESMVALTOOL_COMMIT}/esmvaltool/recipes/",
+    env="REF_METRICS_ESMVALTOOL_DATA_DIR",
+)
+_RECIPES.load_registry(str(importlib.resources.files("climate_ref_esmvaltool").joinpath("recipes.txt")))
+
+
+def load_recipe(recipe: str) -> Recipe:
+    """Load a recipe.
+
+    Parameters
+    ----------
+    recipe
+        The name of an ESMValTool recipe.
+
+    Returns
+    -------
+        The loaded recipe.
+    """
+    filename = _RECIPES.fetch(recipe)
+    return yaml.load(Path(filename).read_text(encoding="utf-8"))  # type: ignore[no-any-return]
+
+
+def prepare_climate_data(datasets: pd.DataFrame, climate_data_dir: Path) -> None:
+    """Symlink the input files from the Pandas dataframe into a directory tree.
+
+    This ensures that ESMValTool can find the data and only uses the
+    requested data.
+
+    Parameters
+    ----------
+    datasets
+        The pandas dataframe describing the input datasets.
+    climate_data_dir
+        The directory where ESMValTool should look for input data.
+    """
+    for row in datasets.itertuples():
+        if not isinstance(row.instance_id, str):  # pragma: no branch
+            msg = f"Invalid instance_id encountered in {row}"
+            raise ValueError(msg)
+        if not isinstance(row.path, str):  # pragma: no branch
+            msg = f"Invalid path encountered in {row}"
+            raise ValueError(msg)
+        tgt = climate_data_dir.joinpath(*row.instance_id.split(".")) / Path(row.path).name
+        tgt.parent.mkdir(parents=True, exist_ok=True)
+        tgt.symlink_to(row.path)

climate_ref_esmvaltool/recipes.txt

@@ -0,0 +1,7 @@
+examples/recipe_python.yml ab3f06d269bb2c1368f4dc39da9bcb232fb2adb1fa556ba769e6c16294ffb4a3
+recipe_calculate_gwl_exceedance_stats.yml 5aa266abc9a8029649b689a2b369a47623b0935d609354332ff4148994642d6b
+recipe_ecs.yml             0cc57034fcb64e32015b4ff949ece5df8cdb8c6f493618b50ceded119fb37918
+recipe_tcr.yml             35f9ef035a4e71aff5cac5dd26c49da2162fc00291bf3b0bd16b661b7b2f606b
+recipe_tcre.yml            4668e357e00c515a8264ac75cb319ce558289689e10189e6f9e982886c414c94
+recipe_zec.yml             b0af7f789b7610ab3f29a6617124aa40c40866ead958204fc199eaf82863de51
+ref/recipe_ref_sea_ice_area_basic.yml 552e282a16ec355778b06f33897e1b8ba8388e5f8a5f814c4c42d91f63007457