microstructure-tpw 0.3.0__py3-none-any.whl

odas_tpw/rsi/combine.py

@@ -0,0 +1,120 @@
+"""Combine binned profiles into a single dataset (L6)."""
+
+from __future__ import annotations
+
+import numpy as np
+import xarray as xr
+
+# Sub-bin tolerance (dbar) for collapsing ULP-distinct-but-equal bin centers.
+# Far below any real bin spacing (>= ~0.1 dbar) yet far above float ULP noise
+# (~1e-11 dbar at 100 dbar), so genuine bins stay distinct while accumulation
+# error in per-profile np.arange grids is merged.
+_DEPTH_ATOL = 1.0e-6
+
+
+def _depth_key(d: float) -> int:
+    """Quantize a depth-bin center onto the shared canonical grid."""
+    return round(float(d) / _DEPTH_ATOL)
+
+
+def combine_profiles(
+    binned_datasets: list[xr.Dataset],
+    profile_metadata: list[dict] | None = None,
+) -> xr.Dataset:
+    """Combine binned profiles into a multi-profile dataset.
+
+    Aligns all profiles to a common depth grid (union of bin centers).
+    Output dimensions: ``(profile, depth_bin)``. NaN where a profile
+    doesn't cover a depth.
+
+    Parameters
+    ----------
+    binned_datasets : list of xr.Dataset
+        Per-profile binned datasets (from ``bin_by_depth``).
+    profile_metadata : list of dict, optional
+        Metadata for each profile (start_time, file, etc.).
+
+    Returns
+    -------
+    xr.Dataset with dimensions ``(profile, depth_bin)``.
+    """
+    if not binned_datasets:
+        return xr.Dataset()
+
+    # Build common depth grid (union of all bin centers). Each profile builds
+    # its own np.arange center grid, so when bin_size is not binary-exact
+    # (e.g. 0.1, 0.2) two profiles produce mathematically-equal centers that
+    # differ by an ULP (0.35 vs 0.35000000000000003). Key the union on a
+    # quantized center (sub-bin tolerance) so those collapse to one column
+    # instead of splitting one physical depth into two half-NaN columns.
+    canon: dict[int, float] = {}
+    for ds in binned_datasets:
+        if "depth_bin" in ds.coords:
+            for d in ds.coords["depth_bin"].values.tolist():
+                canon.setdefault(_depth_key(d), d)
+
+    if not canon:
+        return xr.Dataset()
+
+    items = sorted(canon.items(), key=lambda kv: kv[1])
+    common_depths = np.array([v for _, v in items])
+    key_to_idx = {k: i for i, (k, _) in enumerate(items)}
+    n_profiles = len(binned_datasets)
+    n_depths = len(common_depths)
+
+    # Collect all variable names
+    var_names: set[str] = set()
+    for ds in binned_datasets:
+        var_names.update(str(v) for v in ds.data_vars)
+
+    data_vars = {}
+    for var in sorted(var_names):
+        combined = np.full((n_profiles, n_depths), np.nan)
+        var_attrs: dict = {}
+        for i, ds in enumerate(binned_datasets):
+            if var not in ds.data_vars:
+                continue
+            if not var_attrs:
+                # Carry CF units/long_name/standard_name from the L5 binned
+                # source so the L6 combined product is not metadata-free.
+                var_attrs = dict(ds[var].attrs)
+            ds_depths = ds.coords["depth_bin"].values
+            ds_vals = ds[var].values
+            for j, d in enumerate(ds_depths):
+                idx = key_to_idx.get(_depth_key(d))
+                if idx is not None:
+                    combined[i, idx] = ds_vals[j]
+        data_vars[var] = (["profile", "depth_bin"], combined, var_attrs)
+
+    coords = {
+        "profile": np.arange(n_profiles),
+        "depth_bin": common_depths,
+    }
+
+    result = xr.Dataset(data_vars, coords=coords)
+    result.coords["depth_bin"].attrs.update(
+        {
+            "units": "dbar",
+            "long_name": "depth bin center pressure",
+            "standard_name": "sea_water_pressure",
+            "positive": "down",
+        }
+    )
+    result.coords["profile"].attrs["long_name"] = "profile number"
+
+    # CF/ACDD global attrs: the L6 headline product previously advertised no
+    # convention conformance (empty .attrs), unlike every other writer, so a
+    # CF/ACDD consumer could not validate it. L6 is a set of profiles on a
+    # shared depth grid -> CF §9 featureType "profile" (audit: missing
+    # Conventions/featureType on combined product).
+    result.attrs["Conventions"] = "CF-1.13, ACDD-1.3"
+    result.attrs["featureType"] = "profile"
+
+    # Attach metadata
+    if profile_metadata:
+        for i, meta in enumerate(profile_metadata):
+            for key, val in meta.items():
+                attr_name = f"profile_{i}_{key}"
+                result.attrs[attr_name] = str(val)
+
+    return result

odas_tpw/rsi/config.py

@@ -0,0 +1,126 @@
+# Mar-2026, Claude and Pat Welch, pat@mousebrains.com
+"""YAML configuration file support for rsi-tpw.
+
+Provides loading, validation, three-way merge (defaults <- config <- CLI),
+deterministic hashing, and sequential output directory management.
+
+All config management logic lives in :mod:`odas_tpw.config_base.ConfigManager`;
+this module defines rsi-specific DEFAULTS, instantiates the manager, and
+re-exports the methods as module-level functions for backward compatibility.
+"""
+
+from pathlib import Path
+
+from odas_tpw.config_base import ConfigManager, _normalize_value  # noqa: F401
+
+# ---------------------------------------------------------------------------
+# Canonical defaults — one dict per processing section
+# ---------------------------------------------------------------------------
+
+DEFAULTS: dict[str, dict] = {
+    "profiles": {
+        "P_min": 0.5,
+        "W_min": 0.3,
+        "direction": "auto",
+        "vehicle": None,
+        "min_duration": 7.0,
+    },
+    "epsilon": {
+        "fft_length": 1024,
+        "diss_length": None,
+        "overlap": None,
+        "speed": None,
+        "direction": "auto",
+        "vehicle": None,
+        "goodman": True,
+        "f_AA": 98.0,
+        "f_limit": None,
+        "fit_order": 3,
+        "despike_thresh": 8,
+        "despike_smooth": 0.5,
+        "salinity": None,
+    },
+    "chi": {
+        "fft_length": 1024,
+        "diss_length": None,
+        "overlap": None,
+        "speed": None,
+        "direction": "auto",
+        "vehicle": None,
+        "fp07_model": "single_pole",
+        "goodman": True,
+        "f_AA": 98.0,
+        "fit_method": "iterative",
+        "spectrum_model": "kraichnan",
+        "salinity": None,
+    },
+}
+
+_mgr = ConfigManager(DEFAULTS)
+
+# Re-export manager methods as module-level functions
+load_config = _mgr.load_config
+validate_config = _mgr.validate_config
+merge_config = _mgr.merge_config
+canonicalize = _mgr.canonicalize
+compute_hash = _mgr.compute_hash
+resolve_output_dir = _mgr.resolve_output_dir
+write_signature = _mgr.write_signature
+write_resolved_config = _mgr.write_resolved_config
+
+# Also keep _VALID_SECTIONS for any direct references
+_VALID_SECTIONS = _mgr.valid_sections
+
+
+# ---------------------------------------------------------------------------
+# Template generation
+# ---------------------------------------------------------------------------
+
+_TEMPLATE = """\
+# rsi-tpw configuration
+# Values shown are the defaults. Uncomment and edit to customize.
+# CLI flags override values in this file.
+
+profiles:
+  P_min: 0.5            # minimum pressure [dbar]
+  W_min: 0.3            # minimum fall rate [dbar/s]
+  direction: auto       # profile direction: auto, up, down, glide, horizontal
+  vehicle: null         # vehicle override (null = from .p file)
+  min_duration: 7.0     # minimum profile duration [s]
+
+epsilon:
+  fft_length: 1024      # FFT segment length [samples]
+  diss_length: null     # dissipation window [samples] (null = 4 * fft_length)
+  overlap: null         # window overlap [samples] (null = diss_length // 2)
+  speed: null           # profiling speed [m/s] (null = from dP/dt)
+  direction: auto       # profile direction: auto, up, down, glide, horizontal
+  vehicle: null         # vehicle override (null = from .p file)
+  goodman: true         # Goodman coherent noise removal
+  f_AA: 98.0            # anti-aliasing filter cutoff [Hz]
+  f_limit: null         # upper frequency limit [Hz] (null = f_AA)
+  fit_order: 3          # polynomial fit order for Nasmyth integration
+  despike_thresh: 8     # despike threshold (rectified-HP / LP-envelope ratio, not MAD)
+  despike_smooth: 0.5   # despike envelope low-pass cutoff [Hz]
+  salinity: null        # salinity [PSU] (null = 35, fixed S)
+
+chi:
+  fft_length: 1024      # FFT segment length [samples]
+  diss_length: null     # dissipation window [samples] (null = 4 * fft_length)
+  overlap: null         # window overlap [samples] (null = diss_length // 2)
+  speed: null           # profiling speed [m/s] (null = from dP/dt)
+  direction: auto       # profile direction: auto, up, down, glide, horizontal
+  vehicle: null         # vehicle override (null = from .p file)
+  fp07_model: single_pole  # FP07 transfer function: single_pole or double_pole
+  goodman: true         # Goodman coherent noise removal
+  f_AA: 98.0            # anti-aliasing filter cutoff [Hz]
+  fit_method: iterative # Method 2 fitting: iterative or mle
+  spectrum_model: kraichnan  # theoretical spectrum: batchelor or kraichnan
+  salinity: null        # salinity [PSU] (null = 35, fixed S)
+"""
+
+
+def generate_template(path: str | Path) -> Path:
+    """Write a fully-commented template configuration file."""
+    path = Path(path)
+    path.write_text(_TEMPLATE)
+    return path