microstructure-tpw 0.3.0__py3-none-any.whl

odas_tpw/perturb/binning.py

@@ -0,0 +1,761 @@
+# Mar-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Depth/time binning engine for profiles, dissipation, and chi.
+
+Reference: Code/bin_by_real.m, Code/profile2binned.m, Code/diss2binned.m,
+           Code/chi2binned.m
+"""
+
+import logging
+import re
+from concurrent.futures import ProcessPoolExecutor
+from pathlib import Path
+
+import numpy as np
+import xarray as xr
+
+from odas_tpw.perturb.logging_setup import stage_log
+
+logger = logging.getLogger(__name__)
+
+# Per-profile NetCDFs are named ``<pfile_stem>_prof###.nc`` by
+# :func:`odas_tpw.rsi.profile.extract_profiles`.  The binning step's
+# per-input-file log scope groups them back by source .p file rather than
+# splitting one log per profile, so we strip the suffix to recover the
+# .p stem.  Inputs that don't match the pattern (third-party NetCDFs,
+# already-binned outputs) keep their full stem.
+_PROF_SUFFIX_RE = re.compile(r"_prof\d+$")
+
+
+def _source_stem(profile_file: Path | str) -> str:
+    """Return the source ``.p``-file stem for a per-profile NetCDF path."""
+    return _PROF_SUFFIX_RE.sub("", Path(profile_file).stem)
+
+
+def _bin_indices(coords: np.ndarray, bin_edges: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Bin indices plus an in-range mask.
+
+    Samples with NaN coordinates (np.digitize returns len(edges)) or
+    coordinates outside the bin range are EXCLUDED via the mask — the
+    previous np.clip silently dumped them into the first/last bin.
+    Bins are half-open [lo, hi) except the last, which includes its
+    upper edge.
+    """
+    n_bins = len(bin_edges) - 1
+    with np.errstate(invalid="ignore"):
+        idx = np.digitize(coords, bin_edges) - 1
+        idx = np.where(coords == bin_edges[-1], n_bins - 1, idx)
+    in_range = np.isfinite(coords) & (idx >= 0) & (idx < n_bins)
+    return idx, in_range
+
+
+def _bin_std(values: np.ndarray, coords: np.ndarray, bin_edges: np.ndarray) -> np.ndarray:
+    """NaN-aware std-per-bin via bincount (population std, ddof=0).
+
+    Equivalent to a per-bin ``np.nanstd`` loop, but avoids the
+    O(n_bins * n_samples) mask broadcast.
+    """
+    n_bins = len(bin_edges) - 1
+    idx, in_range = _bin_indices(coords, bin_edges)
+    finite = in_range & np.isfinite(values)
+    idx_f = idx[finite]
+    vals_f = values[finite]
+    counts = np.bincount(idx_f, minlength=n_bins)
+    sums = np.bincount(idx_f, weights=vals_f, minlength=n_bins)
+    sums_sq = np.bincount(idx_f, weights=vals_f * vals_f, minlength=n_bins)
+    with np.errstate(invalid="ignore", divide="ignore"):
+        means = np.where(counts > 0, sums / np.maximum(counts, 1), 0.0)
+        var = sums_sq / np.maximum(counts, 1) - means * means
+        var = np.maximum(var, 0.0)  # cancellation safety
+        std = np.where(counts > 1, np.sqrt(var), np.nan)
+    return std
+
+
+def _bin_array(
+    values: np.ndarray,
+    coords: np.ndarray,
+    bin_edges: np.ndarray,
+    agg_func,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Core binning: assign values to bins and aggregate.
+
+    Parameters
+    ----------
+    values : ndarray, 1D
+    coords : ndarray, 1D (same length as values)
+    bin_edges : ndarray, 1D (n_bins + 1)
+    agg_func : callable (e.g. np.nanmean, np.nanmedian)
+
+    Returns
+    -------
+    binned : ndarray, shape (n_bins,)
+    counts : ndarray, shape (n_bins,) — int, in-range samples per bin
+        (independent of value finiteness; see _bin_finite_counts).
+    """
+    n_bins = len(bin_edges) - 1
+    idx, in_range = _bin_indices(coords, bin_edges)
+    idx = idx[in_range]
+    values = values[in_range]
+
+    counts = np.bincount(idx, minlength=n_bins).astype(int)
+
+    if agg_func is np.nanmean:
+        # Vectorize the dominant case: NaN-aware mean via two bincounts.
+        finite = np.isfinite(values)
+        idx_f = idx[finite]
+        vals_f = values[finite]
+        sums = np.bincount(idx_f, weights=vals_f, minlength=n_bins)
+        finite_counts = np.bincount(idx_f, minlength=n_bins)
+        with np.errstate(invalid="ignore", divide="ignore"):
+            binned = np.where(finite_counts > 0, sums / finite_counts, np.nan)
+        return binned, counts
+
+    # General fallback (e.g. nanmedian): sort once, then each bin is a
+    # contiguous slice — avoids the per-bin O(n_samples) mask broadcast.
+    order = np.argsort(idx, kind="stable")
+    sorted_idx = idx[order]
+    sorted_vals = values[order]
+    splits = np.searchsorted(sorted_idx, np.arange(n_bins + 1))
+    binned = np.full(n_bins, np.nan)
+    for i in range(n_bins):
+        sl = sorted_vals[splits[i] : splits[i + 1]]
+        if sl.size > 0:
+            binned[i] = agg_func(sl)
+    return binned, counts
+
+
+def _bin_finite_counts(
+    values: np.ndarray, coords: np.ndarray, bin_edges: np.ndarray
+) -> np.ndarray:
+    """Per-bin count of finite values — the effective averaging N.
+
+    After QC NaN'ing, the in-range sample count overstates how many
+    values actually entered a bin mean; this is the honest N for
+    weighting bins or building confidence intervals.
+    """
+    n_bins = len(bin_edges) - 1
+    idx, in_range = _bin_indices(coords, bin_edges)
+    finite = in_range & np.isfinite(values)
+    return np.bincount(idx[finite], minlength=n_bins).astype(int)
+
+
+def _bin_or(values: np.ndarray, coords: np.ndarray, bin_edges: np.ndarray) -> np.ndarray:
+    """Bitwise-OR pooling per bin for QC flag bitfields.
+
+    Arithmetic averaging of flag bits produces meaningless fractional
+    values; the OR of all in-bin flags preserves "any sample in this bin
+    was flagged with bit X".  Empty bins are NaN.
+    """
+    n_bins = len(bin_edges) - 1
+    idx, in_range = _bin_indices(coords, bin_edges)
+    idx_v = idx[in_range]
+    vals_v = values[in_range].astype(np.int64)
+    pooled = np.zeros(n_bins, dtype=np.int64)
+    np.bitwise_or.at(pooled, idx_v, vals_v)
+    counts = np.bincount(idx_v, minlength=n_bins)
+    return np.where(counts > 0, pooled.astype(float), np.nan)
+
+
+def _get_agg_func(aggregation: str):
+    """Return the aggregation function for the given method name."""
+    if aggregation == "median":
+        return np.nanmedian
+    return np.nanmean
+
+
+def _time_to_seconds(values: np.ndarray) -> np.ndarray:
+    """Convert numeric or decoded CF time values to float seconds.
+
+    Numeric arrays are already treated as seconds.  ``datetime64`` arrays are
+    converted to Unix epoch seconds, giving CF time variables with different
+    ``seconds since ...`` origins a common basis before bin-edge arithmetic.
+    """
+    arr = np.asarray(values)
+    if arr.dtype.kind == "M":
+        ns = arr.astype("datetime64[ns]").astype("int64")
+        seconds = ns.astype(float) / 1e9
+        seconds[ns == np.iinfo(np.int64).min] = np.nan
+        return seconds
+    if arr.dtype.kind in ("f", "i", "u"):
+        return arr.astype(float)
+    try:
+        dt = arr.astype("datetime64[ns]")
+    except (TypeError, ValueError):
+        return np.full(arr.shape, np.nan, dtype=float)
+    ns = dt.astype("int64")
+    seconds = ns.astype(float) / 1e9
+    seconds[ns == np.iinfo(np.int64).min] = np.nan
+    return seconds
+
+
+_SCALAR_NAMES = ("lat", "lon", "stime", "etime")
+
+
+_DEPTH_CANDIDATES = ("depth", "P", "P_mean")
+
+# Latitude used to convert pressure -> depth when a profile carries no ``lat``.
+# gsw.z_from_p's latitude (gravity) dependence is ~3 m at 1000 dbar between the
+# equator and the poles; a mid-latitude default halves that worst-case error
+# (~+/-1.5 m) vs assuming the equator or a pole. Profiles from the perturb
+# pipeline normally carry their GPS ``lat``, so this fallback is rarely used.
+_DEFAULT_BIN_LATITUDE = 45.0
+
+
+def _decoded(var) -> np.ndarray:
+    """Read a ``netCDF4`` variable applying CF mask + scale, fill/missing -> NaN.
+
+    With CF decoding on (see :func:`_load_profile_snapshot`), ``var[:]`` returns a
+    scaled, masked array whenever the variable carries ``_FillValue`` /
+    ``missing_value`` or ``scale_factor`` / ``add_offset``.  We convert masked
+    cells to NaN (``np.ma.filled``) so packed or sentinel-filled *float* data are
+    decoded to physical values instead of being binned as raw counts / fill
+    sentinels.  (2026-07-03 review, GPT-5.5 F2.)
+
+    Exception — plain (non-packed) integer flag bitfields such as ``qc_drop_*``
+    are read RAW, bypassing CF mask/scale.  netCDF4's auto-mask masks any cell
+    equal to the type's *default* fill (255 for ``uint8``) even with no explicit
+    ``_FillValue`` — but 255 is a legal bitfield value (all 8 flags set), and
+    masking it would widen the array to float and defeat the uint OR-pool in
+    :func:`_bin_snapshot` (a bitfield must never be averaged).  Reading these raw
+    preserves the integer dtype and the exact pre-CF-decode values, so their
+    binning is unchanged; only genuinely packed integers (which carry
+    ``scale_factor`` / ``add_offset`` and decode to physical floats) fall through
+    to the float path.  (2026-07-03 adversarial review of F2.)
+    """
+    attrs = var.ncattrs()
+    packed = "scale_factor" in attrs or "add_offset" in attrs
+    if var.dtype.kind in ("u", "i") and not packed:
+        var.set_auto_maskandscale(False)  # per-var override of the dataset default
+        return np.asarray(var[:])
+
+    arr = var[:]
+    # netCDF4 returns a MaskedArray under CF decoding even when nothing is
+    # masked; only widen to float64+NaN when cells are actually filled.
+    if np.ma.isMaskedArray(arr) and np.ma.count_masked(arr):
+        return np.asarray(np.ma.filled(arr.astype(np.float64), np.nan))
+    return np.asarray(arr)
+
+
+# Data-variable attributes carried through binning to the combo. Binning
+# otherwise drops all data-var attrs (they are recreated from the static schema
+# at combo time), which would discard per-run provenance like the in-situ FP07
+# calibration tag. Only this curated set survives, so the combo does not gain a
+# flood of source attrs — schema-controlled keys (units/long_name/...) are
+# unaffected. Extend when another provenance attr needs to reach the products.
+#
+# flag_meanings / flag_masks are the CF bitfield metadata written on the
+# qc_drop_epsilon / qc_drop_chi flags (qc_gate.py); without them the combo's qc
+# field is an attr-less integer whose bits cannot be decoded. combo's
+# apply_schema only *adds* schema keys (it never clears existing attrs), so
+# preserving them here carries them to the product. One caveat: make_combo's
+# xr.concat uses the default combine_attrs="override" (per-variable attrs come
+# from the FIRST binned file), so in the normal homogeneous case (every source
+# QC'd identically) they survive, but a heterogeneous run whose first-sorted
+# source lacks the flags would drop them combo-wide. (#104 U5-3.)
+_PRESERVE_DATAVAR_ATTRS: frozenset[str] = frozenset({"calibration", "flag_meanings", "flag_masks"})
+
+
+def _load_profile_snapshot(profile_file: Path) -> dict | None:
+    """Read a profile NC once and return a snapshot for binning.
+
+    Returned dict (or None when the file has no depth/P/P_mean variable):
+
+    * ``depth`` — 1-D ndarray of the depth/P/P_mean coordinate
+    * ``vars`` — ``{var_name: 1-D ndarray}`` for every numeric data var
+      that aligns with depth
+    * ``scalars`` — ``{lat|lon|stime|etime: float}`` (epoch seconds for time)
+    * ``scalar_attrs`` — ``{name: attrs_dict}`` (units/calendar stripped — the
+      combo's CF encoder re-emits them on write)
+    * ``var_attrs`` — ``{var_name: attrs_dict}`` for the curated
+      :data:`_PRESERVE_DATAVAR_ATTRS` carried through to the combo
+
+    Implementation note: we open with raw ``netCDF4.Dataset`` rather
+    than ``xr.open_dataset`` here.  xarray's per-open overhead
+    (file-manager cache lookup, variable wrapping, dim/coord
+    establishment) dominated the per-call cost and we don't need any
+    of it — we read a fixed shape of float arrays plus four scalars.
+    Time variables are filtered out via the CF ``units`` convention
+    (' since ' substring).  CF mask + scale decoding is left ON (the
+    ``netCDF4`` default): reads go through :func:`_decoded`, so
+    ``_FillValue`` / ``missing_value`` cells become NaN and
+    ``scale_factor`` / ``add_offset`` packing is applied.  This matches
+    xarray's ``decode_cf=True`` path — external, packed, or
+    partially-written files bin their physical values, not raw sentinels
+    or packed integer counts.
+    """
+    import netCDF4 as nc
+
+    ds = nc.Dataset(str(profile_file), "r")
+    try:
+        ds.set_auto_maskandscale(True)  # CF decode; _decoded fills masked -> NaN
+
+        depth_var = next(
+            (n for n in _DEPTH_CANDIDATES if n in ds.variables), None
+        )
+        if depth_var is None:
+            return None
+        depth = _decoded(ds.variables[depth_var])
+
+        scalars: dict[str, float] = {}
+        scalar_attrs: dict[str, dict] = {}
+        for sname in _SCALAR_NAMES:
+            if sname not in ds.variables:
+                continue
+            sv = ds.variables[sname]
+            if sv.shape != ():
+                continue
+            # Fill-safe: a masked/filled scalar becomes NaN rather than crashing
+            # float() or reading a raw sentinel as a real lat/lon/time.
+            scalars[sname] = float(np.ma.filled(np.ma.asarray(sv[()]), np.nan))
+            scalar_attrs[sname] = {
+                a: getattr(sv, a)
+                for a in sv.ncattrs()
+                if a not in ("units", "calendar")
+            }
+
+        # The bin coordinate must be depth in METERS. A true 'depth' variable is
+        # already meters (TEOS-10, lat-aware) and used as-is; a pressure fallback
+        # (dbar) is converted via gsw.z_from_p using the profile's own latitude
+        # when present, else the mid-latitude default (see _DEFAULT_BIN_LATITUDE).
+        if depth_var in ("P", "P_mean"):
+            import gsw
+
+            _lat = scalars.get("lat")
+            if _lat is None or not np.isfinite(_lat):
+                _lat = _DEFAULT_BIN_LATITUDE
+            depth = -np.asarray(gsw.z_from_p(np.asarray(depth, dtype=float), _lat), dtype=float)
+
+        n_depth = len(depth)
+        data: dict[str, np.ndarray] = {}
+        var_attrs: dict[str, dict] = {}
+        for vname, var in ds.variables.items():
+            if vname == depth_var or vname in _SCALAR_NAMES:
+                continue
+            shape = var.shape
+            if len(shape) != 1 or shape[0] != n_depth:
+                continue
+            # Skip CF coordinate variables (e.g. ``probe`` on the ``probe``
+            # dim) — netCDF4 lists them alongside data vars, while xarray
+            # promotes them to coords.  The previous xarray-based path
+            # was filtering them implicitly via ``ds.data_vars``.
+            if len(var.dimensions) == 1 and var.dimensions[0] == vname:
+                continue
+            # Skip time coordinate vars (t, t_slow) by CF units.
+            try:
+                units = var.getncattr("units")
+            except (AttributeError, KeyError):
+                units = ""
+            if isinstance(units, str) and " since " in units:
+                continue
+            # Skip non-numeric variables (string-typed labels, etc.).
+            if var.dtype.kind not in ("f", "i", "u"):
+                continue
+            data[str(vname)] = _decoded(var)
+            preserved = {a: getattr(var, a) for a in var.ncattrs()
+                         if a in _PRESERVE_DATAVAR_ATTRS}
+            if preserved:
+                var_attrs[str(vname)] = preserved
+    finally:
+        ds.close()
+
+    return {
+        "depth": depth,
+        "vars": data,
+        "scalars": scalars,
+        "scalar_attrs": scalar_attrs,
+        "var_attrs": var_attrs,
+    }
+
+
+def _bin_snapshot(snapshot: dict, bin_edges: np.ndarray, agg, diagnostics: bool) -> dict:
+    """Bin a pre-loaded snapshot onto *bin_edges* — no file IO.
+
+    Returns the same shape of dict that the previous ``_bin_one_profile``
+    produced (``vars``, ``stds``, ``scalars``, ``scalar_attrs``).
+    """
+    out: dict = {
+        "vars": {},
+        "stds": {},
+        "finite_counts": {},
+        "counts": None,
+        "scalars": snapshot["scalars"],
+        "scalar_attrs": snapshot["scalar_attrs"],
+        "var_attrs": snapshot.get("var_attrs", {}),
+    }
+    depth = snapshot["depth"]
+    for vname, arr in snapshot["vars"].items():
+        if arr.dtype.kind == "u":
+            # QC flag bitfields (uint dtype): OR-pool, never average.
+            out["vars"][vname] = _bin_or(arr, depth, bin_edges)
+            if out["counts"] is None:
+                _, counts = _bin_array(arr.astype(np.float64), depth, bin_edges, agg)
+                out["counts"] = counts
+            continue
+        if vname.endswith("LnSigma"):
+            # Standard deviations combine in quadrature: average the variances
+            # (RMS of sigma), not the sigmas. Use np.nanmean explicitly, NOT
+            # the dataset's `agg`: sqrt(mean(sigma^2)) is the RMS, but
+            # sqrt(median(sigma^2)) is not -- under median binning that
+            # square/root pair collapses to ~median(|sigma|) and silently
+            # mis-states the combined log-uncertainty.
+            binned_var, counts = _bin_array(
+                arr.astype(np.float64) ** 2, depth, bin_edges, np.nanmean
+            )
+            out["vars"][vname] = np.sqrt(binned_var)
+        else:
+            binned, counts = _bin_array(arr, depth, bin_edges, agg)
+            out["vars"][vname] = binned
+        if out["counts"] is None:
+            out["counts"] = counts
+        if diagnostics:
+            out["stds"][vname] = _bin_std(arr, depth, bin_edges)
+            out["finite_counts"][vname] = _bin_finite_counts(arr, depth, bin_edges)
+    return out
+
+
+def _bin_one_profile(
+    profile_file: Path,
+    bin_edges: np.ndarray,
+    agg,
+    diagnostics: bool,
+) -> dict:
+    """Open + bin a single profile NetCDF onto *bin_edges*.
+
+    Compatibility shim around :func:`_load_profile_snapshot` +
+    :func:`_bin_snapshot` for callers that want the old "one open, one
+    bin" behavior in a single function call.
+    """
+    snap = _load_profile_snapshot(profile_file)
+    if snap is None:
+        return {"vars": {}, "stds": {}, "scalars": {}, "scalar_attrs": {}, "var_attrs": {}}
+    return _bin_snapshot(snap, bin_edges, agg, diagnostics)
+
+
+# Top-level worker entrypoints — must be importable for spawn-style
+# multiprocessing (macOS default).  The thin tuple signatures keep the
+# Python pickle small: just file path + small numpy array + tiny config.
+
+
+def _bin_scan_worker(profile_file: Path) -> tuple[float, float] | None:
+    """Worker: read just enough of the file to report (min, max) depth."""
+    snap = _load_profile_snapshot(profile_file)
+    if snap is None:
+        return None
+    d = snap["depth"]
+    d = d[np.isfinite(d)]
+    if d.size == 0:
+        return None
+    return float(d.min()), float(d.max())
+
+
+def _bin_compute_worker(args: tuple) -> dict:
+    """Worker: load snapshot + bin onto pre-computed *bin_edges*."""
+    profile_file, bin_edges, aggregation, diagnostics = args
+    return _bin_one_profile(profile_file, bin_edges, _get_agg_func(aggregation), diagnostics)
+
+
+def bin_by_depth(
+    profile_files: list[Path],
+    bin_width: float = 1.0,
+    aggregation: str = "mean",
+    diagnostics: bool = False,
+    log_dir: Path | None = None,
+    jobs: int = 1,
+) -> xr.Dataset:
+    """Bin per-profile NetCDFs by depth into 2D (bin x profile).
+
+    Parameters
+    ----------
+    profile_files : list of Path
+        Paths to per-profile NetCDF files.
+    bin_width : float
+        Depth bin width [m].
+    aggregation : str
+        "mean" or "median".
+    diagnostics : bool
+        Include n_samples and *_std per bin.
+    log_dir : Path, optional
+        When supplied, the per-input-file binning loop is wrapped in
+        :func:`~odas_tpw.perturb.logging_setup.stage_log` so each source
+        file's records land in ``<log_dir>/<source_stem>.log`` (in
+        addition to the worker/run logs).
+    jobs : int, default 1
+        When > 1, dispatch the per-profile depth scan and the per-profile
+        load+bin onto a process pool of *jobs* workers. The two phases
+        share one ``ProcessPoolExecutor`` so spawn-fork overhead is paid
+        once.
+
+    Returns
+    -------
+    xr.Dataset with dims (bin, profile).
+
+    Notes
+    -----
+    Serial path (jobs <= 1): each file is read once into an in-memory
+    snapshot, the global bin grid is computed from cached depths, then
+    each snapshot is binned without further IO — single open per file.
+
+    Parallel path (jobs > 1): workers each open their share of files
+    twice (once for the scan, once for the bin); we accept that second
+    open in exchange for shipping just (min,max) tuples through pickle
+    in phase 1 instead of the full snapshot dicts.  For SN465-class
+    workloads this is dominated by phase 2 (load + bin) which scales
+    cleanly with worker count.
+    """
+    agg = _get_agg_func(aggregation)
+    n_profiles = len(profile_files)
+
+    # ---- Phase 1: scan depth ranges -------------------------------------
+    if jobs > 1 and n_profiles > 1:
+        with ProcessPoolExecutor(max_workers=jobs) as exe:
+            ranges = list(exe.map(_bin_scan_worker, profile_files))
+    else:
+        ranges = [_bin_scan_worker(f) for f in profile_files]
+
+    g_min = np.inf
+    g_max = -np.inf
+    saw_any = False
+    for r in ranges:
+        if r is None:
+            continue
+        saw_any = True
+        g_min = min(g_min, r[0])
+        g_max = max(g_max, r[1])
+    if not saw_any:
+        return xr.Dataset()
+
+    d_min = np.floor(g_min / bin_width) * bin_width
+    d_max = np.ceil(g_max / bin_width) * bin_width
+    # Defect fix: build edges from an integer bin count instead of
+    # np.arange(d_min, d_max + bin_width, bin_width).  For non-binary-exact
+    # bin_width (e.g. 0.7) np.arange's float accumulation can land the
+    # penultimate edge just below the stop and emit a spurious extra trailing
+    # bin past d_max, stealing the deepest boundary sample (round-then-arange).
+    n_edges = round(float((d_max - d_min) / bin_width)) + 1
+    bin_edges = d_min + np.arange(n_edges) * bin_width
+    bin_centers = (bin_edges[:-1] + bin_edges[1:]) / 2.0
+    n_bins = len(bin_centers)
+
+    # ---- Phase 2: load + bin --------------------------------------------
+    if jobs > 1 and n_profiles > 1:
+        args_iter = ((f, bin_edges, aggregation, diagnostics) for f in profile_files)
+        with ProcessPoolExecutor(max_workers=jobs) as exe:
+            results = list(exe.map(_bin_compute_worker, args_iter))
+    else:
+        results = [_bin_one_profile(f, bin_edges, agg, diagnostics) for f in profile_files]
+
+    result_vars: dict = {}
+    profile_scalars = {
+        "lat": np.full(n_profiles, np.nan),
+        "lon": np.full(n_profiles, np.nan),
+        "stime": np.full(n_profiles, np.nan),
+        "etime": np.full(n_profiles, np.nan),
+    }
+    profile_scalar_attrs: dict[str, dict] = {}
+    # Curated data-var attrs (e.g. the FP07 in-situ calibration tag) from the
+    # first profile that carries them; concat keeps the first anyway.
+    profile_var_attrs: dict[str, dict] = {}
+
+    for pi, (pfile, res) in enumerate(zip(profile_files, results)):
+        with stage_log(log_dir, _source_stem(pfile)):
+            if not res["vars"] and not res["scalars"]:
+                continue
+            for sname, val in res["scalars"].items():
+                profile_scalars[sname][pi] = val
+                if sname not in profile_scalar_attrs:
+                    profile_scalar_attrs[sname] = res["scalar_attrs"].get(sname, {})
+            for vname, binned in res["vars"].items():
+                if vname not in profile_var_attrs and res.get("var_attrs", {}).get(vname):
+                    profile_var_attrs[vname] = res["var_attrs"][vname]
+                if vname not in result_vars:
+                    result_vars[vname] = np.full((n_bins, n_profiles), np.nan)
+                    if diagnostics:
+                        result_vars[f"{vname}_std"] = np.full(
+                            (n_bins, n_profiles), np.nan
+                        )
+                        result_vars[f"{vname}_n"] = np.full(
+                            (n_bins, n_profiles), np.nan
+                        )
+                result_vars[vname][:, pi] = binned
+            if diagnostics:
+                for vname, std_arr in res["stds"].items():
+                    result_vars[f"{vname}_std"][:, pi] = std_arr
+                for vname, n_arr in res.get("finite_counts", {}).items():
+                    key = f"{vname}_n"
+                    if key in result_vars:
+                        result_vars[key][:, pi] = n_arr
+
+    if diagnostics:
+        counts = np.zeros((n_bins, n_profiles), dtype=float)
+        for pi, res in enumerate(results):
+            if res.get("counts") is not None:
+                counts[:, pi] = res["counts"]
+        result_vars["n_samples"] = counts
+
+    data_vars: dict = {}
+    for vname, arr in result_vars.items():
+        attrs = profile_var_attrs.get(vname, {})
+        data_vars[str(vname)] = (
+            (["bin", "profile"], arr, attrs) if attrs else (["bin", "profile"], arr)
+        )
+
+    # Emit per-profile scalars as 1-D vars on the profile dim, only when at
+    # least one profile actually carried them (preserves backward
+    # compatibility with older per-profile NCs that lack lat/lon/stime/etime).
+    for sname, sarr in profile_scalars.items():
+        if np.any(np.isfinite(sarr)):
+            data_vars[sname] = (["profile"], sarr, profile_scalar_attrs.get(sname, {}))
+
+    return xr.Dataset(
+        data_vars,
+        coords={
+            "bin": bin_centers,
+            "profile": np.arange(n_profiles),
+        },
+    )
+
+
+def bin_by_time(
+    profile_files: list[Path],
+    bin_width: float = 1.0,
+    aggregation: str = "mean",
+    diagnostics: bool = False,
+    log_dir: Path | None = None,
+) -> xr.Dataset:
+    """Bin per-profile NetCDFs by time.
+
+    Returns a concatenated dataset along a time dimension.
+
+    See :func:`bin_by_depth` for the meaning of *log_dir*.
+
+    .. note::
+       Unlike :func:`bin_by_depth`, the *diagnostics* outputs
+       (``*_std`` / ``*_n`` / ``n_samples``) are not implemented for time
+       binning; only the binned means are written.  A one-time warning is
+       emitted when *diagnostics* is requested so the absence is not silent.
+    """
+    agg = _get_agg_func(aggregation)
+    if diagnostics:
+        # Time binning does not (yet) emit the per-bin std / finite-count /
+        # n_samples diagnostics that the depth path does. Warn once rather than
+        # silently honoring the flag with mean-only output (#40/#53).
+        logger.warning(
+            "bin_by_time: diagnostics outputs (*_std, *_n, n_samples) are not "
+            "produced for time binning; only the binned means are written"
+        )
+    all_binned = []
+
+    for f in profile_files:
+        with stage_log(log_dir, _source_stem(f)):
+            with xr.open_dataset(f) as ds:
+                # Use the time coordinate
+                for time_name in ("t_slow", "t_fast", "time"):
+                    if time_name in ds:
+                        t_raw = ds[time_name].values
+                        break
+                else:
+                    if diagnostics:
+                        logger.warning(
+                            "bin_by_time: %s has no time coordinate "
+                            "(t_slow/t_fast/time); dropping it from the binned output",
+                            f.name,
+                        )
+                    continue
+
+                t = _time_to_seconds(t_raw)
+                finite_t = np.isfinite(t)
+                if not finite_t.any():
+                    if diagnostics:
+                        logger.warning(
+                            "bin_by_time: %s has no finite times; dropping it from "
+                            "the binned output",
+                            f.name,
+                        )
+                    continue
+                t_min = float(np.nanmin(t[finite_t]))
+                t_max = float(np.nanmax(t[finite_t]))
+                # Integer-first edge count via CEIL (not round): avoids the
+                # np.arange float-stop spurious trailing bin while still
+                # guaranteeing the last edge >= t_max, so the final partial bin's
+                # samples are never silently dropped (round() truncated the span
+                # when its fractional part was < 0.5).
+                n_edges = int(np.ceil((t_max - t_min) / bin_width)) + 1
+                bin_edges = t_min + np.arange(n_edges) * bin_width
+                if len(bin_edges) < 2:
+                    bin_edges = np.array([t_min, t_min + bin_width])
+                bin_centers = (bin_edges[:-1] + bin_edges[1:]) / 2.0
+
+                binned_data = {"time": bin_centers}
+                for vname in ds.data_vars:
+                    arr = ds[vname].values
+                    if arr.ndim != 1 or len(arr) != len(t):
+                        continue
+                    if arr.dtype.kind == "M":  # skip datetime64 variables
+                        continue
+                    if arr.dtype.kind not in ("f", "i", "u"):
+                        continue
+                    # Match the depth-binning dispatch (_bin_snapshot): QC flag
+                    # bitfields OR-pool, LnSigma combines in quadrature, the rest
+                    # aggregate normally. Plain nanmean here would average flags
+                    # into fractional garbage and underestimate the sigmas.
+                    if arr.dtype.kind == "u":
+                        binned_data[str(vname)] = _bin_or(arr, t, bin_edges)
+                        continue
+                    if str(vname).endswith("LnSigma"):
+                        # Quadrature RMS requires the arithmetic mean of the
+                        # variances regardless of the dataset's `agg` (median
+                        # would break the sqrt(mean(sigma^2)) identity).
+                        bvar, _ = _bin_array(
+                            arr.astype(np.float64) ** 2, t, bin_edges, np.nanmean
+                        )
+                        binned_data[str(vname)] = np.sqrt(bvar)
+                        continue
+                    b, _ = _bin_array(arr, t, bin_edges, agg)
+                    binned_data[str(vname)] = b
+
+            if len(binned_data) > 1:
+                bds = xr.Dataset(
+                    {k: (["time"], v) for k, v in binned_data.items() if k != "time"},
+                    coords={"time": binned_data["time"]},
+                )
+                all_binned.append(bds)
+
+    if not all_binned:
+        return xr.Dataset()
+    return xr.concat(all_binned, dim="time")
+
+
+def bin_diss(
+    diss_files: list[Path],
+    bin_width: float = 1.0,
+    aggregation: str = "mean",
+    method: str = "depth",
+    diagnostics: bool = False,
+    log_dir: Path | None = None,
+    jobs: int = 1,
+) -> xr.Dataset:
+    """Bin dissipation estimates by depth or time.
+
+    Handles per-probe (e_1, e_2) and combined (epsilonMean) variables.
+    """
+    if method == "time":
+        return bin_by_time(diss_files, bin_width, aggregation, diagnostics, log_dir=log_dir)
+    return bin_by_depth(
+        diss_files, bin_width, aggregation, diagnostics, log_dir=log_dir, jobs=jobs
+    )
+
+
+def bin_chi(
+    chi_files: list[Path],
+    bin_width: float = 1.0,
+    aggregation: str = "mean",
+    method: str = "depth",
+    diagnostics: bool = False,
+    log_dir: Path | None = None,
+    jobs: int = 1,
+) -> xr.Dataset:
+    """Bin chi estimates by depth or time."""
+    if method == "time":
+        return bin_by_time(chi_files, bin_width, aggregation, diagnostics, log_dir=log_dir)
+    return bin_by_depth(
+        chi_files, bin_width, aggregation, diagnostics, log_dir=log_dir, jobs=jobs
+    )