gagely 0.1.0__py3-none-any.whl

gagely/__init__.py

@@ -0,0 +1,11 @@
+try:
+    from ._version import version as __version__
+except ImportError:
+    try:
+        from importlib.metadata import version
+
+        __version__ = version("gagely")
+    except Exception:
+        __version__ = "0.0.0"
+
+__all__ = ["__version__"]

gagely/_dss_utils.py

@@ -0,0 +1,106 @@
+"""Shared DSS interval-inference and gap-fill helpers.
+
+Used by both ``gagely.usgs`` and ``gagely.contrail`` so that interval
+detection lives in one place.
+"""
+
+import logging
+from datetime import datetime
+from typing import List, Optional, Tuple
+
+import pandas as pd
+from pydsstools.core import DssPathName, UNDEFINED
+
+__all__: List[str] = []
+
+
+def _infer_interval_seconds(times: pd.Series) -> Optional[int]:
+    """Return the modal sampling interval in seconds across all of *times*.
+
+    Computes consecutive diffs over the full sorted series and returns the
+    most common diff in seconds. Logs a warning if more than one unique
+    diff is found.
+
+    Returns ``None`` if fewer than 2 samples are available.
+    """
+    if len(times) < 2:
+        return None
+    diffs = times.sort_values().diff().dropna()
+    if diffs.empty:
+        return None
+    counts = diffs.value_counts()
+    modal_diff = counts.index[0]
+    modal_seconds = int(modal_diff.total_seconds())
+    if len(counts) > 1:
+        anomalies = [
+            (int(d.total_seconds()), int(c))
+            for d, c in counts.iloc[1:4].items()
+        ]
+        logging.warning(
+            "Non-uniform intervals: modal=%ds (%d/%d rows); top anomalies %s",
+            modal_seconds, int(counts.iloc[0]), int(counts.sum()), anomalies,
+        )
+    return modal_seconds
+
+
+def _infer_interval_epart(times: pd.Series) -> Optional[str]:
+    """Return the DSS E-part string for the modal interval in *times*, or ``None``."""
+    seconds = _infer_interval_seconds(times)
+    if seconds is None:
+        return None
+    return DssPathName.interval_to_epart(seconds)
+
+
+_FILL_PROFILES = ("undefined", "ffill", "bfill", "interpolate")
+
+
+def _densify_timeseries(
+    times: List[datetime],
+    values: List[float],
+    interval_seconds: int,
+    profile: str = "undefined",
+) -> Tuple[List[datetime], List[float]]:
+    """Reindex a (times, values) pair onto a regular *interval_seconds* grid.
+
+    Gap slots are filled according to *profile*:
+
+    - ``"undefined"`` (default): stamp ``UNDEFINED`` (-9999.0).
+    - ``"ffill"``: forward-fill from the last known value; leading gaps → UNDEFINED.
+    - ``"bfill"``: backward-fill from the next known value; trailing gaps → UNDEFINED.
+    - ``"interpolate"``: linear interpolation between bounding values; edge gaps → UNDEFINED.
+
+    The grid is bounded by ``min(times)`` and ``max(times)``; the caller's
+    requested window is not padded.
+
+    Returns a new ``(times, values)`` pair sorted by time.
+    """
+    if profile not in _FILL_PROFILES:
+        raise ValueError(f"profile must be one of {_FILL_PROFILES!r}, got {profile!r}")
+
+    s = pd.Series(values, index=pd.to_datetime(times), name="value").sort_index()
+    s = s[~s.index.duplicated(keep="first")]
+
+    diffs = s.index.to_series().diff().dropna()
+    if (diffs == pd.Timedelta(seconds=interval_seconds)).all():
+        return s.index.to_pydatetime().tolist(), s.tolist()
+
+    target = pd.date_range(
+        start=s.index.min(), end=s.index.max(), freq=f"{interval_seconds}s"
+    )
+
+    if profile == "undefined":
+        densified = s.reindex(target, fill_value=UNDEFINED)
+    elif profile == "ffill":
+        densified = s.reindex(target).ffill().fillna(UNDEFINED)
+    elif profile == "bfill":
+        densified = s.reindex(target).bfill().fillna(UNDEFINED)
+    else:  # interpolate
+        densified = s.reindex(target).interpolate(method="time").fillna(UNDEFINED)
+
+    n_filled = len(densified) - len(s)
+    if n_filled > 0:
+        logging.debug(
+            "_densify_timeseries: filled %d / %d slots (profile=%r)",
+            n_filled, len(densified), profile,
+        )
+    return densified.index.to_pydatetime().tolist(), densified.tolist()

gagely/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None