Merge pull request #1507 from esm-tools/esm-catalog/pr-a1d-datacube-extension

feat(esm_catalog): PR-A1d — datacube STAC extension

Author: mandresm

.github/workflows/esm-catalog-tests.yml

@@ -34,6 +34,6 @@ jobs:
           # with --no-deps and add only the deps it actually imports (plus a modern
           # pytest; the base pins pytest==7.1.2, which predates 3.12 support).
           pip install -e . --no-deps
-          pip install -U "pytest>=7.4" click loguru pystac shapely universal-pathlib
+          pip install -U "pytest>=7.4" click loguru pystac shapely universal-pathlib jsonschema
       - name: Run esm_catalog tests
         run: pytest tests/test_esm_catalog -v

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 6.66.0
+current_version = 6.66.1
 commit = True
 tag = True
 

setup.py

@@ -126,6 +126,6 @@
     test_suite="tests",
     tests_require=test_requirements,
     url="https://github.com/esm-tools/esm_tools",
-    version="6.66.0",
+    version="6.66.1",
     zip_safe=False,
 )

src/esm_archiving/__init__.py

@@ -4,7 +4,7 @@
 
 __author__ = """Paul Gierz"""
 __email__ = "pgierz@awi.de"
-__version__ = "6.66.0"
+__version__ = "6.66.1"
 
 from .esm_archiving import (archive_mistral, check_tar_lists,
                             delete_original_data, determine_datestamp_location,

src/esm_calendar/__init__.py

@@ -2,6 +2,6 @@
 
 __author__ = """Dirk Barbi"""
 __email__ = "dirk.barbi@awi.de"
-__version__ = "6.66.0"
+__version__ = "6.66.1"
 
 from .esm_calendar import *

src/esm_catalog/datacube.py

@@ -0,0 +1,68 @@
+"""Datacube STAC extension: cube:dimensions and cube:variables.
+
+Expected metadata shapes (the contract the file scanners must meet):
+
+    metadata["dimensions"]: dict mapping dimension name to a STAC datacube
+        Dimension Object, e.g.
+        {"time": {"type": "temporal", "extent": ["2000-01-01T00:00:00Z",
+                                                 "2000-12-31T00:00:00Z"]},
+         "lon": {"type": "spatial", "axis": "x", "extent": [-180.0, 180.0]}}
+
+    metadata["variables"]: list of dicts with keys
+        name (str, required — entries without it are skipped),
+        dimensions (list[str]), units (str), and any of
+        description / long_name / standard_name (str).
+
+The v2.2.0 schema requires cube:dimensions whenever the extension URL is
+declared, so the extension is a no-op unless dimensions are present.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from esm_catalog.registry import EXTENSION_URLS
+
+if TYPE_CHECKING:
+    import pystac
+
+
+def add_datacube_extension(item: "pystac.Item", metadata: dict) -> None:
+    """Inject datacube extension fields into *item* from *metadata*.
+
+    Sets item.properties["cube:dimensions"] (pass-through) and
+    item.properties["cube:variables"] (mapped), and appends the datacube
+    schema URL to item.stac_extensions (idempotent). No-op when *metadata*
+    carries no dimensions.
+    """
+    dims = metadata.get("dimensions", {})
+    if not dims:
+        return
+
+    item.properties["cube:dimensions"] = dims
+
+    cube_vars = _to_cube_variables(metadata.get("variables", []))
+    if cube_vars:
+        item.properties["cube:variables"] = cube_vars
+
+    url = EXTENSION_URLS["datacube"]
+    if url not in item.stac_extensions:
+        item.stac_extensions.append(url)
+
+
+def _to_cube_variables(variables: list) -> dict:
+    """Map scanner variable entries to datacube Variable Objects."""
+    cube_vars = {}
+    for v in variables:
+        name = v.get("name")
+        if not name:
+            continue
+        entry: dict = {"dimensions": v.get("dimensions", [])}
+        if "units" in v:
+            entry["unit"] = v["units"]
+        for key in ("description", "long_name", "standard_name"):
+            if key in v:
+                entry["description"] = v[key]
+                break
+        cube_vars[name] = entry
+    return cube_vars

src/esm_catalog/item.py

@@ -10,6 +10,8 @@
 from pystac import Asset, Item, Link
 from upath import UPath
 
+from esm_catalog.datacube import add_datacube_extension
+
 
 def make_item(
     path: Union[Path, UPath, str],
@@ -58,6 +60,8 @@ def make_item(
         )
     )
 
+    add_datacube_extension(item, metadata)
+
     return item
 
 

src/esm_cleanup/__init__.py

@@ -2,4 +2,4 @@
 
 __author__ = """Dirk Barbi"""
 __email__ = "dirk.barbi@awi.de"
-__version__ = "6.66.0"
+__version__ = "6.66.1"

src/esm_database/__init__.py

@@ -2,4 +2,4 @@
 
 __author__ = """Dirk Barbi"""
 __email__ = "dirk.barbi@awi.de"
-__version__ = "6.66.0"
+__version__ = "6.66.1"

src/esm_environment/__init__.py

@@ -2,6 +2,6 @@
 
 __author__ = """Dirk Barbi"""
 __email__ = "dirk.barbi@awi.de"
-__version__ = "6.66.0"
+__version__ = "6.66.1"
 
 from .esm_environment import *