Functions in the vel module

(Content automatically geneated from the source code)

KOBBE.VEL

Functions for processing ocean and sea ice drift velocity.

kobbe.vel.calculate_ice_vel(ds: Dataset, avg_method: str = 'mean', min_per_ensemble: float = 1, sspd_scaling: bool = False, true_sspd_name: str = 'sound_speed_CTD') → Dataset

Calculate sea ice drift velocity from the AverageIce fields.

Parameters:

dsxarray.Dataset

Input dataset containing the AverageIce velocity components.

avg_methodstr, optional

Method to calculate ensemble average (‘median’ or ‘mean’). Default is ‘mean’.

min_per_ensembleint, optional

Minimum number of samples required to produce a valid ensemble average.

sspd_scalingbool, optional

If True, scales the ice velocity by the ratio of actual sound speed to averaged sound speed.

true_sspd_namestr, optional

The name of the dataset field containing the true sound speed values. Default is ‘sound_speed_CTD’.

Returns:

xarray.Dataset

Updated dataset with ‘uice’ and ‘vice’ fields added.

kobbe.vel.calculate_ocean_vel(ds: Dataset, avg_method: str = 'mean', orientation: str = 'up', sspd_scaling: bool = False, true_sspd_name: str = 'sound_speed_CTD') → Dataset

Calculate ocean velocity from the Average_VelEast and Average_VelNorth fields.

Parameters:

dsxarray.Dataset

Input dataset containing the Average_VelEast and Average_VelNorth fields.

avg_methodstr, optional

Method to calculate ensemble average (‘median’ or ‘mean’). Default is ‘mean’.

orientationstr [‘up’, ‘dn’]

Vertical orientation of the acoustic beam.

sspd_scalingbool, optional

If True, scales the ice velocity by the ratio of actual sound speed to averaged sound speed.

true_sspd_namestr, optional

The name of the dataset field containing the true sound speed values. Default is ‘sound_speed_CTD’.

Returns:

xarray.Dataset

Updated dataset with ‘ucur’ and ‘vcur’ fields added.

kobbe.vel.calculate_uvcur_avg(ds: Dataset, avg_method: str = 'mean', min_good_pct: float | None = None) → Dataset

Calculate ensemble average ocean velocity.

Parameters:

dsxarray.Dataset

Input dataset containing ocean velocity components.

avg_methodstr, optional

Method to calculate ensemble average (‘median’ or ‘mean’). Default is ‘mean’.

min_good_pctfloat, optional

Minimum percentage of good samples required for a bin to be included in the average. Default is None.

Returns:

xarray.Dataset

Updated dataset with ‘UCUR’ and ‘VCUR’ fields added.

kobbe.vel.clear_empty_bins(ds: Dataset, thr_perc: float = 5) → Dataset

Remove bins where less than thr_perc percent of the samples contain valid (non-NaN) data.

This function examines each bin along the VEL_BIN dimension and removes bins that have a high proportion of missing data (NaNs). The threshold percentage (thr_perc) defines the minimum percentage of valid samples required to retain a bin.

Parameters:

dsxr.Dataset

The input dataset containing the VEL_BIN dimension and data with potential NaNs.

thr_percfloat, optional

The threshold percentage of valid (non-NaN) data required to keep a bin. Default is 5%.

Returns:

xr.Dataset

The dataset with bins removed where the percentage of valid data is below thr_perc.

kobbe.vel.interp_oceanvel(ds: Dataset, target_depth: float) → Dataset

Interpolate ocean velocity components (ucur, vcur) to a fixed depth (target_depth).

This function interpolates the ocean velocity components from the measured bin depths to a specified target depth. The interpolated velocities are added to the dataset with names indicating the target depth.

Parameters:

dsxr.Dataset

The input dataset containing the ocean velocity components (ucur, vcur) and their associated depths (BIN_DEPTH) over time.

target_depthfloat

The depth (in meters) to which the velocities should be interpolated.

Returns:

xr.Dataset

The dataset with added velocity components interpolated to the specified depth. The new variables are named UCUR_<depth>m and VCUR_<depth>m.

kobbe.vel.reject_sidelobe(ds: Dataset) → Dataset

Mask samples where we expect sidelobe interference based on the calculated maximum range (Rmax).

From Nortek documentation (nortekgroup.com/assets/software/N3015-011-SignaturePrinciples.pdf):

Maximum range Rmax is given by:

  1. Rmax = A * cos(θ) - s_c

Where:

  • A is the distance between the transducer and the surface.

  • θ (theta) is the beam angle, assumed to be 25 degrees for Nortek Signatures.

  • s_c is the velocity cell size.

The distance A is calculated as:

  1. A = DEP - ICE_DRAFT

Where:

  • DEP is the sample-mean depth of the water column.

  • ICE_DRAFT is the sample-mean sea ice draft (using SEA_ICE_DRAFT_MEDIAN_LE if available, otherwise 0).

We use the sample mean tilt for θ.

This function identifies and masks (sets to NaN) the velocity samples (ucur, vcur) in regions close enough to the surface where sidelobe

interference is expected, based on the calculated Rmax.

Parameters:

dsxr.Dataset

The input dataset containing ocean velocity components (ucur, vcur), depth, bin depth, and possibly sea ice draft information.

Returns:

xr.Dataset

The dataset with sidelobe-affected velocity samples masked (set to NaN).

kobbe.vel.rotate_vels_magdec(ds: Dataset, avg_method: str = 'mean') → Dataset

Rotate ocean and ice velocities to account for magnetic declination.

This function rotates the processed fields (ucur, vcur, uice, vice) by the magnetic declination angle to correct for geographic referencing. It does not modify raw variables (e.g., Average_VelNorth).

Average velocities (UCUR, VCUR, UICE,`VICE`) are recalculated after rotating.

Parameters:

dsxr.Dataset

The input dataset containing ocean and ice velocity components.

avg_methodstr, optional

Method to calculate ensemble average (‘median’ or ‘mean’). Default is ‘mean’.

Returns:

xr.Dataset

The dataset with rotated velocity components to account for magnetic declination.

kobbe.vel.sound_speed_correction(ds: Dataset, true_sspd_name: str = 'sound_speed_CTD') → Dataset
kobbe.vel.uvoc_mask_range(ds: Dataset, uv_max: float = 1.5, tilt_max: float = 5, sspd_range: Tuple[float, float] = (1400, 1560), cor_min: float = 60, amp_range: Tuple[float, float] = (30, 85), max_amp_increase: float = 20, return_proc_string: bool = False) → Dataset

Apply a series of masking criteria to ocean velocity components ucur and vcur.

Masking criteria: 1. Speed exceeds uv_max (m/s). 2. Tilt exceeds tilt_max (degrees). 3. Instrument-recorded sound speed is outside sspd_range (m/s). 4. Any beam correlation is below cor_min (percent). 5. Any beam amplitude is outside amp_range (dB). 6. There is a bin-to-bin amplitude jump greater than max_amp_increase (dB).

Parameters:

dsxr.Dataset

The input dataset containing ocean velocity components and related data.

uv_maxfloat, optional

Maximum allowable ocean velocity magnitude (default is 1.5 m/s).

tilt_maxfloat, optional

Maximum allowable tilt (default is 5 degrees).

sspd_rangeTuple[float, float], optional

Acceptable range of sound speed (default is 1400 to 1560 m/s).

cor_minfloat, optional

Minimum allowable beam correlation (default is 60%).

amp_rangeTuple[float, float], optional

Acceptable range of beam amplitudes (default is 30 to 85 dB).

max_amp_increasefloat, optional

Maximum allowable bin-to-bin amplitude increase (default is 20 dB).

return_proc_string:

Whether to return a processing string (to be removed - drop)

Returns:

xr.Dataset

The dataset with ucur and vcur masked according to the specified criteria.