oceanarray 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. oceanarray/__init__.py +12 -10
  2. oceanarray/_version.py +1 -1
  3. oceanarray/analysis/__init__.py +20 -0
  4. oceanarray/{clock_offset.py → analysis/clock.py} +26 -9
  5. oceanarray/analysis/hydrographic.py +325 -0
  6. oceanarray/analysis/science.py +226 -0
  7. oceanarray/analysis/spectral.py +348 -0
  8. oceanarray/analysis/temporal.py +217 -0
  9. oceanarray/analysis/vector.py +115 -0
  10. oceanarray/cli.py +598 -140
  11. oceanarray/config/__init__.py +7 -0
  12. oceanarray/{parameters.py → config/parameters.py} +64 -9
  13. oceanarray/{validation.py → config/validation.py} +28 -65
  14. oceanarray/inspect.py +117 -0
  15. oceanarray/legacy/tools.py +852 -0
  16. oceanarray/paths.py +163 -0
  17. oceanarray/plotters/__init__.py +146 -42
  18. oceanarray/plotters/_cli_legacy.py +316 -0
  19. oceanarray/plotters/{_animation.py → animation.py} +2 -2
  20. oceanarray/plotters/current.py +1640 -0
  21. oceanarray/plotters/diagnostic.py +1549 -0
  22. oceanarray/plotters/helpers.py +247 -0
  23. oceanarray/plotters/hydrography.py +465 -0
  24. oceanarray/plotters/primitives.py +336 -0
  25. oceanarray/plotters/spectrum.py +1012 -0
  26. oceanarray/plotters/timeseries.py +582 -0
  27. oceanarray/plotters/ts.py +481 -0
  28. oceanarray/processors/__init__.py +331 -0
  29. oceanarray/processors/caldip.py +1 -0
  30. oceanarray/processors/coordinate.py +719 -0
  31. oceanarray/{time_gridding.py → processors/grid.py} +295 -60
  32. oceanarray/processors/helpers.py +357 -0
  33. oceanarray/processors/pressure.py +401 -0
  34. oceanarray/processors/qc.py +818 -0
  35. oceanarray/processors/stack.py +692 -0
  36. oceanarray/{stage1.py → processors/stage1.py} +138 -199
  37. oceanarray/{stage2.py → processors/stage2.py} +23 -100
  38. oceanarray/processors/stage3.py +699 -0
  39. oceanarray/report/_array.py +297 -11
  40. oceanarray/report/_grid.py +63 -36
  41. oceanarray/report/_html_helpers.py +27 -45
  42. oceanarray/report/_instrument.py +40 -27
  43. oceanarray/report/_mooring.py +177 -48
  44. oceanarray/report/_plots.py +352 -3657
  45. oceanarray/report/_recovery_table.py +507 -0
  46. oceanarray/report/_stack.py +32 -26
  47. oceanarray/tools/__init__.py +33 -0
  48. oceanarray/{rapid_interp.py → tools/rapid_interp.py} +95 -1
  49. oceanarray/{readers.py → tools/readers.py} +3 -0
  50. oceanarray/{writers.py → tools/writers.py} +7 -3
  51. oceanarray/utilities.py +176 -0
  52. oceanarray-0.2.0.dist-info/METADATA +108 -0
  53. oceanarray-0.2.0.dist-info/RECORD +93 -0
  54. oceanarray/mooring_level.py +0 -1368
  55. oceanarray/plotter.py +0 -942
  56. oceanarray/plotters/_current.py +0 -705
  57. oceanarray/plotters/_diagnostic.py +0 -667
  58. oceanarray/plotters/_helpers.py +0 -57
  59. oceanarray/plotters/_primitives.py +0 -101
  60. oceanarray/plotters/_section.py +0 -16
  61. oceanarray/plotters/_timeseries.py +0 -11
  62. oceanarray/read_rbr_hex.py +0 -541
  63. oceanarray/stage3.py +0 -2494
  64. oceanarray/tools.py +0 -400
  65. oceanarray/transports.py +0 -1
  66. oceanarray-0.1.0.dist-info/METADATA +0 -503
  67. oceanarray-0.1.0.dist-info/RECORD +0 -76
  68. {oceanarray-0.1.0.dist-info → oceanarray-0.2.0.dist-info}/WHEEL +0 -0
  69. {oceanarray-0.1.0.dist-info → oceanarray-0.2.0.dist-info}/entry_points.txt +0 -0
  70. {oceanarray-0.1.0.dist-info → oceanarray-0.2.0.dist-info}/licenses/LICENSE +0 -0
  71. {oceanarray-0.1.0.dist-info → oceanarray-0.2.0.dist-info}/top_level.txt +0 -0
oceanarray/__init__.py CHANGED
@@ -4,17 +4,19 @@ This package provides functions for processing, quality control, and analysis
4
4
  of oceanographic time series data from moorings and instruments.
5
5
  """
6
6
 
7
+ from oceanarray.config import parameters
8
+ from oceanarray.processors import process
9
+
7
10
  __all__ = [
8
- "clock_offset",
9
- "detect_deployment_window",
10
- "logsheet",
11
- "plotters",
12
- "readers",
13
- "stage1",
14
- "stage2",
15
- "time_gridding",
11
+ # Subpackages (canonical locations)
12
+ "analysis",
13
+ "config",
14
+ "processors",
16
15
  "tools",
17
- "transports",
16
+ # Top-level modules
17
+ "parameters",
18
+ "plotters",
18
19
  "utilities",
19
- "writers",
20
+ # Public API
21
+ "process",
20
22
  ]
oceanarray/_version.py CHANGED
@@ -1 +1 @@
1
- __version__ = '0.1.0'
1
+ __version__ = '0.2.0'
@@ -0,0 +1,20 @@
1
+ """Analysis subpackage for oceanarray.
2
+
3
+ Submodules
4
+ ----------
5
+ science : QC routines (flag_salinity_outliers, flag_temporal_spikes,
6
+ run_qc, process_dataset) and backward-compat re-exports.
7
+ vector : XYZ→ENU rotation (xyz_to_enu_2d) and progressive-vector
8
+ trajectory computation (progressive_vector).
9
+ temporal : Lag correlation (lag_correlation), histogram split value
10
+ (split_value), T/S downsampling (downsample_to_sparse), and
11
+ Tukey time-series filtering (filter_sigma_tukey).
12
+ spectral : Gonella rotary spectra (gonella_rotary_spectrum), Welch PSD
13
+ (welch_psd, welch_psd_gapaware), and continuous wavelet
14
+ transforms (compute_cwt).
15
+ hydrographic : Salinity calculation (calc_psal), isopycnal tracking
16
+ (isopycnal_pressure_series, isopycnal_dataset), cold-regime
17
+ detection (find_cold_entry_exit), and dataset differencing
18
+ (calc_ds_difference).
19
+ clock : Clock-offset analysis for mooring instruments.
20
+ """
@@ -1,8 +1,15 @@
1
1
  """Clock offset analysis functions for oceanographic instrument data.
2
2
 
3
+ Promoted from the top-level ``oceanarray/clock_offset.py``; backward-compatible
4
+ re-exports live at ``oceanarray/clock_offset.py``.
5
+
3
6
  This module provides functions to analyze and detect clock offsets between
4
7
  different instruments on the same mooring by comparing deployment timing
5
8
  and performing lag correlation analysis.
9
+
10
+ Naming conventions updated from the original module:
11
+ - YAML key ``instruments`` → ``clamp``
12
+ - file suffix ``_raw`` → ``_stage2``
6
13
  """
7
14
 
8
15
  import os
@@ -12,11 +19,16 @@ import pandas as pd
12
19
  import xarray as xr
13
20
  import yaml
14
21
 
15
- from oceanarray import tools
22
+ from oceanarray.analysis.temporal import lag_correlation
16
23
  from oceanarray.legacy import find_deployment
17
24
 
18
25
 
19
- def load_mooring_instruments(mooring_name, base_dir, output_path, file_suffix="_raw"): # noqa: ARG001
26
+ def load_mooring_instruments(
27
+ mooring_name,
28
+ base_dir, # noqa: ARG001
29
+ output_path,
30
+ file_suffix="_stage2",
31
+ ):
20
32
  """Load all instruments for a mooring from netCDF files and enrich with YAML metadata.
21
33
 
22
34
  Parameters
@@ -24,11 +36,11 @@ def load_mooring_instruments(mooring_name, base_dir, output_path, file_suffix="_
24
36
  mooring_name : str
25
37
  Name of the mooring (e.g., 'dsE_1_2018')
26
38
  base_dir : str
27
- Base directory path
39
+ Base directory path (currently unused — reserved for future use)
28
40
  output_path : str
29
41
  Path to processed data directory
30
42
  file_suffix : str, optional
31
- File suffix to use ('_raw' or '_use'), default '_raw'
43
+ File suffix to use (e.g. '_stage2', '_stage3'), default '_stage2'
32
44
 
33
45
  Returns
34
46
  -------
@@ -44,8 +56,15 @@ def load_mooring_instruments(mooring_name, base_dir, output_path, file_suffix="_
44
56
  with open(moor_yaml, "r") as f:
45
57
  moor_yaml_data = yaml.safe_load(f)
46
58
 
59
+ # Support both new key 'clamp' and legacy key 'instruments'
60
+ instrument_list = moor_yaml_data.get("clamp", moor_yaml_data.get("instruments", []))
61
+ if not instrument_list:
62
+ raise KeyError( # noqa: TRY003
63
+ f"Mooring YAML {moor_yaml} has neither 'clamp' nor 'instruments' key."
64
+ )
65
+
47
66
  datasets = []
48
- for i in moor_yaml_data["instruments"]:
67
+ for i in instrument_list:
49
68
  fname = mooring_name + "_" + str(i["serial"]) + file_suffix + ".nc"
50
69
  rawfile = proc_dir + "/" + i["instrument"] + "/" + fname
51
70
 
@@ -385,7 +404,7 @@ def perform_lag_correlation_analysis(combined_ds, ref_index=0, sub_sample=5):
385
404
  temp_i_sub = combined_ds["temperature"][:, i].values[::sub_sample]
386
405
  coff = combined_ds["clock_offset"][i].values
387
406
 
388
- corrs_sub = tools.lag_correlation(ref_temp_sub, temp_i_sub, max_lag_sub)
407
+ corrs_sub = lag_correlation(ref_temp_sub, temp_i_sub, max_lag_sub)
389
408
 
390
409
  max_corr_idx = np.nanargmax(corrs_sub)
391
410
  max_corr = corrs_sub[max_corr_idx]
@@ -548,6 +567,7 @@ def plot_deployment_boundaries(
548
567
  Figure size for each plot, default (12, 4)
549
568
 
550
569
  """
570
+ import matplotlib.dates as mdates
551
571
  import matplotlib.pyplot as plt
552
572
 
553
573
  start_times = combined_ds["start_time"].values
@@ -662,9 +682,6 @@ def plot_deployment_boundaries(
662
682
  ax.legend(loc="best")
663
683
  ax.grid(True, alpha=0.3)
664
684
 
665
- # Format x-axis for better readability
666
- import matplotlib.dates as mdates
667
-
668
685
  ax.xaxis.set_major_formatter(mdates.DateFormatter("%H:%M:%S"))
669
686
  ax.xaxis.set_major_locator(
670
687
  mdates.MinuteLocator(interval=max(1, n_samples // 5))
@@ -0,0 +1,325 @@
1
+ """Hydrographic analysis utilities for oceanographic mooring data.
2
+
3
+ hydrographic.py provides salinity computation, isopycnal tracking, dataset
4
+ differencing, and cold-regime detection functions extracted from the general
5
+ science utilities.
6
+
7
+ Pairs with :mod:`oceanarray.plotters.hydrography` for figure output.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import numpy as np
13
+ import pandas as pd
14
+ import xarray as xr
15
+ import gsw
16
+
17
+
18
+ def calc_psal(ds: xr.Dataset) -> xr.Dataset:
19
+ """Compute Practical Salinity from conductivity, temperature, and pressure.
20
+
21
+ Uses the Gibbs SeaWater (GSW) toolbox: ``gsw.SP_from_C`` applies the
22
+ PSS-78 equation to derive Practical Salinity (dimensionless, roughly PSU)
23
+ from conductivity (mS cm⁻¹), temperature (°C), and pressure (dbar).
24
+
25
+ If ``PSAL`` is already present in *ds* the function is a no-op.
26
+
27
+ Parameters
28
+ ----------
29
+ ds : xarray.Dataset
30
+ Dataset containing ``CNDC`` (conductivity, mS cm⁻¹), ``TEMP``
31
+ (temperature, °C), and ``PRES`` (pressure, dbar).
32
+
33
+ Returns
34
+ -------
35
+ xarray.Dataset
36
+ Input dataset with ``PSAL`` added (same dimensions as ``CNDC``),
37
+ or unchanged if ``PSAL`` was already present.
38
+
39
+ """
40
+ if "PSAL" not in ds:
41
+ SP = gsw.SP_from_C(ds["CNDC"], ds["TEMP"], ds["PRES"])
42
+ ds["PSAL"] = (ds["CNDC"].dims, SP.data)
43
+ else:
44
+ print("ds already contains variable PSAL")
45
+ return ds
46
+
47
+
48
+ def find_cold_entry_exit(
49
+ time: np.ndarray,
50
+ temp: np.ndarray,
51
+ quantile: float = 0.95,
52
+ dwell_seconds: int = 1800,
53
+ smooth_window: int = 5,
54
+ ) -> tuple[pd.Timestamp | None, pd.Timestamp | None, float]:
55
+ """Identify first sustained entry into 'cold' regime and last sustained exit.
56
+
57
+ Parameters
58
+ ----------
59
+ time : array-like of datetime64
60
+ Time coordinate array.
61
+ temp : array-like of float
62
+ Temperature values aligned with *time*.
63
+ quantile : float
64
+ Percentile for threshold (e.g. 0.1 ~ 10th percentile).
65
+ dwell_seconds : int
66
+ Minimum time in cold regime for it to count (seconds).
67
+ smooth_window : int
68
+ Rolling median window length (samples).
69
+
70
+ Returns
71
+ -------
72
+ t_start, t_end, threshold : tuple of (Timestamp or None, Timestamp or None, float)
73
+
74
+ """
75
+ time = pd.to_datetime(time)
76
+ temp = np.asarray(temp, dtype=float)
77
+ thr = np.nanquantile(temp, quantile)
78
+
79
+ # smooth with rolling median
80
+ if smooth_window > 1:
81
+ temp = (
82
+ pd.Series(temp)
83
+ .rolling(smooth_window, center=True, min_periods=1)
84
+ .median()
85
+ .values
86
+ )
87
+
88
+ below = temp <= thr
89
+ if not below.any():
90
+ return None, None, thr
91
+
92
+ # sampling interval (assume near-regular)
93
+ dt = np.nanmedian(np.diff(time.values).astype("timedelta64[s]").astype(float))
94
+ min_len = int(np.ceil(dwell_seconds / dt))
95
+
96
+ # contiguous runs
97
+ idx = np.where(below)[0]
98
+ gaps = np.diff(idx) > 1
99
+ starts = np.r_[idx[0], idx[1:][gaps]]
100
+ ends = np.r_[idx[:-1][gaps], idx[-1]]
101
+
102
+ runs = [(s, e) for s, e in zip(starts, ends) if (e - s + 1) >= min_len]
103
+ if not runs:
104
+ return None, None, thr
105
+
106
+ s0, _ = runs[0]
107
+ _, eL = runs[-1]
108
+ return time[s0], time[eL], thr
109
+
110
+
111
+ def calc_ds_difference(ds1: xr.Dataset, ds2: xr.Dataset) -> xr.Dataset:
112
+ """Compute the variable-by-variable difference between two time-matched datasets."""
113
+ if not np.array_equal(ds1["TIME"].values, ds2["TIME"].values):
114
+ raise ValueError("TIME grids do not match between datasets.") # noqa: TRY003
115
+
116
+ # Variables to exclude from differencing
117
+ exclude_vars = {"YY", "MM", "DD", "HH"}
118
+
119
+ # Prepare a dict for new data variables
120
+ diff_data = {}
121
+
122
+ for var in ds1.data_vars:
123
+ # Only difference variables with dimension TIME and not in exclude list
124
+ if "TIME" in ds1[var].dims and var not in exclude_vars:
125
+ diff_data[var] = ds1[var] - ds2[var]
126
+ else:
127
+ # Copy over variables that are not differenced
128
+ diff_data[var] = ds1[var]
129
+
130
+ # Create a new dataset with the same coordinates and attributes
131
+ ds_diff = ds1.copy()
132
+ for var in diff_data:
133
+ ds_diff[var] = diff_data[var]
134
+
135
+ return ds_diff
136
+
137
+
138
+ def isopycnal_pressure_series(
139
+ sigma0_tp: np.ndarray,
140
+ pressure: np.ndarray,
141
+ sigma_grid: np.ndarray,
142
+ ) -> np.ndarray:
143
+ """Find the pressure of each target density surface at every time step.
144
+
145
+ Uses a "first crossing from shallow" approach: for each target σ₀ value,
146
+ scans from the shallowest pressure downward and finds the first level where
147
+ sigma0 transitions from below to at-or-above the target, then linearly
148
+ interpolates between those two levels. This is robust to non-monotonic
149
+ sigma0 columns (which occur in gridded fields during knockdowns) and always
150
+ returns the shallowest crossing — the physically meaningful pycnocline.
151
+
152
+ Returns NaN only when the target density is absent from the entire column
153
+ (too light or too dense for any observed level at that time step).
154
+
155
+ .. note::
156
+ Operates on σ₀ (potential density referenced to 0 dbar). If the
157
+ mooring was processed with a different reference pressure (e.g. σ₂ at
158
+ 2000 dbar), pass the corresponding sigma variable. A future option
159
+ ``--sig-ref`` / ``density_reference`` will generalise this; for now
160
+ the variable name in the dataset controls which reference is used.
161
+
162
+ Parameters
163
+ ----------
164
+ sigma0_tp:
165
+ Shape ``(time, pressure)``. NaN where missing.
166
+ pressure:
167
+ 1-D array of pressure levels in dbar. Need not be sorted — the
168
+ function sorts each time step's finite values by pressure before
169
+ scanning for crossings.
170
+ sigma_grid:
171
+ Target sigma0 values (kg m⁻³) at which to find the pressure.
172
+
173
+ Returns
174
+ -------
175
+ np.ndarray
176
+ Shape ``(time, len(sigma_grid))``. NaN where the target isopycnal is
177
+ absent from the observed column at that time step.
178
+
179
+ """
180
+ s = np.asarray(sigma0_tp, dtype=float)
181
+ p = np.asarray(pressure, dtype=float)
182
+ sg = np.asarray(sigma_grid, dtype=float)
183
+ n_t = s.shape[0]
184
+ n_sg = len(sg)
185
+ result = np.full((n_t, n_sg), np.nan)
186
+
187
+ for t in range(n_t):
188
+ col = s[t, :]
189
+ finite_mask = np.isfinite(col)
190
+ if finite_mask.sum() < 2:
191
+ continue
192
+ s_f = col[finite_mask]
193
+ p_f = p[finite_mask]
194
+ sort_idx = np.argsort(p_f)
195
+ s_f = s_f[sort_idx]
196
+ p_f = p_f[sort_idx]
197
+
198
+ # Upward crossings: pairs (j, j+1) where s_f[j] < target and
199
+ # s_f[j+1] >= target. This handles non-monotonic columns: isolated
200
+ # spikes (level above target then back below) do not produce an upward
201
+ # crossing, while genuine crossings of the pycnocline do.
202
+ # Shape: (n_p-1, n_sg)
203
+ above = s_f[:, None] >= sg[None, :] # (n_p, n_sg)
204
+ upward = ~above[:-1, :] & above[1:, :] # first element of each crossing pair
205
+
206
+ has_crossing = upward.any(axis=0) # (n_sg,)
207
+ # argmax on upward gives index j of the first crossing pair (j, j+1).
208
+ # When has_crossing is False argmax returns 0 — use safe fallback indices.
209
+ j0 = np.argmax(upward, axis=0) # (n_sg,) index of lower bound
210
+ i0 = np.where(has_crossing, j0, 0)
211
+ i1 = np.where(has_crossing, j0 + 1, 1)
212
+
213
+ s0 = s_f[i0]
214
+ s1 = s_f[i1]
215
+ p0v = p_f[i0]
216
+ p1v = p_f[i1]
217
+ denom = s1 - s0
218
+ # denom > 0 guaranteed for valid crossings (s0 < target <= s1).
219
+ with np.errstate(divide="ignore", invalid="ignore"):
220
+ frac = np.where(has_crossing & (denom > 0), (sg - s0) / denom, 0.0)
221
+ result[t, :] = np.where(has_crossing, p0v + frac * (p1v - p0v), np.nan)
222
+
223
+ # To also track the *last* (deepest) upward crossing of each surface,
224
+ # flip upward along axis=0, argmax, then map back:
225
+ # j0_last = (len(s_f) - 2) - np.argmax(upward[::-1, :], axis=0)
226
+
227
+ return result
228
+
229
+
230
+ def isopycnal_dataset(
231
+ ds: xr.Dataset,
232
+ sigma_var: str = "sigma0",
233
+ sigma_grid: np.ndarray | None = None,
234
+ ) -> xr.Dataset:
235
+ """Build an isopycnal-tracking dataset from a gridded mooring file.
236
+
237
+ Tracks the pressure (and height above seabed) of density surfaces through
238
+ time using the gridded sigma0 field. Calls
239
+ :func:`isopycnal_pressure_series` column-by-column.
240
+
241
+ Parameters
242
+ ----------
243
+ ds:
244
+ Gridded mooring xr.Dataset with ``(pressure, time)`` dimensions and
245
+ a sigma variable. A ``waterdepth`` global attribute (metres) is used
246
+ for the height-above-seabed conversion; if absent both ``_height``
247
+ variables are all-NaN.
248
+ sigma_var:
249
+ Name of the sigma variable in *ds* (default ``"sigma0"``).
250
+ sigma_grid:
251
+ Target sigma0 values to track. If ``None``, a 0.1 kg m⁻³ grid is
252
+ computed from the observed data range.
253
+
254
+ Returns
255
+ -------
256
+ xr.Dataset
257
+ Dimensions ``(sigma0_level, time)``. Variables:
258
+
259
+ * ``isopycnal_pressure`` — dbar, NaN where absent.
260
+ * ``isopycnal_height`` — m above seabed, NaN where absent.
261
+
262
+ """
263
+ if sigma_var not in ds:
264
+ raise ValueError(f"sigma variable '{sigma_var}' not found in dataset") # noqa: TRY003
265
+
266
+ da = ds[sigma_var]
267
+ if "time" not in da.dims or "pressure" not in da.dims:
268
+ raise ValueError( # noqa: TRY003
269
+ f"'{sigma_var}' must have both 'time' and 'pressure' dimensions"
270
+ )
271
+ da_tp = da.transpose("time", "pressure")
272
+ pressure = da_tp["pressure"].values
273
+ time = da_tp["time"].values
274
+ sigma0_tp = da_tp.values
275
+
276
+ if sigma_grid is None:
277
+ s_finite = sigma0_tp[np.isfinite(sigma0_tp)]
278
+ if len(s_finite) == 0:
279
+ sigma_grid = np.arange(26.5, 28.2, 0.1)
280
+ else:
281
+ smin = np.floor(s_finite.min() * 10) / 10
282
+ smax = np.ceil(s_finite.max() * 10) / 10
283
+ sigma_grid = np.arange(smin, smax + 0.05, 0.1)
284
+
285
+ iso_p = isopycnal_pressure_series(sigma0_tp, pressure, sigma_grid) # (T, N)
286
+
287
+ try:
288
+ waterdepth = float(ds.attrs.get("waterdepth", ""))
289
+ except (ValueError, TypeError):
290
+ waterdepth = np.nan
291
+ if np.isfinite(waterdepth) and waterdepth > 0:
292
+ iso_h = waterdepth - iso_p
293
+ iso_h[iso_h < 0] = np.nan
294
+ else:
295
+ iso_h = np.full_like(iso_p, np.nan)
296
+
297
+ dim_name = f"{sigma_var}_level"
298
+ return xr.Dataset(
299
+ {
300
+ "isopycnal_pressure": xr.DataArray(
301
+ iso_p.T,
302
+ dims=[dim_name, "time"],
303
+ attrs={"units": "dbar", "long_name": "Isopycnal pressure"},
304
+ ),
305
+ "isopycnal_height": xr.DataArray(
306
+ iso_h.T,
307
+ dims=[dim_name, "time"],
308
+ attrs={
309
+ "units": "m",
310
+ "long_name": "Isopycnal height above seabed",
311
+ },
312
+ ),
313
+ },
314
+ coords={
315
+ dim_name: xr.DataArray(
316
+ sigma_grid,
317
+ dims=[dim_name],
318
+ attrs={
319
+ "units": "kg m-3",
320
+ "long_name": f"Potential density anomaly ({sigma_var})",
321
+ },
322
+ ),
323
+ "time": time,
324
+ },
325
+ )
@@ -0,0 +1,226 @@
1
+ """QC and dataset processing functions for oceanographic instrument data.
2
+
3
+ Contains salinity/conductivity quality-control routines and a dataset
4
+ processing helper. Hydrographic, spectral, time-series, and vector
5
+ utilities have been split into dedicated submodules:
6
+
7
+ - :mod:`oceanarray.analysis.hydrographic` — salinity calculation, isopycnal
8
+ tracking, cold-regime detection, dataset differencing.
9
+ - :mod:`oceanarray.analysis.spectral` — Gonella rotary spectra, Welch PSD,
10
+ continuous wavelet transforms.
11
+ - :mod:`oceanarray.analysis.temporal` — lag correlation, split value,
12
+ downsampling, Tukey filtering.
13
+ - :mod:`oceanarray.analysis.vector` — XYZ→ENU rotation, progressive vector.
14
+
15
+ Backward-compatible re-exports at the bottom of this file preserve existing
16
+ ``from oceanarray.analysis._science import …`` usage.
17
+ """
18
+
19
+ import logging
20
+
21
+ import numpy as np
22
+ import xarray as xr
23
+
24
+ from oceanarray import utilities
25
+
26
+ # Initialize logging
27
+ _log = logging.getLogger(__name__)
28
+
29
+
30
+ def flag_salinity_outliers(ds: xr.Dataset, n_std: float = 4) -> xr.DataArray:
31
+ """Flag PSAL values more than n_std standard deviations from the mean.
32
+
33
+ Computed separately for each depth level.
34
+
35
+ Parameters
36
+ ----------
37
+ ds : xarray.Dataset
38
+ Dataset containing "PSAL" variable with dimensions including "DEPTH".
39
+ n_std : float, optional
40
+ Number of standard deviations from the mean to define an outlier (default is 4).
41
+
42
+ Returns
43
+ -------
44
+ xarray.DataArray (bool)
45
+ Boolean array with True where salinity is flagged as an outlier.
46
+
47
+ """
48
+ if "CNDC_QC" in ds:
49
+ mask = ds["CNDC_QC"] == 0
50
+ mean_sal = ds["PSAL"].where(mask).mean(dim="TIME", skipna=True)
51
+ std_sal = ds["PSAL"].where(mask).std(dim="TIME", skipna=True)
52
+ else:
53
+ mean_sal = ds["PSAL"].mean(dim="TIME", skipna=True)
54
+ std_sal = ds["PSAL"].std(dim="TIME", skipna=True)
55
+
56
+ # Broadcast mean and std over time
57
+ lower = mean_sal - n_std * std_sal
58
+ upper = mean_sal + n_std * std_sal
59
+
60
+ flag = (ds["PSAL"] < lower) | (ds["PSAL"] > upper)
61
+ return flag
62
+
63
+
64
+ def flag_temporal_spikes(
65
+ ds: xr.Dataset, var: str = "CNDC", threshold: float = 5
66
+ ) -> xr.DataArray:
67
+ """Flag large absolute differences in time for each depth.
68
+
69
+ threshold: maximum allowed difference in units of the variable.
70
+ """
71
+ diff = np.abs(ds[var].diff("TIME", label="upper"))
72
+ flag = diff > threshold
73
+ # Pad to match original dimensions
74
+ flag = flag.reindex(TIME=ds["TIME"], method="ffill")
75
+ flag = flag.fillna(False)
76
+ return flag.astype(bool)
77
+
78
+
79
+ def flag_vertical_inconsistencies(
80
+ ds: xr.Dataset, var: str = "CNDC", threshold: float = 2
81
+ ) -> xr.DataArray:
82
+ """Flag points that are very different from vertical neighbors.
83
+
84
+ threshold: max allowed difference between vertically adjacent sensors.
85
+ """
86
+ # Central difference approximation in depth
87
+ vert_diff = np.abs(ds[var].diff("DEPTH"))
88
+ # Pad to match original dimensions
89
+ vert_diff = vert_diff.reindex(DEPTH=ds["DEPTH"], method="ffill")
90
+ flag = vert_diff > threshold
91
+ return flag
92
+
93
+
94
+ def run_qc(ds: xr.Dataset) -> xr.Dataset:
95
+ """Apply a sequence of QC tests and write combined CNDC_QC flag variable."""
96
+ from oceanarray.analysis.hydrographic import calc_psal as _calc_psal
97
+
98
+ if "PSAL" not in ds:
99
+ ds = _calc_psal(ds)
100
+
101
+ sal_flag = flag_salinity_outliers(ds, 6).astype(bool)
102
+ time_flag = flag_temporal_spikes(ds).astype(bool)
103
+ # vert_flag = flag_vertical_inconsistencies(ds).astype(bool)
104
+
105
+ # Combine all
106
+ combined_flag = sal_flag | time_flag
107
+ ds["CNDC_QC"] = (ds["CNDC"].dims, combined_flag.data.astype(int))
108
+
109
+ sal_flag = flag_salinity_outliers(ds, 3).astype(bool)
110
+ combined_flag = sal_flag | time_flag
111
+ ds["CNDC_QC"] = (ds["CNDC"].dims, combined_flag.data.astype(int))
112
+
113
+ return ds
114
+
115
+
116
+ def process_dataset(
117
+ ds: xr.Dataset,
118
+ latlim: tuple[float, float] = (26.0, 27.0),
119
+ lonlim: tuple[float, float] = (-77.0, -76.5),
120
+ pgrid: np.ndarray = None,
121
+ ) -> tuple[xr.Dataset, xr.Dataset]:
122
+ """Filter and process a hydrographic dataset for use in training.
123
+
124
+ This function selects a region of interest, extracts and downsamples profiles of
125
+ temperature and salinity onto both standard and sparse pressure grids. It also computes
126
+ potential density anomaly for both resolutions.
127
+
128
+ Parameters
129
+ ----------
130
+ ds : xr.Dataset
131
+ Input dataset containing hydrographic data including CT, SA, PRES, and metadata.
132
+ latlim : tuple of float, optional
133
+ Latitude limits for filtering, by default (26.0, 27.0).
134
+ lonlim : tuple of float, optional
135
+ Longitude limits for filtering, by default (-77.0, -76.5).
136
+ pgrid : np.ndarray, optional
137
+ Target pressure levels (dbar) for vertical interpolation. When None,
138
+ a 20 dbar grid is constructed automatically from 0 to the maximum
139
+ observed pressure.
140
+
141
+ Returns
142
+ -------
143
+ ds_standard : xr.Dataset
144
+ Dataset downsampled to standard pressure levels.
145
+ ds_sparse : xr.Dataset
146
+ Dataset downsampled to sparse pressure levels.
147
+
148
+ See Also
149
+ --------
150
+ verticalnn.data_utils.downsample_to_sparse : Used to interpolate to target pressure levels.
151
+ verticalnn.config.STANDARD_PRESSURES : Standard pressure grid.
152
+ verticalnn.config.SPARSE_PRESSURES : Sparse pressure grid.
153
+
154
+ """
155
+ from oceanarray.analysis.temporal import downsample_to_sparse as _downsample
156
+
157
+ pres_key, time_key, pres_dim, time_dim = utilities.get_dims(ds)
158
+
159
+ if pgrid is None:
160
+ max_pres = np.nanmax(ds[pres_key].values)
161
+ pgrid = np.arange(0, max_pres + 1, 20)
162
+
163
+ # Extract variables
164
+ TEMP_profiles = ds["TEMP"].values
165
+ PSAL_profiles = ds["PSAL"].values
166
+ CT_profiles = ds["CT"].values
167
+ SA_profiles = ds["SA"].values
168
+ PRES = ds[pres_key].values
169
+ LAT = ds["LATITUDE"].values
170
+ LON = ds["LONGITUDE"].values
171
+ time = ds[time_key].values
172
+
173
+ # Apply region of interest mask
174
+ mask = (
175
+ (LAT >= latlim[0])
176
+ & (LAT <= latlim[1])
177
+ & (LON >= lonlim[0])
178
+ & (LON <= lonlim[1])
179
+ )
180
+ TEMP_profiles = TEMP_profiles[mask]
181
+ PSAL_profiles = PSAL_profiles[mask]
182
+ CT_profiles = CT_profiles[mask]
183
+ SA_profiles = SA_profiles[mask]
184
+ time = time[mask]
185
+ LAT = LAT[mask]
186
+ LON = LON[mask]
187
+
188
+ # Downsample to standard pressures
189
+ CT_standard, SA_standard = _downsample(CT_profiles, SA_profiles, PRES, pgrid)
190
+ # Downsample to standard pressures
191
+ temp_standard, salt_standard = _downsample(
192
+ TEMP_profiles, PSAL_profiles, PRES, pgrid
193
+ )
194
+ standard_pressures = pgrid.flatten()
195
+
196
+ # Create ds_standard
197
+ ds_standard = xr.Dataset(
198
+ {
199
+ "CT": ((time_dim, pres_dim), CT_standard),
200
+ "SA": ((time_dim, pres_dim), SA_standard),
201
+ "TEMP": ((time_dim, pres_dim), temp_standard),
202
+ "PSAL": ((time_dim, pres_dim), salt_standard),
203
+ },
204
+ coords={
205
+ time_key: (time_dim, time),
206
+ pres_key: (pres_dim, standard_pressures),
207
+ "LATITUDE": (time_dim, LAT),
208
+ "LONGITUDE": (time_dim, LON),
209
+ },
210
+ )
211
+
212
+ return ds_standard
213
+
214
+
215
+ # ---------------------------------------------------------------------------
216
+ # Backward-compat re-exports — import directly from the new modules in new code
217
+ # ---------------------------------------------------------------------------
218
+ from .temporal import lag_correlation, split_value, downsample_to_sparse # noqa: F401, E402
219
+ from .spectral import compute_cwt, welch_psd, welch_psd_gapaware # noqa: F401, E402
220
+ from .hydrographic import ( # noqa: F401, E402
221
+ calc_psal,
222
+ find_cold_entry_exit,
223
+ calc_ds_difference,
224
+ isopycnal_pressure_series,
225
+ isopycnal_dataset,
226
+ )