climate-ref-core 0.14.2__tar.gz → 0.14.4__tar.gz

{climate_ref_core-0.14.2 → climate_ref_core-0.14.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: climate-ref-core
-Version: 0.14.2
+Version: 0.14.4
 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
@@ -25,7 +25,7 @@ Requires-Dist: fastprogress==1.0.5
 Requires-Dist: intake-esgf>=2025.7.16
 Requires-Dist: loguru>=0.7.0
 Requires-Dist: numpy>=2.0.0
-Requires-Dist: pandas<3,>=2.1.0
+Requires-Dist: pandas>=2.1.0
 Requires-Dist: pooch<2,>=1.8.0
 Requires-Dist: pyarrow>=17.0.0
 Requires-Dist: pydantic>=2.10.6

{climate_ref_core-0.14.2 → climate_ref_core-0.14.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "climate-ref-core"
-version = "0.14.2"
+version = "0.14.4"
 description = "Core library for the CMIP Rapid Evaluation Framework"
 readme = "README.md"
 authors = [
@@ -48,7 +48,7 @@ dependencies = [
     # SPEC 0000 constraints
     # We follow [SPEC-0000](https://scientific-python.org/specs/spec-0000/)
     # which defines a 2-year support window for key libraries and 3-year window for Python versions
-    "pandas>=2.1.0,<3",
+    "pandas>=2.1.0",
     "numpy>=2.0.0",
 
     # Temporarily pin fastprogress dependency (from intake-esm) due to bug in recent version

{climate_ref_core-0.14.2 → climate_ref_core-0.14.4}/src/climate_ref_core/dataset_registry.py

@@ -21,6 +21,30 @@ from climate_ref_core.env import env
 DATASET_URL = env.str("REF_DATASET_URL", default="https://obs4ref.climate-ref.org")
 
 
+def resolve_cache_dir(cache_name: str) -> pathlib.Path:
+    """
+    Resolve the cache directory for a registry.
+
+    If the ``REF_DATASET_CACHE_DIR`` environment variable is set, use that as the root.
+    Otherwise, fall back to the OS cache under ``climate_ref``.
+
+    Parameters
+    ----------
+    cache_name
+        Subdirectory name within the cache root.
+
+    Returns
+    -------
+        The resolved cache directory path.
+    """
+    if env_cache_dir := os.environ.get("REF_DATASET_CACHE_DIR"):
+        cache_dir = pathlib.Path(os.path.expandvars(env_cache_dir)).expanduser()
+    else:
+        cache_dir = pooch.os_cache("climate_ref")
+
+    return cache_dir / cache_name
+
+
 def _verify_hash_matches(fname: str | pathlib.Path, known_hash: str) -> bool:
     """
     Check if the hash of a file matches a known hash.
@@ -207,30 +231,6 @@ class DatasetRegistryManager:
         return list(self._registries.keys())
 
     @staticmethod
-    def _resolve_cache_dir(cache_name: str) -> pathlib.Path:
-        """
-        Resolve the cache directory for a registry.
-
-        If the ``REF_DATASET_CACHE_DIR`` environment variable is set,
-        use that as the root. Otherwise, fall back to the OS cache
-        under ``climate_ref``.
-
-        Parameters
-        ----------
-        cache_name
-            Subdirectory name within the cache root.
-
-        Returns
-        -------
-            The resolved cache directory path.
-        """
-        if env_cache_dir := os.environ.get("REF_DATASET_CACHE_DIR"):
-            cache_dir = pathlib.Path(os.path.expandvars(env_cache_dir)).expanduser()
-        else:
-            cache_dir = pooch.os_cache("climate_ref")
-
-        return cache_dir / cache_name
-
     @staticmethod
     def _migrate_cache(
         registry: pooch.Pooch,
@@ -314,7 +314,7 @@ class DatasetRegistryManager:
         if cache_name is None:
             cache_name = name
 
-        cache_path = self._resolve_cache_dir(cache_name)
+        cache_path = resolve_cache_dir(cache_name)
 
         # Before v0.13.0 everything was cached directly under
         # pooch.os_cache("climate_ref") with no per-registry subdirectory.

{climate_ref_core-0.14.2 → climate_ref_core-0.14.4}/src/climate_ref_core/testing.py

@@ -10,6 +10,7 @@ This module provides:
 
 from __future__ import annotations
 
+import json
 import shutil
 import sys
 from pathlib import Path
@@ -28,6 +29,7 @@ from climate_ref_core.datasets import (
 )
 from climate_ref_core.diagnostics import ExecutionDefinition, ExecutionResult
 from climate_ref_core.esgf.base import ESGFRequest
+from climate_ref_core.metric_values.typing import SeriesMetricValue
 from climate_ref_core.pycmec.metric import CMECMetric
 from climate_ref_core.pycmec.output import CMECOutput
 
@@ -499,6 +501,13 @@ def validate_cmec_bundles(diagnostic: Diagnostic, result: ExecutionResult) -> No
     AssertionError
         If the result is not successful or bundles are invalid
     """
+    # TODO: Add content regression checks for the CMEC bundles (diagnostic.json /
+    # output.json), mirroring `validate_series_regression`. These bundles are only
+    # structurally validated here, so a diagnostic can change the metric/output
+    # values without any regression test failing (see issue #703 for the series
+    # equivalent). A content comparison must sanitise the regenerated bundle first
+    # via `ExecutionRegression.output_replacements`, since the committed bundles
+    # store `<OUTPUT_DIR>` / `<TEST_DATA_DIR>` placeholders.
     assert result.successful, f"Execution failed: {result}"
 
     # Validate metric bundle
@@ -517,6 +526,71 @@ def validate_cmec_bundles(diagnostic: Diagnostic, result: ExecutionResult) -> No
     CMECOutput.load_from_json(result.to_output_path(result.output_bundle_filename))
 
 
+def _load_series_sanitised(path: Path, replacements: dict[str, str]) -> list[SeriesMetricValue]:
+    """
+    Load series from ``path``, replacing real paths with regression placeholders.
+    """
+    text = path.read_text(encoding="utf-8")
+    # Apply replacements longest-key-first in case of nested repleacements
+    for real, placeholder in sorted(replacements.items(), key=lambda kv: len(kv[0]), reverse=True):
+        text = text.replace(real, placeholder)
+    data = json.loads(text)
+    if not isinstance(data, list):
+        raise ValueError(f"Expected a list of series values, got {type(data)}")
+    return [SeriesMetricValue.model_validate(s, strict=True) for s in data]
+
+
+def validate_series_regression(
+    expected_path: Path,
+    actual_path: Path,
+    *,
+    slug: str,
+    replacements: dict[str, str] | None = None,
+) -> None:
+    """
+    Assert that regenerated series match the committed regression series.
+
+    If ``expected_path`` does not exist (legacy regression data without a stored series),
+    the check is skipped.
+
+    Parameters
+    ----------
+    expected_path
+        Path to the committed ``series.json`` regression artifact. This file
+        stores sanitized placeholders (e.g. ``<OUTPUT_DIR>``).
+    actual_path
+        Path to the freshly regenerated ``series.json`` in the output directory.
+        This file contains expanded absolute paths.
+    slug
+        The diagnostic slug, used for error messages.
+    replacements
+        Optional ``real path -> placeholder`` mapping applied to the regenerated series before comparison,
+        mirroring the sanitisation used when the regression data was written.
+
+    Raises
+    ------
+    AssertionError
+        If the regenerated series differ from the committed series.
+    """
+    if not expected_path.exists():
+        return
+
+    expected = SeriesMetricValue.load_from_json(expected_path)
+    actual = _load_series_sanitised(actual_path, replacements or {})
+
+    def _sorted_dump(series: list[SeriesMetricValue]) -> list[dict[str, Any]]:
+        return sorted((s.model_dump(mode="json") for s in series), key=lambda s: repr(s["dimensions"]))
+
+    assert len(actual) == len(expected), (
+        f"Diagnostic {slug} produced {len(actual)} series but the committed series.json "
+        f"has {len(expected)}. Regenerate the regression data with `--force-regen`."
+    )
+    assert _sorted_dump(actual) == _sorted_dump(expected), (
+        f"Diagnostic {slug} produced series that differ from the committed series.json. "
+        f"Regenerate the regression data with `--force-regen`."
+    )
+
+
 @frozen
 class RegressionValidator:
     """
@@ -585,10 +659,19 @@ class RegressionValidator:
         )
 
     def validate(self, definition: ExecutionDefinition) -> None:
-        """Validate CMEC bundles in the regression output."""
+        """Validate CMEC bundles and series in the regression output."""
         result = self.diagnostic.build_execution_result(definition)
         result.to_output_path("out.log").touch()  # Log file not tracked in regression
         validate_cmec_bundles(self.diagnostic, result)
+        validate_series_regression(
+            expected_path=self.paths.regression / "series.json",
+            actual_path=definition.output_directory / "series.json",
+            slug=self.diagnostic.slug,
+            replacements={
+                str(definition.output_directory): "<OUTPUT_DIR>",
+                str(self.test_data_dir): "<TEST_DATA_DIR>",
+            },
+        )
 
 
 def collect_test_case_params(provider: DiagnosticProvider) -> list[ParameterSet]:

{climate_ref_core-0.14.2 → climate_ref_core-0.14.4}/tests/unit/test_dataset_registry/test_dataset_registry.py

@@ -252,11 +252,7 @@ class TestMigrateCache:
 
         new_dir = tmp_path / "new_cache" / "test_registry"
 
-        mocker.patch.object(
-            DatasetRegistryManager,
-            "_resolve_cache_dir",
-            return_value=new_dir,
-        )
+        mocker.patch("climate_ref_core.dataset_registry.resolve_cache_dir", return_value=new_dir)
 
         registry_path, package, resource = fake_registry_file
         with registry_path.open("w") as f:

{climate_ref_core-0.14.2 → climate_ref_core-0.14.4}/tests/unit/test_testing.py

@@ -8,6 +8,7 @@ import yaml
 
 from climate_ref_core.datasets import DatasetCollection, ExecutionDatasetCollection, SourceDatasetType
 from climate_ref_core.diagnostics import ExecutionResult
+from climate_ref_core.metric_values.typing import SeriesMetricValue
 from climate_ref_core.testing import (
     RegressionValidator,
     TestCase,
@@ -19,6 +20,7 @@ from climate_ref_core.testing import (
     load_datasets_from_yaml,
     save_datasets_to_yaml,
     validate_cmec_bundles,
+    validate_series_regression,
 )
 
 
@@ -912,3 +914,120 @@ class TestRegressionValidator:
 
         # Verify build_execution_result was called
         mock_diagnostic.build_execution_result.assert_called_once_with(mock_definition)
+
+
+def _series(value: float, *, dim: str = "M1", index_name: str = "year", attrs=None) -> SeriesMetricValue:
+    """Build a small SeriesMetricValue for testing."""
+    return SeriesMetricValue(
+        dimensions={"source_id": dim},
+        values=[value, value + 1.0],
+        index=["2000", "2001"],
+        index_name=index_name,
+        attributes=attrs,
+    )
+
+
+def _write_series(path: Path, series: list[SeriesMetricValue]) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    SeriesMetricValue.dump_to_json(path, series)
+    return path
+
+
+class TestValidateSeriesRegression:
+    def test_matching_series_passes(self, tmp_path):
+        series = [_series(1.0), _series(5.0, dim="M2")]
+        expected = _write_series(tmp_path / "expected" / "series.json", series)
+        actual = _write_series(tmp_path / "actual" / "series.json", series)
+
+        validate_series_regression(expected, actual, slug="my-diag")
+
+    def test_order_insensitive(self, tmp_path):
+        a, b = _series(1.0, dim="M1"), _series(5.0, dim="M2")
+        expected = _write_series(tmp_path / "expected" / "series.json", [a, b])
+        actual = _write_series(tmp_path / "actual" / "series.json", [b, a])
+
+        validate_series_regression(expected, actual, slug="my-diag")
+
+    def test_missing_expected_is_skipped(self, tmp_path):
+        actual = _write_series(tmp_path / "actual" / "series.json", [_series(1.0)])
+        missing_expected = tmp_path / "expected" / "series.json"
+
+        # Must not raise, even though actual is non-empty.
+        validate_series_regression(missing_expected, actual, slug="my-diag")
+
+    def test_count_mismatch_raises(self, tmp_path):
+        """A different number of series fails with a count message (Check for #703)."""
+        expected = _write_series(tmp_path / "expected" / "series.json", [])
+        actual = _write_series(tmp_path / "actual" / "series.json", [_series(1.0)])
+
+        with pytest.raises(AssertionError, match=r"produced 1 series but the committed series\.json has 0"):
+            validate_series_regression(expected, actual, slug="my-diag")
+
+    def test_value_mismatch_raises(self, tmp_path):
+        """Same count but different values fails with a content message."""
+        expected = _write_series(tmp_path / "expected" / "series.json", [_series(1.0)])
+        actual = _write_series(tmp_path / "actual" / "series.json", [_series(2.0)])
+
+        with pytest.raises(AssertionError, match="produced series that differ"):
+            validate_series_regression(expected, actual, slug="my-diag")
+
+    def test_attribute_mismatch_raises(self, tmp_path):
+        """Differences in series attributes are detected."""
+        expected = _write_series(
+            tmp_path / "expected" / "series.json", [_series(1.0, attrs={"caption": "old"})]
+        )
+        actual = _write_series(tmp_path / "actual" / "series.json", [_series(1.0, attrs={"caption": "new"})])
+
+        with pytest.raises(AssertionError, match="produced series that differ"):
+            validate_series_regression(expected, actual, slug="my-diag")
+
+    def test_slug_in_error_message(self, tmp_path):
+        """The diagnostic slug is surfaced in failure messages."""
+        expected = _write_series(tmp_path / "expected" / "series.json", [])
+        actual = _write_series(tmp_path / "actual" / "series.json", [_series(1.0)])
+
+        with pytest.raises(AssertionError, match="Diagnostic some-slug"):
+            validate_series_regression(expected, actual, slug="some-slug")
+
+    def test_sanitised_path_placeholders_are_normalised(self, tmp_path):
+        """Committed placeholders compare equal to expanded regenerated paths."""
+        expected = _write_series(
+            tmp_path / "expected" / "series.json",
+            [_series(1.0, attrs={"source_file": "<TEST_DATA_DIR>/input.nc"})],
+        )
+        actual = _write_series(
+            tmp_path / "actual" / "series.json",
+            [_series(1.0, attrs={"source_file": f"{tmp_path}/input.nc"})],
+        )
+
+        validate_series_regression(
+            expected,
+            actual,
+            slug="my-diag",
+            replacements={str(tmp_path): "<TEST_DATA_DIR>"},
+        )
+
+    def test_nested_replacements(self, tmp_path):
+        """A nested output dir is substituted before its parent test-data dir."""
+        test_data_dir = tmp_path / "test-data"
+        output_dir = test_data_dir / "diag" / "default" / "output"
+        output_dir.mkdir(parents=True)
+
+        expected = _write_series(
+            test_data_dir / "expected" / "series.json",
+            [_series(1.0, attrs={"plot": "<OUTPUT_DIR>/plot.png", "input": "<TEST_DATA_DIR>/in.nc"})],
+        )
+        actual = _write_series(
+            output_dir / "series.json",
+            [_series(1.0, attrs={"plot": f"{output_dir}/plot.png", "input": f"{test_data_dir}/in.nc"})],
+        )
+
+        validate_series_regression(
+            expected,
+            actual,
+            slug="my-diag",
+            replacements={
+                str(output_dir): "<OUTPUT_DIR>",
+                str(test_data_dir): "<TEST_DATA_DIR>",
+            },
+        )