climate-ref-core 0.6.5__tar.gz → 0.6.6__tar.gz

{climate_ref_core-0.6.5 → climate_ref_core-0.6.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: climate-ref-core
-Version: 0.6.5
+Version: 0.6.6
 Summary: Core library for the CMIP Rapid Evaluation Framework
 Author-email: Jared Lewis <jared.lewis@climate-resource.com>, Mika Pflueger <mika.pflueger@climate-resource.com>, Bouwe Andela <b.andela@esciencecenter.nl>, Jiwoo Lee <lee1043@llnl.gov>, Min Xu <xum1@ornl.gov>, Nathan Collier <collierno@ornl.gov>, Dora Hegedus <dora.hegedus@stfc.ac.uk>
 License-Expression: Apache-2.0
@@ -29,7 +29,7 @@ Requires-Dist: pydantic>=2.10.6
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: requests
 Requires-Dist: rich
-Requires-Dist: setuptools>=75.8.0
+Requires-Dist: setuptools<81
 Requires-Dist: typing-extensions
 Description-Content-Type: text/markdown
 

{climate_ref_core-0.6.5 → climate_ref_core-0.6.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "climate-ref-core"
-version = "0.6.5"
+version = "0.6.6"
 description = "Core library for the CMIP Rapid Evaluation Framework"
 readme = "README.md"
 authors = [
@@ -39,7 +39,7 @@ dependencies = [
     "environs>=11",
     "pyyaml>=6.0.2",
     # Not used directly, but required to support some installations
-    "setuptools>=75.8.0",
+    "setuptools<81",
 
     # SPEC 0000 constraints
     # We follow [SPEC-0000](https://scientific-python.org/specs/spec-0000/)

{climate_ref_core-0.6.5 → climate_ref_core-0.6.6}/src/climate_ref_core/constraints.py

@@ -6,7 +6,7 @@ import sys
 import warnings
 from collections import defaultdict
 from collections.abc import Mapping
-from typing import Protocol, runtime_checkable
+from typing import Literal, Protocol, runtime_checkable
 
 if sys.version_info < (3, 11):
     from typing_extensions import Self
@@ -148,6 +148,7 @@ class RequireFacets:
 
     dimension: str
     required_facets: tuple[str, ...]
+    operator: Literal["all", "any"] = "all"
 
     def validate(self, group: pd.DataFrame) -> bool:
         """
@@ -156,7 +157,8 @@ class RequireFacets:
         if self.dimension not in group:
             logger.warning(f"Dimension {self.dimension} not present in group {group}")
             return False
-        return all(value in group[self.dimension].values for value in self.required_facets)
+        op = all if self.operator == "all" else any
+        return op(value in group[self.dimension].values for value in self.required_facets)
 
 
 @frozen

{climate_ref_core-0.6.5 → climate_ref_core-0.6.6}/src/climate_ref_core/datasets.py

@@ -5,7 +5,7 @@ Dataset management and filtering
 import enum
 import functools
 import hashlib
-from collections.abc import Collection, Iterable
+from collections.abc import Collection, Iterable, Iterator
 from typing import Any, Self
 
 import pandas as pd
@@ -172,9 +172,24 @@ class ExecutionDatasetCollection:
     def __hash__(self) -> int:
         return hash(self.hash)
 
+    def __iter__(self) -> Iterator[SourceDatasetType]:
+        return iter(self._collection)
+
+    def keys(self) -> Iterable[SourceDatasetType]:
+        """
+        Iterate over the source types in the collection.
+        """
+        return self._collection.keys()
+
+    def values(self) -> Iterable[DatasetCollection]:
+        """
+        Iterate over the datasets in the collection.
+        """
+        return self._collection.values()
+
     def items(self) -> Iterable[tuple[SourceDatasetType, DatasetCollection]]:
         """
-        Iterate over the datasets in the collection
+        Iterate over the items in the collection.
         """
         return self._collection.items()
 

{climate_ref_core-0.6.5 → climate_ref_core-0.6.6}/src/climate_ref_core/diagnostics.py

@@ -14,6 +14,7 @@ from attrs import field, frozen
 from climate_ref_core.constraints import GroupConstraint
 from climate_ref_core.datasets import ExecutionDatasetCollection, FacetFilter, SourceDatasetType
 from climate_ref_core.metric_values import SeriesMetricValue
+from climate_ref_core.metric_values.typing import SeriesDefinition
 from climate_ref_core.pycmec.metric import CMECMetric
 from climate_ref_core.pycmec.output import CMECOutput
 
@@ -182,9 +183,11 @@ class ExecutionResult:
     Whether the diagnostic execution ran successfully.
     """
 
-    series: Sequence[SeriesMetricValue] = field(factory=tuple)
+    series_filename: pathlib.Path | None = None
     """
     A collection of series metric values that were extracted from the execution.
+
+    These are written to a CSV file in the output directory.
     """
 
     @staticmethod
@@ -193,6 +196,7 @@ class ExecutionResult:
         *,
         cmec_output_bundle: CMECOutput | dict[str, Any],
         cmec_metric_bundle: CMECMetric | dict[str, Any],
+        series: Sequence[SeriesMetricValue] = tuple(),
     ) -> ExecutionResult:
         """
         Build a ExecutionResult from a CMEC output bundle.
@@ -205,6 +209,8 @@ class ExecutionResult:
             An output bundle in the CMEC format.
         cmec_metric_bundle
             An diagnostic bundle in the CMEC format.
+        series
+            Series metric values extracted from the execution.
 
         Returns
         -------
@@ -223,17 +229,21 @@ class ExecutionResult:
             cmec_metric = cmec_metric_bundle
 
         definition.to_output_path(filename=None).mkdir(parents=True, exist_ok=True)
-        bundle_path = definition.to_output_path("output.json")
-        cmec_output.dump_to_json(bundle_path)
 
-        definition.to_output_path(filename=None).mkdir(parents=True, exist_ok=True)
-        bundle_path = definition.to_output_path("diagnostic.json")
-        cmec_metric.dump_to_json(bundle_path)
+        output_filename = "output.json"
+        metric_filename = "diagnostic.json"
+        series_filename = "series.json"
 
+        cmec_output.dump_to_json(definition.to_output_path(output_filename))
+        cmec_metric.dump_to_json(definition.to_output_path(metric_filename))
+        SeriesMetricValue.dump_to_json(definition.to_output_path(series_filename), series)
+
+        # We are using relative paths for the output files for portability of the results
         return ExecutionResult(
             definition=definition,
-            output_bundle_filename=pathlib.Path("output.json"),
-            metric_bundle_filename=pathlib.Path("diagnostic.json"),
+            output_bundle_filename=pathlib.Path(output_filename),
+            metric_bundle_filename=pathlib.Path(metric_filename),
+            series_filename=pathlib.Path(series_filename),
             successful=True,
         )
 
@@ -432,6 +442,11 @@ class AbstractDiagnostic(Protocol):
     is raised.
     """
 
+    series: Sequence[SeriesDefinition]
+    """
+    Definition of the series that are produced by the diagnostic.
+    """
+
     provider: DiagnosticProvider
     """
     The provider that provides the diagnostic.
@@ -493,6 +508,8 @@ class Diagnostic(AbstractDiagnostic):
     See (climate_ref_example.example.ExampleDiagnostic)[] for an example implementation.
     """
 
+    series: Sequence[SeriesDefinition] = tuple()
+
     def __init__(self) -> None:
         super().__init__()
         self._provider: DiagnosticProvider | None = None

{climate_ref_core-0.6.5 → climate_ref_core-0.6.6}/src/climate_ref_core/executor.py

@@ -160,12 +160,15 @@ def import_executor_cls(fqn: str) -> type[Executor]:
         imp = importlib.import_module(module)
         executor: type[Executor] = getattr(imp, attribute_name)
 
+        if isinstance(executor, Exception):
+            raise executor
+
         # We can't really check if the executor is a subclass of Executor here
         # Protocols can't be used with issubclass if they have non-method members
         # We have to check this at class instantiation time
 
         return executor
-    except ModuleNotFoundError:
+    except (ModuleNotFoundError, ImportError):
         logger.error(f"Package '{fqn}' not found")
         raise InvalidExecutorException(fqn, f"Module '{module}' not found")
     except AttributeError:

climate_ref_core-0.6.6/src/climate_ref_core/metric_values/typing.py

@@ -0,0 +1,139 @@
+import json
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, Self
+
+from pydantic import BaseModel, model_validator
+
+Value = float | int
+
+
+class SeriesDefinition(BaseModel):
+    """
+    A definition of a 1-d array with an associated index and additional dimensions.
+    """
+
+    file_pattern: str
+    """A glob pattern to match files that contain the series values."""
+
+    sel: dict[str, Any] | None = None
+    """A dictionary of selection criteria to apply with :meth:`xarray.Dataset.sel` after loading the file."""
+
+    dimensions: dict[str, str]
+    """Key, value pairs that identify the dimensions of the metric."""
+
+    values_name: str
+    """The name of the variable in the file that contains the values of the series."""
+
+    index_name: str
+    """The name of the variable in the file that contains the index of the series."""
+
+    attributes: Sequence[str]
+    """A list of attributes that should be extracted from the file and included in the series metadata."""
+
+
+class SeriesMetricValue(BaseModel):
+    """
+    A 1-d array with an associated index and additional dimensions
+
+    These values are typically sourced from the CMEC metrics bundle
+    """
+
+    dimensions: dict[str, str]
+    """
+    Key, value pairs that identify the dimensions of the metric
+
+    These values are used for a faceted search of the metric values.
+    """
+    values: Sequence[Value]
+    """
+    A 1-d array of values
+    """
+    index: Sequence[str | Value]
+    """
+    A 1-d array of index values
+
+    Values must be strings or numbers and have the same length as values.
+    Non-unique index values are not allowed.
+    """
+
+    index_name: str
+    """
+    The name of the index.
+
+    This is used for presentation purposes and is not used in the controlled vocabulary.
+    """
+
+    attributes: dict[str, str | Value] | None = None
+    """
+    Additional unstructured attributes associated with the metric value
+    """
+
+    @model_validator(mode="after")
+    def validate_index_length(self) -> Self:
+        """Validate that index has the same length as values"""
+        if len(self.index) != len(self.values):
+            raise ValueError(
+                f"Index length ({len(self.index)}) must match values length ({len(self.values)})"
+            )
+        return self
+
+    @classmethod
+    def dump_to_json(cls, path: Path, series: Sequence["SeriesMetricValue"]) -> None:
+        """
+        Dump a sequence of SeriesMetricValue to a JSON file.
+
+        Parameters
+        ----------
+        path
+            The path to the JSON file.
+
+            The directory containing this file must already exist.
+            This file will be overwritten if it already exists.
+        series
+            The series values to dump.
+        """
+        with open(path, "w") as f:
+            json.dump([s.model_dump() for s in series], f, indent=2)
+
+    @classmethod
+    def load_from_json(
+        cls,
+        path: Path,
+    ) -> list["SeriesMetricValue"]:
+        """
+        Dump a sequence of SeriesMetricValue to a JSON file.
+
+        Parameters
+        ----------
+        path
+            The path to the JSON file.
+        """
+        with open(path) as f:
+            data = json.load(f)
+
+        if not isinstance(data, list):
+            raise ValueError(f"Expected a list of series values, got {type(data)}")
+
+        return [cls.model_validate(s) for s in data]
+
+
+class ScalarMetricValue(BaseModel):
+    """
+    A scalar value with an associated dimensions
+    """
+
+    dimensions: dict[str, str]
+    """
+    Key, value pairs that identify the dimensions of the metric
+
+    These values are used for a faceted search of the metric values.
+    """
+    value: Value
+    """
+    A scalar value
+    """
+    attributes: dict[str, str | Value] | None = None
+    """
+    Additional unstructured attributes associated with the metric value
+    """

{climate_ref_core-0.6.5 → climate_ref_core-0.6.6}/src/climate_ref_core/providers.py

@@ -232,6 +232,27 @@ def _get_micromamba_url() -> str:
 class CondaDiagnosticProvider(CommandLineDiagnosticProvider):
     """
     A provider for diagnostics that can be run from the command line in a conda environment.
+
+    Parameters
+    ----------
+    name
+        The name of the provider.
+    version
+        The version of the provider.
+    slug
+        A slugified version of the name.
+    repo
+        URL of the git repository to install a development version of the package from.
+    tag_or_commit
+        Tag or commit to install from the `repo` repository.
+
+    Attributes
+    ----------
+    env_vars
+        Environment variables to set when running commands in the conda environment.
+    url
+        URL to install a development version of the package from.
+
     """
 
     def __init__(
@@ -246,6 +267,7 @@ class CondaDiagnosticProvider(CommandLineDiagnosticProvider):
         self._conda_exe: Path | None = None
         self._prefix: Path | None = None
         self.url = f"git+{repo}@{tag_or_commit}" if repo and tag_or_commit else None
+        self.env_vars: dict[str, str] = {}
 
     @property
     def prefix(self) -> Path:
@@ -404,6 +426,8 @@ class CondaDiagnosticProvider(CommandLineDiagnosticProvider):
             *cmd,
         ]
         logger.info(f"Running '{' '.join(cmd)}'")
+        env_vars = os.environ.copy()
+        env_vars.update(self.env_vars)
         try:
             # This captures the log output until the execution is complete
             # We could poll using `subprocess.Popen` if we want something more responsive
@@ -413,6 +437,7 @@ class CondaDiagnosticProvider(CommandLineDiagnosticProvider):
                 stdout=subprocess.PIPE,
                 stderr=subprocess.STDOUT,
                 text=True,
+                env=env_vars,
             )
             logger.info("Command output: \n" + res.stdout)
             logger.info("Command execution successful")

{climate_ref_core-0.6.5 → climate_ref_core-0.6.6}/src/climate_ref_core/pycmec/controlled_vocabulary.py

@@ -1,4 +1,5 @@
 import pathlib
+from collections.abc import Iterable, Sequence
 from typing import Any
 
 from attrs import field, frozen, validators
@@ -7,6 +8,7 @@ from loguru import logger
 from yaml import safe_load
 
 from climate_ref_core.exceptions import ResultValidationError
+from climate_ref_core.metric_values import ScalarMetricValue, SeriesMetricValue
 from climate_ref_core.pycmec.metric import CMECMetric
 
 RESERVED_DIMENSION_NAMES = {"attributes", "json_structure", "created_at", "updated_at", "value", "id"}
@@ -122,33 +124,49 @@ class CV:
                 return dim
         raise KeyError(f"Dimension {name} not found")
 
-    def validate_metrics(self, metric_bundle: CMECMetric) -> None:
+    def _validate_value(self, metric_value: ScalarMetricValue | SeriesMetricValue) -> None:
         """
-        Validate a diagnostic bundle against a CV
+        Validate a single metric value against the CV
+        """
+        for k, v in metric_value.dimensions.items():
+            try:
+                dimension = self.get_dimension_by_name(k)
+            except KeyError:
+                raise ResultValidationError(f"Unknown dimension: {k!r}")
+            if not dimension.allow_extra_values:
+                if v not in [dv.name for dv in dimension.values]:
+                    raise ResultValidationError(f"Unknown value {v!r} for dimension {k!r}")
+
+        if hasattr(metric_value, "value") and not isinstance(metric_value.value, float):  # pragma: no cover
+            # This may not be possible with the current CMECMetric implementation
+            raise ResultValidationError(f"Unexpected value: {metric_value.value!r}")
+
+    def validate_metrics(self, metric_value_collection: CMECMetric | Sequence[SeriesMetricValue]) -> None:
+        """
+        Validate a set of metric values (either scalar or series) against a CV
 
         The CV describes the accepted dimensions and values within a bundle
 
         Parameters
         ----------
-        metric_bundle
+        metric_value_collection
+            A collection of metric values to validate.
+
+            This can be a CMECMetric instance or a sequence of SeriesMetricValue instances.
 
         Raises
         ------
         ResultValidationError
             If the validation of the dimensions or values fails
         """
-        for result in metric_bundle.iter_results():
-            for k, v in result.dimensions.items():
-                try:
-                    dimension = self.get_dimension_by_name(k)
-                except KeyError:
-                    raise ResultValidationError(f"Unknown dimension: {k!r}")
-                if not dimension.allow_extra_values:
-                    if v not in [dv.name for dv in dimension.values]:
-                        raise ResultValidationError(f"Unknown value {v!r} for dimension {k!r}")
-            if not isinstance(result.value, float):  # pragma: no cover
-                # This may not be possible with the current CMECMetric implementation
-                raise ResultValidationError(f"Unexpected value: {result.value!r}")
+        generator: Iterable[SeriesMetricValue | ScalarMetricValue]
+        if isinstance(metric_value_collection, CMECMetric):
+            generator = metric_value_collection.iter_results()
+        else:
+            generator = iter(metric_value_collection)
+
+        for result in generator:
+            self._validate_value(result)
 
     @staticmethod
     def load_from_file(filename: pathlib.Path | str) -> "CV":

{climate_ref_core-0.6.5 → climate_ref_core-0.6.6}/tests/unit/metric_values/test_typing.py

@@ -1,4 +1,5 @@
 import re
+from pathlib import Path
 
 import pytest
 
@@ -65,3 +66,34 @@ class TestSeriesMetricValue:
                 index=[1.0],
                 index_name="time",
             )
+
+    def test_dump_and_load_json(self, tmp_path: Path):
+        series = [
+            SeriesMetricValue(
+                dimensions={"model": "test1"},
+                values=[1.0, 2.0, 3.0],
+                index=[0, 1, 2],
+                index_name="time",
+                attributes={"attr": "value1"},
+            ),
+            SeriesMetricValue(
+                dimensions={"model": "test2"},
+                values=[4.0, 5.0],
+                index=["a", "b"],
+                index_name="other",
+                attributes=None,
+            ),
+        ]
+        path = tmp_path / "test.json"
+
+        SeriesMetricValue.dump_to_json(path, series)
+        loaded_series = SeriesMetricValue.load_from_json(path)
+
+        assert loaded_series == series
+
+    def test_load_from_json_not_a_list(self, tmp_path: Path):
+        path = tmp_path / "test.json"
+        path.write_text('{"not": "a list"}')
+
+        with pytest.raises(ValueError, match="Expected a list of series values, got <class 'dict'>"):
+            SeriesMetricValue.load_from_json(path)

climate_ref_core-0.6.6/tests/unit/test_datasets/dataset_collection_hash.yml

@@ -0,0 +1,2 @@
+2074659132983676899
+...

climate_ref_core-0.6.6/tests/unit/test_datasets/dataset_collection_obs4mips_hash.yml

@@ -0,0 +1,2 @@
+7325210510695053782
+...

climate_ref_core-0.6.6/tests/unit/test_datasets/metric_dataset_hash.yml

@@ -0,0 +1,2 @@
+77b5ed086e4aedb114d6f02472e88edd1db6dae2
+...

{climate_ref_core-0.6.5 → climate_ref_core-0.6.6}/tests/unit/test_datasets.py

@@ -35,6 +35,18 @@ class TestMetricDataset:
         with pytest.raises(KeyError):
             metric_dataset["cmip7"]
 
+    def test_iter(self, metric_dataset):
+        assert tuple(iter(metric_dataset)) == tuple(iter(metric_dataset._collection))
+
+    def test_keys(self, metric_dataset):
+        assert metric_dataset.keys() == metric_dataset._collection.keys()
+
+    def test_values(self, metric_dataset):
+        assert tuple(metric_dataset.values()) == tuple(metric_dataset._collection.values())
+
+    def test_items(self, metric_dataset):
+        assert metric_dataset.items() == metric_dataset._collection.items()
+
     def test_python_hash(self, metric_dataset, cmip6_data_catalog, data_regression):
         dataset_hash = hash(metric_dataset)
 

{climate_ref_core-0.6.5 → climate_ref_core-0.6.6}/tests/unit/test_providers.py

@@ -294,6 +294,12 @@ class TestCondaMetricsProvider:
             ):
                 provider.run(["mock-command"])
         else:
+            mocker.patch.object(
+                climate_ref_core.providers.os.environ,
+                "copy",
+                return_value={"existing_var": "existing_value"},
+            )
+            provider.env_vars = {"test_var": "test_value"}
             provider.run(["mock-command"])
 
             run.assert_called_with(
@@ -308,4 +314,5 @@ class TestCondaMetricsProvider:
                 stdout=subprocess.PIPE,
                 stderr=subprocess.STDOUT,
                 text=True,
+                env={"existing_var": "existing_value", "test_var": "test_value"},
             )

climate_ref_core-0.6.5/src/climate_ref_core/metric_values/typing.py

@@ -1,74 +0,0 @@
-from collections.abc import Sequence
-from typing import Self
-
-from pydantic import BaseModel, model_validator
-
-Value = float | int
-
-
-class SeriesMetricValue(BaseModel):
-    """
-    A 1-d array with an associated index and additional dimensions
-
-    These values are typically sourced from the CMEC metrics bundle
-    """
-
-    dimensions: dict[str, str]
-    """
-    Key, value pairs that identify the dimensions of the metric
-
-    These values are used for a faceted search of the metric values.
-    """
-    values: Sequence[Value]
-    """
-    A 1-d array of values
-    """
-    index: Sequence[str | Value]
-    """
-    A 1-d array of index values
-
-    Values must be strings or numbers and have the same length as values.
-    Non-unique index values are not allowed.
-    """
-
-    index_name: str
-    """
-    The name of the index.
-
-    This is used for presentation purposes and is not used in the controlled vocabulary.
-    """
-
-    attributes: dict[str, str | Value] | None = None
-    """
-    Additional unstructured attributes associated with the metric value
-    """
-
-    @model_validator(mode="after")
-    def validate_index_length(self) -> Self:
-        """Validate that index has the same length as values"""
-        if len(self.index) != len(self.values):
-            raise ValueError(
-                f"Index length ({len(self.index)}) must match values length ({len(self.values)})"
-            )
-        return self
-
-
-class ScalarMetricValue(BaseModel):
-    """
-    A scalar value with an associated dimensions
-    """
-
-    dimensions: dict[str, str]
-    """
-    Key, value pairs that identify the dimensions of the metric
-
-    These values are used for a faceted search of the metric values.
-    """
-    value: Value
-    """
-    A scalar value
-    """
-    attributes: dict[str, str | Value] | None = None
-    """
-    Additional unstructured attributes associated with the metric value
-    """

climate_ref_core-0.6.5/tests/unit/test_datasets/dataset_collection_hash.yml

@@ -1,2 +0,0 @@
-7542818482515079959
-...

climate_ref_core-0.6.5/tests/unit/test_datasets/dataset_collection_obs4mips_hash.yml

@@ -1,2 +0,0 @@
-2267913680803057005
-...

climate_ref_core-0.6.5/tests/unit/test_datasets/metric_dataset_hash.yml

@@ -1,2 +0,0 @@
-b7c5c9f8cf6d6324df57e2b78fcfc80f52df8621
-...