oceanarray 0.1.0__py3-none-any.whl

oceanarray/plotters/_helpers.py

@@ -0,0 +1,57 @@
+"""Shared private helpers for the plotters package.
+
+Post-OdB: migrate the following from report/_plots.py:
+  _instrument_panels, _CANONICAL_PANELS, _COMPACT_PANEL_VARS,
+  _rose_ax, _ts_heatmap_panel, _add_sigma0_contours, _xyz_to_enu_2d.
+
+Also migrate _instrument_label from plotter.py.
+
+Note: _fig_to_base64 stays in report/_html_helpers.py (called only by
+Tier-3 wrappers in report/_plots.py; plotters/ never serialises to base64).
+
+See .claude/plotters_update-20260718.md for migration checklist.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def tukey_smooth(arr: np.ndarray, window_n: int) -> np.ndarray:
+    """Zero-phase Tukey (cosine-tapered) smooth, NaN-gap aware.
+
+    Uses a convolution-based approach so NaN gaps do not propagate: output
+    points near gaps are weighted only by the finite neighbours that fall
+    within the window.  Output is set to NaN where fewer than 10 % of the
+    window weights are finite (edges of large data gaps).
+
+    Requires ``scipy``.
+
+    Parameters
+    ----------
+    arr : np.ndarray
+        1-D array, possibly containing NaNs.
+    window_n : int
+        Window length in samples.
+
+    Returns
+    -------
+    np.ndarray
+        Smoothed array, same shape as *arr*.
+
+    """
+    from scipy.signal import windows as scipy_windows
+
+    if window_n < 3 or window_n >= len(arr):
+        return arr.copy()
+    win = scipy_windows.tukey(window_n, alpha=0.5)
+    win = win / win.sum()
+    finite = np.isfinite(arr)
+    smoothed = np.convolve(np.where(finite, arr, 0.0), win, mode="same")
+    wsum = np.convolve(finite.astype(float), win, mode="same")
+    with np.errstate(invalid="ignore"):
+        smoothed = np.where(wsum > 0.1, smoothed / wsum, np.nan)
+    return smoothed
+
+
+# TODO post-OdB: migrate from plotter.py / report/_plots.py

oceanarray/plotters/_primitives.py

@@ -0,0 +1,101 @@
+"""Tier-1 data-agnostic plotting primitives.
+
+These functions accept pre-processed arrays (not xarray Datasets) and have no
+knowledge of oceanographic variable naming conventions.  They are the lowest
+layer in the three-tier plotters architecture:
+
+  Tier 1: _primitives.py   — generic, array-in / Figure-out
+  Tier 2: _current.py etc. — domain wrappers (xr.Dataset-in / Figure-out)
+  Tier 3: report/_plots.py — thin wrappers (path-in / base64-out)
+
+Post-OdB: add plot_vector_heatmap, plot_section, plot_spectrum,
+plot_polar_histogram, plot_timeseries.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import matplotlib.colors as mcolors
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.collections import LineCollection
+
+from ..utilities import _nice_colorbar_bounds
+
+
+def plot_trajectory(
+    x: np.ndarray,
+    y: np.ndarray,
+    color_data: Optional[np.ndarray] = None,
+    cmap: str = "coolwarm",
+    xlabel: str = "East displacement (m)",
+    ylabel: str = "North displacement (m)",
+    colorbar_label: str = "",
+    title: str = "",
+) -> plt.Figure:
+    """Plot a 2D trajectory, optionally coloured per-segment by a scalar field.
+
+    When *color_data* is provided, segments are drawn as a LineCollection with
+    colours mapped through *cmap*.  When omitted, a plain line is drawn with
+    green and red markers at the start and end respectively.
+
+    Parameters
+    ----------
+    x, y : ndarray
+        Trajectory coordinates (same length).
+    color_data : ndarray, optional
+        Scalar values to map onto the line (same length as x/y).
+    cmap : str
+        Matplotlib colormap name used when color_data is provided.
+    xlabel, ylabel : str
+        Axis labels.
+    colorbar_label : str
+        Label for the colorbar (only shown when color_data is provided).
+    title : str
+        Figure title.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+
+    """
+    fig, ax = plt.subplots(figsize=(7, 6))
+
+    if color_data is not None:
+        points = np.array([x, y]).T.reshape(-1, 1, 2)
+        segments = np.concatenate([points[:-1], points[1:]], axis=1)
+        vmin = np.nanmin(color_data)
+        vmax = np.nanmax(color_data)
+        bounds = _nice_colorbar_bounds(vmin, vmax, n=20)
+        norm = mcolors.BoundaryNorm(bounds, ncolors=256)
+        lc = LineCollection(segments, cmap=cmap, norm=norm, linewidth=1.5)
+        lc.set_array(color_data[:-1])
+        ax.add_collection(lc)
+        fig.colorbar(lc, ax=ax, label=colorbar_label, shrink=0.8, ticks=bounds)
+        ax.set_xlim(
+            np.nanmin(x) - 0.05 * (np.nanmax(x) - np.nanmin(x) + 1),
+            np.nanmax(x) + 0.05 * (np.nanmax(x) - np.nanmin(x) + 1),
+        )
+        ax.set_ylim(
+            np.nanmin(y) - 0.05 * (np.nanmax(y) - np.nanmin(y) + 1),
+            np.nanmax(y) + 0.05 * (np.nanmax(y) - np.nanmin(y) + 1),
+        )
+    else:
+        ax.plot(x, y, color="steelblue", linewidth=1.5)
+
+    # Start/end markers
+    ax.plot(x[0], y[0], "o", color="green", markersize=8, label="Start", zorder=5)
+    ax.plot(x[-1], y[-1], "s", color="red", markersize=8, label="End", zorder=5)
+    ax.legend(fontsize=8)
+
+    ax.set_xlabel(xlabel)
+    ax.set_ylabel(ylabel)
+    if title:
+        ax.set_title(title)
+    ax.axhline(0, color="k", linewidth=0.5, linestyle="--", alpha=0.4)
+    ax.axvline(0, color="k", linewidth=0.5, linestyle="--", alpha=0.4)
+    ax.set_aspect("equal", adjustable="box")
+    ax.grid(True, linestyle="--", linewidth=0.5, alpha=0.4)
+    fig.tight_layout()
+    return fig

oceanarray/plotters/_section.py

@@ -0,0 +1,16 @@
+"""Tier-2 domain wrappers for time × pressure section plots.
+
+Post-OdB: migrate the following from plotter.py and report/_plots.py:
+  plot_grid, pcolor_timeseries_by_depth, plot_grid_fig (was _make_grid_fig_b64),
+  plot_isopycnal (was _make_isopycnal_fig_b64), plot_grid_n2 (was _make_grid_n2_b64).
+
+Tier-1 primitive: plot_section (data-agnostic, contour_da=None for any quantity).
+
+Note: _filter_sigma_tukey belongs in tools/ (data pre-treatment), not here.
+Callers pass pre-filtered data; high-level wrappers like plot_isopycnal may
+apply the filter internally but expose it as a parameter.
+
+See .claude/plotters_update-20260718.md for migration checklist.
+"""
+
+# TODO post-OdB: migrate from plotter.py / report/_plots.py

oceanarray/plotters/_timeseries.py

@@ -0,0 +1,11 @@
+"""Tier-2 domain wrappers for instrument time-series plots.
+
+Post-OdB: migrate the following from plotter.py and report/_plots.py:
+  plot_microcat_raw, plot_microcat, plot_aquadopp_raw, plot_aquadopp_quick,
+  plot_timeseries_by_depth, plot_mooring_timeseries, plot_trim_windows,
+  build_instrument_fig (was _build_fig_from_ds), plot_instrument_windows.
+
+See .claude/plotters_update-20260718.md for migration checklist.
+"""
+
+# TODO post-OdB: migrate from plotter.py / report/_plots.py