Merge pull request #1 from ewquon/copilot/refactor-era5-gfs-preprocessing

Implement HindcastBase to eliminate duplicated code and follow Python best practices

Author: ewquon

erftools/hindcast/__init__.py

@@ -0,0 +1,12 @@
+"""Hindcast preprocessing framework for ERA5 and GFS data."""
+from .config import HindcastConfig
+from .base import HindcastBase
+from .era5 import ERA5Hindcast
+from .gfs import GFSHindcast
+
+__all__ = [
+    "HindcastConfig",
+    "HindcastBase",
+    "ERA5Hindcast",
+    "GFSHindcast",
+]

erftools/hindcast/base.py

@@ -0,0 +1,107 @@
+"""Abstract base class for ERA5/GFS hindcast preprocessing workflows."""
+from __future__ import annotations
+
+import datetime as _dt
+import logging
+import os
+from abc import ABC, abstractmethod
+from typing import Any, Optional, Sequence, Union
+
+from erftools.utils.projection import create_lcc_mapping
+
+from .config import HindcastConfig
+
+logger = logging.getLogger(__name__)
+
+
+class HindcastBase(ABC):
+    """Abstract base class for hindcast preprocessing workflows.
+
+    Subclasses must implement :meth:`download` and :meth:`process`.
+    The :meth:`run` method provides a template that calls both in order.
+
+    The configuration can be supplied in one of two ways:
+
+    1. **Legacy input file** – pass *config_file* as the first positional
+       argument (a path to a ``key: value`` text file)::
+
+           hindcast = ERA5Hindcast("input_for_Laura")
+
+    2. **Inline kwargs** – omit *config_file* and supply *datetime* and
+       *area* as keyword arguments::
+
+           hindcast = ERA5Hindcast(
+               datetime="2020-08-26 00:00",
+               area=(50, -130, 10, -50),
+           )
+
+    Parameters
+    ----------
+    config_file:
+        Path to the key:value input file (e.g. ``input_for_Laura``).
+        Mutually exclusive with *datetime*/*area*.
+    datetime:
+        Date/time of the hindcast snapshot.  Accepts a ``str`` parseable by
+        :class:`pandas.Timestamp`, a :class:`datetime.datetime`, or a
+        :class:`pandas.Timestamp`.  Keyword-only; requires *area*.
+    area:
+        Domain extent as ``(lat_max, lon_min, lat_min, lon_max)``.
+        Keyword-only; requires *datetime*.
+    **kwargs:
+        Additional keyword arguments forwarded to subclasses.
+    """
+
+    def __init__(
+        self,
+        config_file: Optional[Union[str, os.PathLike]] = None,
+        *,
+        datetime: Optional[Union[str, _dt.datetime]] = None,
+        area: Optional[Sequence[float]] = None,
+        **kwargs: Any,
+    ) -> None:
+        if config_file is not None:
+            self.config_file: Optional[str] = os.fspath(config_file)
+            self.config: HindcastConfig = HindcastConfig.from_file(self.config_file)
+            logger.info("Loaded config from %s", self.config_file)
+        elif datetime is not None and area is not None:
+            self.config_file = None
+            self.config = HindcastConfig.from_datetime(datetime, area)
+            logger.info("Built config from datetime=%r, area=%r", datetime, area)
+        else:
+            raise ValueError(
+                "Provide either config_file or both datetime and area keyword arguments"
+            )
+        self.config.validate()
+        self.lambert_conformal: str = create_lcc_mapping(self.config.area)
+
+    def _setup_output_dirs(self, *dirs: str) -> None:
+        """Create one or more output directories."""
+        for d in dirs:
+            os.makedirs(d, exist_ok=True)
+
+    @abstractmethod
+    def download(self) -> Any:
+        """Download raw hindcast data.
+
+        Returns
+        -------
+        Any
+            Implementation-specific download result passed to :meth:`process`.
+        """
+
+    @abstractmethod
+    def process(self, download_result: Any) -> None:
+        """Process downloaded data and write ERF input files.
+
+        Parameters
+        ----------
+        download_result:
+            The value returned by :meth:`download`.
+        """
+
+    def run(self) -> None:
+        """Template method: download then process."""
+        logger.info("Starting %s run", self.__class__.__name__)
+        result = self.download()
+        self.process(result)
+        logger.info("Finished %s run", self.__class__.__name__)

erftools/hindcast/config.py

@@ -0,0 +1,150 @@
+"""Configuration dataclass for ERA5/GFS hindcast preprocessing."""
+from __future__ import annotations
+
+import datetime as _dt
+import logging
+import os
+from dataclasses import dataclass
+from typing import List, Sequence, Union
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class HindcastConfig:
+    """Configuration parsed from a hindcast input file.
+
+    The expected file format is a text file with ``key: value`` pairs::
+
+        year: 2020
+        month: 08
+        day: 26
+        time: 00:00
+        area: 50,-130,10,-50
+
+    The ``area`` field is ``lat_max, lon_min, lat_min, lon_max``.
+    """
+
+    year: int
+    month: int
+    day: int
+    time: str  # "HH:MM"
+    area: List[float]  # [lat_max, lon_min, lat_min, lon_max]
+
+    @classmethod
+    def from_file(cls, filename: Union[str, os.PathLike]) -> "HindcastConfig":
+        """Parse a key:value input file into a :class:`HindcastConfig`.
+
+        Parameters
+        ----------
+        filename:
+            Path to the input file.  Accepts both ``str`` and
+            :class:`os.PathLike` objects (e.g. :class:`pathlib.Path`).
+
+        Returns
+        -------
+        HindcastConfig
+        """
+        filename = os.fspath(filename)
+        if not os.path.isfile(filename):
+            raise FileNotFoundError(f"Input file not found: {filename}")
+        data: dict = {}
+        with open(filename, "r") as fh:
+            for lineno, line in enumerate(fh, start=1):
+                stripped = line.strip()
+                if not stripped or stripped.startswith("#"):
+                    continue
+                if ":" not in stripped:
+                    logger.warning(
+                        "%s line %d: skipping unrecognised line: %r",
+                        filename,
+                        lineno,
+                        stripped,
+                    )
+                    continue
+                key, _, value = stripped.partition(":")
+                key = key.strip().lower()
+                value = value.strip()
+                if key == "area":
+                    data[key] = [float(x) for x in value.split(",")]
+                elif key == "time":
+                    data[key] = value
+                else:
+                    try:
+                        data[key] = int(value)
+                    except ValueError:
+                        data[key] = value
+        return cls(**data)
+
+    @classmethod
+    def from_datetime(
+        cls,
+        dt: Union[str, _dt.datetime],
+        area: Sequence[float],
+    ) -> "HindcastConfig":
+        """Construct a :class:`HindcastConfig` from a datetime-like object and area.
+
+        Parameters
+        ----------
+        dt:
+            The date/time of the hindcast snapshot.  Accepted types are:
+
+            * ``str`` – ISO-format string (e.g. ``"2020-08-26"``,
+              ``"2020-08-26 00:00"``).  When :mod:`pandas` is available,
+              any string parseable by :class:`pandas.Timestamp` is accepted;
+              otherwise :func:`datetime.datetime.fromisoformat` is used.
+            * :class:`datetime.datetime` or :class:`pandas.Timestamp`
+              (which is a subclass of :class:`datetime.datetime`).
+
+        area:
+            Sequence of four floats ``[lat_max, lon_min, lat_min, lon_max]``.
+
+        Returns
+        -------
+        HindcastConfig
+        """
+        if isinstance(dt, str):
+            try:
+                import pandas as pd  # preferred: handles non-ISO formats too
+                dt = pd.Timestamp(dt)
+            except ImportError:
+                # Fallback for environments without pandas: accept ISO format strings
+                dt = _dt.datetime.fromisoformat(dt)
+        # At this point dt is a datetime.datetime (pd.Timestamp inherits from it)
+        if not isinstance(dt, _dt.datetime):
+            raise TypeError(
+                f"dt must be a str, datetime.datetime, or pandas.Timestamp; got {type(dt)!r}"
+            )
+        time_str = f"{dt.hour:02d}:{dt.minute:02d}"
+        return cls(
+            year=int(dt.year),
+            month=int(dt.month),
+            day=int(dt.day),
+            time=time_str,
+            area=list(area),
+        )
+
+    def validate(self) -> None:
+        """Validate the parsed configuration values.
+
+        Raises
+        ------
+        ValueError
+            If any required field is missing or any value is out of range.
+        """
+        for field_name in ("year", "month", "day", "time", "area"):
+            if getattr(self, field_name, None) is None:
+                raise ValueError(f"Missing required field: {field_name}")
+        if len(self.area) != 4:
+            raise ValueError(
+                "'area' must have exactly 4 values: lat_max, lon_min, lat_min, lon_max"
+            )
+        lat_max, lon_min, lat_min, lon_max = self.area
+        if lat_max <= lat_min:
+            raise ValueError(
+                "area: lat_max (1st value) must be greater than lat_min (3rd value)"
+            )
+        if lon_max <= lon_min:
+            raise ValueError(
+                "area: lon_max (4th value) must be greater than lon_min (2nd value)"
+            )