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.
- oceanarray/__init__.py +12 -10
- oceanarray/_version.py +1 -1
- oceanarray/analysis/__init__.py +20 -0
- oceanarray/{clock_offset.py → analysis/clock.py} +26 -9
- oceanarray/analysis/hydrographic.py +325 -0
- oceanarray/analysis/science.py +226 -0
- oceanarray/analysis/spectral.py +348 -0
- oceanarray/analysis/temporal.py +217 -0
- oceanarray/analysis/vector.py +115 -0
- oceanarray/cli.py +598 -140
- oceanarray/config/__init__.py +7 -0
- oceanarray/{parameters.py → config/parameters.py} +64 -9
- oceanarray/{validation.py → config/validation.py} +28 -65
- oceanarray/inspect.py +117 -0
- oceanarray/legacy/tools.py +852 -0
- oceanarray/paths.py +163 -0
- oceanarray/plotters/__init__.py +146 -42
- oceanarray/plotters/_cli_legacy.py +316 -0
- oceanarray/plotters/{_animation.py → animation.py} +2 -2
- oceanarray/plotters/current.py +1640 -0
- oceanarray/plotters/diagnostic.py +1549 -0
- oceanarray/plotters/helpers.py +247 -0
- oceanarray/plotters/hydrography.py +465 -0
- oceanarray/plotters/primitives.py +336 -0
- oceanarray/plotters/spectrum.py +1012 -0
- oceanarray/plotters/timeseries.py +582 -0
- oceanarray/plotters/ts.py +481 -0
- oceanarray/processors/__init__.py +331 -0
- oceanarray/processors/caldip.py +1 -0
- oceanarray/processors/coordinate.py +719 -0
- oceanarray/{time_gridding.py → processors/grid.py} +295 -60
- oceanarray/processors/helpers.py +357 -0
- oceanarray/processors/pressure.py +401 -0
- oceanarray/processors/qc.py +818 -0
- oceanarray/processors/stack.py +692 -0
- oceanarray/{stage1.py → processors/stage1.py} +138 -199
- oceanarray/{stage2.py → processors/stage2.py} +23 -100
- oceanarray/processors/stage3.py +699 -0
- oceanarray/report/_array.py +297 -11
- oceanarray/report/_grid.py +63 -36
- oceanarray/report/_html_helpers.py +27 -45
- oceanarray/report/_instrument.py +40 -27
- oceanarray/report/_mooring.py +177 -48
- oceanarray/report/_plots.py +352 -3657
- oceanarray/report/_recovery_table.py +507 -0
- oceanarray/report/_stack.py +32 -26
- oceanarray/tools/__init__.py +33 -0
- oceanarray/{rapid_interp.py → tools/rapid_interp.py} +95 -1
- oceanarray/{readers.py → tools/readers.py} +3 -0
- oceanarray/{writers.py → tools/writers.py} +7 -3
- oceanarray/utilities.py +176 -0
- oceanarray-0.2.0.dist-info/METADATA +108 -0
- oceanarray-0.2.0.dist-info/RECORD +93 -0
- oceanarray/mooring_level.py +0 -1368
- oceanarray/plotter.py +0 -942
- oceanarray/plotters/_current.py +0 -705
- oceanarray/plotters/_diagnostic.py +0 -667
- oceanarray/plotters/_helpers.py +0 -57
- oceanarray/plotters/_primitives.py +0 -101
- oceanarray/plotters/_section.py +0 -16
- oceanarray/plotters/_timeseries.py +0 -11
- oceanarray/read_rbr_hex.py +0 -541
- oceanarray/stage3.py +0 -2494
- oceanarray/tools.py +0 -400
- oceanarray/transports.py +0 -1
- oceanarray-0.1.0.dist-info/METADATA +0 -503
- oceanarray-0.1.0.dist-info/RECORD +0 -76
- {oceanarray-0.1.0.dist-info → oceanarray-0.2.0.dist-info}/WHEEL +0 -0
- {oceanarray-0.1.0.dist-info → oceanarray-0.2.0.dist-info}/entry_points.txt +0 -0
- {oceanarray-0.1.0.dist-info → oceanarray-0.2.0.dist-info}/licenses/LICENSE +0 -0
- {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
|
-
|
|
9
|
-
"
|
|
10
|
-
"
|
|
11
|
-
"
|
|
12
|
-
"readers",
|
|
13
|
-
"stage1",
|
|
14
|
-
"stage2",
|
|
15
|
-
"time_gridding",
|
|
11
|
+
# Subpackages (canonical locations)
|
|
12
|
+
"analysis",
|
|
13
|
+
"config",
|
|
14
|
+
"processors",
|
|
16
15
|
"tools",
|
|
17
|
-
|
|
16
|
+
# Top-level modules
|
|
17
|
+
"parameters",
|
|
18
|
+
"plotters",
|
|
18
19
|
"utilities",
|
|
19
|
-
|
|
20
|
+
# Public API
|
|
21
|
+
"process",
|
|
20
22
|
]
|
oceanarray/_version.py
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
__version__ = '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
|
|
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(
|
|
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 ('
|
|
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
|
|
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 =
|
|
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
|
+
)
|