feat: Pydantic-zarr V3 model for Sentinel-1 GRD γ0T RTC stores (#138)

* phase 1: S1 RTC Pydantic models aligned with S2 pattern

- Add src/eopf_geozarr/data_api/s1_rtc.py — Zarr V3 Pydantic models for
  S1 GRD γ0T RTC GeoZarr stores, using pyz.v3 GroupSpec/ArraySpec with
  TypedDict members (same pattern as s2.py uses pyz.v2)
- Models: S1RtcRoot, S1RtcOrbitGroup, S1RtcNativeResolutionDataset,
  S1RtcOverviewResolutionDataset, S1RtcConditionsGroup
- Validation: convention UUIDs, spatial:dimensions, multiscales layout,
  required data arrays (vv/vh/border_mask), gamma_area presence
- Add tests/_test_data/s1_rtc_examples/s1-grd-rtc-31TCH.json — realistic
  fixture with 3 timesteps, 6 overview levels, 3 gamma_area conditions
- Add tests/test_data_api/test_s1_rtc.py — 11 tests: round-trip, structure
  validation, negative cases (missing orbit, r10m, UUIDs, etc.)
- Add conftest fixture s1_rtc_json_example parametrized over all fixtures

* refactor: improve Pydantic model definitions and streamline imports in S1 RTC module

* fix: standardize spatial dimensions to lowercase in S1 RTC models and test cases

* refactor: use zcm.Multiscales typed model per reviewer feedback

- Replace dict[str, Any] multiscales field with zcm.Multiscales import
- Remove inline MultiscalesTransform/ScaleLevel/Multiscales classes
- Update test assertions for Pydantic model attribute access

* fix: configure ruff TC001 for Pydantic runtime-evaluated base classes

- Add [tool.ruff.lint.flake8-type-checking] runtime-evaluated-base-classes
  for pydantic.BaseModel so Pydantic field type imports aren't flagged
- Remove 4 stale noqa comments auto-fixed by ruff

* refactor: replace validators with precise type annotations per review

- spatial_dimensions: tuple[Literal['y'], Literal['x']] (removes validator)
- spatial_bbox: tuple[float, float, float, float] (removes validator)
- spatial_shape: tuple[int, int] (removes validator)
- spatial_transform: tuple[float, ...] x6 (removes validator)
- S1RtcOrbitGroupMembers: r10m required, others NotRequired (removes validator)
- Add resolution_levels() method to S1RtcOrbitGroup
- Apply same tuple types to S1RtcConditionsAttrs

* ci: disable temporarly pre-commit job in ci.yml

Comment out pre-commit job in CI workflow

* ci: enable pre-commit checks in CI workflow

* ci: transitive actions/cache@v4 dependency

---------

Co-authored-by: Loïc Houpert <10154151+lhoupert@users.noreply.github.com>

Author: emmanuelmathot

.github/workflows/ci.yml

@@ -14,7 +14,10 @@ jobs:
     - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
       with:
         python-version: '3.12'
-    - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+    - name: Install pre-commit
+      run: pip install pre-commit
+    - name: Run pre-commit
+      run: pre-commit run --all-files
 
   test:
     runs-on: ${{ matrix.os }}

pyproject.toml

@@ -150,6 +150,9 @@ ignore = [
     "TRY003",  # Long exception messages outside class - common pattern
 ]
 
+[tool.ruff.lint.flake8-type-checking]
+runtime-evaluated-base-classes = ["pydantic.BaseModel"]
+
 [tool.mypy]
 python_version = "3.12"
 warn_return_any = true

src/eopf_geozarr/data_api/geozarr/common.py

@@ -24,7 +24,7 @@
 from pydantic.experimental.missing_sentinel import MISSING
 from typing_extensions import runtime_checkable
 
-from eopf_geozarr.data_api.geozarr.projjson import ProjJSON  # noqa: TC001
+from eopf_geozarr.data_api.geozarr.projjson import ProjJSON
 
 if TYPE_CHECKING:
     from collections.abc import Mapping

src/eopf_geozarr/data_api/geozarr/geoproj.py

@@ -8,7 +8,7 @@
 from zarr_cm import geo_proj
 
 from eopf_geozarr.data_api.geozarr.common import is_none
-from eopf_geozarr.data_api.geozarr.projjson import ProjJSON  # noqa: TC001
+from eopf_geozarr.data_api.geozarr.projjson import ProjJSON
 
 PROJ_UUID = geo_proj.UUID
 

src/eopf_geozarr/data_api/geozarr/multiscales/geozarr.py

@@ -5,7 +5,7 @@
 from pydantic import BaseModel, model_validator
 from pydantic.experimental.missing_sentinel import MISSING
 from typing_extensions import TypedDict
-from zarr_cm import ConventionMetadataObject  # noqa: TC002
+from zarr_cm import ConventionMetadataObject
 
 from . import tms, zcm
 

src/eopf_geozarr/data_api/geozarr/multiscales/tms.py

@@ -2,7 +2,7 @@
 
 from pydantic import BaseModel
 
-from eopf_geozarr.data_api.geozarr.types import ResamplingMethod  # noqa: TC001
+from eopf_geozarr.data_api.geozarr.types import ResamplingMethod
 
 
 class TileMatrix(BaseModel):

src/eopf_geozarr/data_api/s1_rtc.py

@@ -0,0 +1,285 @@
+"""
+Pydantic-zarr integrated models for Sentinel-1 GRD gamma0T RTC GeoZarr stores.
+
+Uses the pyz.v3 GroupSpec/ArraySpec with TypedDict members to enforce strict
+structure validation — same pattern as s2.py (which uses pyz.v2 for Zarr V2).
+
+These models validate time-series Zarr V3 stores built from S1Tiling GeoTIFFs
+on the Sentinel-2 MGRS grid. This is a *different data product* from the EOPF
+L1 GRD models in s1.py — those describe radar-geometry Zarr V2 products.
+
+Store hierarchy::
+
+    s1-grd-rtc-{tile}.zarr/
+    ├── zarr.json
+    ├── ascending/
+    │   ├── zarr.json          # zarr_conventions, multiscales, proj:, spatial:
+    │   ├── r10m/              # native resolution dataset
+    │   │   ├── vv/            # (time, Y, X) float32
+    │   │   ├── vh/            # (time, Y, X) float32
+    │   │   ├── border_mask/   # (time, Y, X) uint8
+    │   │   ├── time/          # (time,) int64 datetime
+    │   │   ├── absolute_orbit/
+    │   │   ├── relative_orbit/
+    │   │   └── platform/
+    │   ├── r20m/ … r720m/     # overview levels (vv, vh, border_mask only)
+    │   └── conditions/
+    │       └── gamma_area_{orbit}/  # (Y, X) float32
+    └── descending/
+        └── (same structure)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, Self
+
+from pydantic import BaseModel, Field, model_validator
+from typing_extensions import TypedDict
+from zarr_cm import geo_proj
+from zarr_cm import multiscales as multiscales_cm
+from zarr_cm import spatial as spatial_cm
+
+from eopf_geozarr.data_api.geozarr.common import DatasetAttrs
+from eopf_geozarr.data_api.geozarr.multiscales.zcm import Multiscales
+from eopf_geozarr.pyz.v3 import ArraySpec, GroupSpec
+
+# ============================================================================
+# Constants
+# ============================================================================
+
+MULTISCALES_UUID = multiscales_cm.UUID
+GEO_PROJ_UUID = geo_proj.UUID
+SPATIAL_UUID = spatial_cm.UUID
+
+REQUIRED_CONVENTION_UUIDS = frozenset({MULTISCALES_UUID, GEO_PROJ_UUID, SPATIAL_UUID})
+
+ResolutionLevel = Literal["r10m", "r20m", "r60m", "r120m", "r360m", "r720m"]
+OrbitDirection = Literal["ascending", "descending"]
+Polarisation = Literal["vv", "vh"]
+
+# ============================================================================
+# Attributes models
+# ============================================================================
+
+
+class S1RtcOrbitGroupAttrs(BaseModel):
+    """Attributes for an orbit-direction group (ascending or descending).
+
+    Carries the three GeoZarr conventions plus proj:/spatial:/multiscales metadata.
+    """
+
+    zarr_conventions: list[dict[str, Any]]
+    multiscales: Multiscales
+    proj_code: str = Field(alias="proj:code")
+    spatial_dimensions: tuple[Literal["y"], Literal["x"]] = Field(alias="spatial:dimensions")
+    spatial_bbox: tuple[float, float, float, float] = Field(alias="spatial:bbox")
+
+    model_config = {"extra": "allow", "populate_by_name": True, "serialize_by_alias": True}
+
+    @model_validator(mode="after")
+    def validate_zarr_conventions(self) -> Self:
+        """Ensure all three required convention UUIDs are present."""
+        present = {c["uuid"] for c in self.zarr_conventions if "uuid" in c}
+        missing = REQUIRED_CONVENTION_UUIDS - present
+        if missing:
+            raise ValueError(f"Missing required zarr_conventions UUIDs: {missing}")
+        return self
+
+
+class S1RtcResolutionAttrs(BaseModel):
+    """Attributes for a resolution-level group (r10m, r20m, ...)."""
+
+    spatial_shape: tuple[int, int] = Field(alias="spatial:shape")
+    spatial_transform: tuple[float, float, float, float, float, float] = Field(
+        alias="spatial:transform"
+    )
+
+    model_config = {"extra": "allow", "populate_by_name": True, "serialize_by_alias": True}
+
+
+class S1RtcConditionsAttrs(BaseModel):
+    """Attributes for the conditions group."""
+
+    proj_code: str = Field(alias="proj:code")
+    spatial_dimensions: tuple[Literal["y"], Literal["x"]] = Field(alias="spatial:dimensions")
+    spatial_transform: tuple[float, float, float, float, float, float] = Field(
+        alias="spatial:transform"
+    )
+
+    model_config = {"extra": "allow", "populate_by_name": True, "serialize_by_alias": True}
+
+
+# ============================================================================
+# TypedDict members (same pattern as S2 Sentinel2ResolutionMembers)
+# ============================================================================
+
+
+class S1RtcNativeResolutionMembers(TypedDict, closed=True, total=False):  # type: ignore[call-arg]
+    """Members for the native resolution dataset (r10m).
+
+    Data variables (time, Y, X) plus 1-D coordinate variables (time,).
+    All fields optional since not all arrays are present during incremental construction.
+    """
+
+    vv: ArraySpec[Any]
+    vh: ArraySpec[Any]
+    border_mask: ArraySpec[Any]
+    time: ArraySpec[Any]
+    absolute_orbit: ArraySpec[Any]
+    relative_orbit: ArraySpec[Any]
+    platform: ArraySpec[Any]
+
+
+class S1RtcOverviewResolutionMembers(TypedDict, closed=True, total=False):  # type: ignore[call-arg]
+    """Members for overview resolution datasets (r20m … r720m).
+
+    Only data variables, no coordinate arrays.
+    """
+
+    vv: ArraySpec[Any]
+    vh: ArraySpec[Any]
+    border_mask: ArraySpec[Any]
+
+
+# ============================================================================
+# Group models (same pattern as S2 Sentinel2ResolutionDataset etc.)
+# ============================================================================
+
+
+class S1RtcNativeResolutionDataset(
+    GroupSpec[S1RtcResolutionAttrs, S1RtcNativeResolutionMembers]  # type: ignore[type-var]
+):
+    """The r10m dataset: data variables + coordinate arrays."""
+
+    @model_validator(mode="after")
+    def validate_data_variables(self) -> Self:
+        """Ensure vv, vh, and border_mask are present."""
+        for name in ("vv", "vh", "border_mask"):
+            if name not in self.members:
+                raise ValueError(f"Native resolution dataset must contain '{name}' array")
+        return self
+
+    @property
+    def vv(self) -> ArraySpec[Any]:
+        return self.members["vv"]
+
+    @property
+    def vh(self) -> ArraySpec[Any]:
+        return self.members["vh"]
+
+    @property
+    def border_mask(self) -> ArraySpec[Any]:
+        return self.members["border_mask"]
+
+
+class S1RtcOverviewResolutionDataset(
+    GroupSpec[S1RtcResolutionAttrs, S1RtcOverviewResolutionMembers]  # type: ignore[type-var]
+):
+    """An overview resolution dataset (r20m-r720m): data variables only."""
+
+
+class S1RtcConditionsGroup(GroupSpec[S1RtcConditionsAttrs, dict[str, ArraySpec[Any]]]):
+    """Time-invariant condition arrays, keyed by name (e.g. gamma_area_008)."""
+
+    @model_validator(mode="after")
+    def validate_has_gamma_area(self) -> Self:
+        """At least one gamma_area_* array should be present."""
+        if not any(k.startswith("gamma_area_") for k in self.members):
+            raise ValueError("Conditions group must contain at least one 'gamma_area_*' array")
+        return self
+
+
+class S1RtcOrbitGroupMembers(TypedDict, closed=True):  # type: ignore[call-arg]
+    """Members for an orbit-direction group.
+
+    r10m is always required; overview levels and conditions are optional.
+    """
+
+    r10m: S1RtcNativeResolutionDataset
+    r20m: NotRequired[S1RtcOverviewResolutionDataset]
+    r60m: NotRequired[S1RtcOverviewResolutionDataset]
+    r120m: NotRequired[S1RtcOverviewResolutionDataset]
+    r360m: NotRequired[S1RtcOverviewResolutionDataset]
+    r720m: NotRequired[S1RtcOverviewResolutionDataset]
+    conditions: NotRequired[S1RtcConditionsGroup]
+
+
+class S1RtcOrbitGroup(
+    GroupSpec[S1RtcOrbitGroupAttrs, S1RtcOrbitGroupMembers]  # type: ignore[type-var]
+):
+    """One orbit direction (ascending or descending) with multiscale layout."""
+
+    @property
+    def r10m(self) -> S1RtcNativeResolutionDataset:
+        return self.members["r10m"]
+
+    @property
+    def conditions(self) -> S1RtcConditionsGroup | None:
+        return self.members.get("conditions")
+
+    def get_resolution(self, level: ResolutionLevel) -> GroupSpec[Any, Any] | None:
+        """Retrieve a resolution dataset by level name."""
+        return self.members.get(level)
+
+    def resolution_levels(self) -> list[ResolutionLevel]:
+        """List available resolution levels in this orbit group."""
+        all_levels: tuple[ResolutionLevel, ...] = (
+            "r10m",
+            "r20m",
+            "r60m",
+            "r120m",
+            "r360m",
+            "r720m",
+        )
+        return [lvl for lvl in all_levels if lvl in self.members]
+
+
+# ============================================================================
+# Root model (same pattern as S2 Sentinel2Root)
+# ============================================================================
+
+
+class S1RtcRootMembers(TypedDict, closed=True, total=False):  # type: ignore[call-arg]
+    """Members for the root group. At least one orbit direction must be present."""
+
+    ascending: S1RtcOrbitGroup
+    descending: S1RtcOrbitGroup
+
+
+class S1RtcRoot(GroupSpec[DatasetAttrs, S1RtcRootMembers]):  # type: ignore[type-var]
+    """Complete S1 GRD RTC GeoZarr V3 hierarchy.
+
+    The hierarchy follows the implementation plan::
+
+        s1-grd-rtc-{tile}.zarr/
+        ├── zarr.json
+        ├── ascending/
+        │   ├── zarr.json          # zarr_conventions, multiscales, proj:, spatial:
+        │   ├── r10m/
+        │   │   ├── vv/            # (time, Y, X) float32
+        │   │   ├── vh/            # (time, Y, X) float32
+        │   │   ├── border_mask/   # (time, Y, X) uint8
+        │   │   ├── time/          # (time,) int64
+        │   │   ├── absolute_orbit/
+        │   │   ├── relative_orbit/
+        │   │   └── platform/
+        │   ├── r20m/ … r720m/
+        │   └── conditions/
+        │       └── gamma_area_{orbit}/
+        └── descending/
+            └── (same)
+    """
+
+    @model_validator(mode="after")
+    def validate_at_least_one_orbit(self) -> Self:
+        if "ascending" not in self.members and "descending" not in self.members:
+            raise ValueError("Store must contain at least one orbit group (ascending/descending)")
+        return self
+
+    @property
+    def ascending(self) -> S1RtcOrbitGroup | None:
+        return self.members.get("ascending")
+
+    @property
+    def descending(self) -> S1RtcOrbitGroup | None:
+        return self.members.get("descending")