gliderad2cp API

Calculate shear from a Nortek AD2CP mounted on a glider. Compatible with any glider as long as the ADCP is returning data for the 4 beams. TODO: make compatible with the 3-beam configuration.

gliderad2cp.process_shear

process

The main function which converts beam velocity data shear in the ENU directions.

load_data

Loads AD2CP netcdf file and creates supplemental variables based on input glider data.

_velocity_soundspeed_correction

Correct for salinity error in the soundspeed calculation.

_quality_control_velocities

Removes bad velocity measurements based on velocity, amplitude and correlation criteria defined in options.

_determine_velocity_measurement_depths

Determines what depth each velocity measurement was taken at for each beam, account for glider attitude.

_regrid_beam_velocities_to_isobars

Regrids beam velocities onto isobars to avoid shear smearing in the final shear data.

_rotate_BEAMS_to_XYZ

Transforms velocity measurements from along-beam coordinates to XYZ coordinates.

_rotate_XYZ_to_ENU

Rotates velocity measurements in XYZ coordinates into ENU coordinates.

Notes

.process() runs the following functions in this order

  1. load_data

  2. (correct_heading - Awaiting publication, contact Bastien Queste for access)

  3. _velocity_soundspeed_correction

  4. _quality_control_velocities

  5. _determine_velocity_measurement_depths

  6. _regrid_beam_velocities_to_isobars

  7. _rotate_BEAMS_to_XYZ

  8. _rotate_XYZ_to_ENU

gliderad2cp.process_shear._determine_velocity_measurement_depths(ADCP, options)[source]

Determines what depth each velocity measurement was taken at for each beam, account for glider attitude.

Inputs

ADCPxr.Dataset

GliderAD2CP format xr.Dataset produced by the gliderad2cp.load_data() function.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function. Requires ‘ADCP_mounting_direction’ to be either ‘top’ or ‘bottom’.

Outputs

ADCPxr.Dataset

Same as input with additional D1, D2, D3 and D4 depth variabiles.

gliderad2cp.process_shear._quality_control_velocities(ADCP, options)[source]

Removes bad velocity measurements based on velocity, amplitude and correlation criteria defined in options.

Inputs

ADCPxr.Dataset

GliderAD2CP format xr.Dataset produced by the gliderad2cp.load_data() function.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function. Requires ‘ADCP_mounting_direction’ to be either ‘top’ or ‘bottom’.

Outputs

ADCPxr.Dataset

Same as input with bad velocity data replaced with NaNs.

gliderad2cp.process_shear._regrid_beam_velocities_to_isobars(ADCP, options)[source]

Regrids beam velocities onto isobars to avoid shear smearing in the final shear data.

Inputs

ADCPxr.Dataset

GliderAD2CP format xr.Dataset produced by the gliderad2cp.load_data() function.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function. Requires ‘ADCP_mounting_direction’ to be either ‘top’ or ‘bottom’.

Outputs

ADCPxr.Dataset

Same as input but with the additional gridded_bin dimension (defined as range from the glider), and the V1, V2, V3, V4 velocities which are velocities from beams 1-4 projected onto isobars.

gliderad2cp.process_shear._rotate_BEAMS_to_XYZ(ADCP, options)[source]

Coordinate transform that converts BEAM velocities to glider relative velocities X, Y, Z. Those of you with a keen eye will notice we rely on the redundancy of 4 beams to calculate 3 beam which allows you to estimate values of any missing beam from the others. We do this for a specific - and I promise you, rather clever - reason. You see, if we could calculate from 3 beams, but X would not be aligned to glider pitch. So either we rotate the resulting matrix, or we simply calculate from the original 4 beam matrix.

TODO : Bastien Queste : double check a 3-beam algorithm gives the same result.

Inputs

ADCPxr.Dataset

GliderAD2CP format xr.Dataset produced by the gliderad2cp.load_data() function.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function. Requires ‘ADCP_mounting_direction’ to be either ‘top’ or ‘bottom’.

Outputs

ADCPxr.Dataset

Same as input but with the additional X, Y and Z velocities (X aligned with the glider, Z aligned with ADCP direction)

gliderad2cp.process_shear._rotate_XYZ_to_ENU(ADCP, options)[source]

Coordinate transform that converts velocity estimates relative to the glider (X, Y, Z) into the earth relative reference frame east, north, up (ENU)

Inputs

ADCPxr.Dataset

GliderAD2CP format xr.Dataset produced by the gliderad2cp.load_data() function.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function. Requires ‘ADCP_mounting_direction’ to be either ‘top’ or ‘bottom’.

Outputs

ADCPxr.Dataset

Same as input but with the additional X, Y and Z velocities (X aligned with the glider, Z aligned with ADCP direction)

gliderad2cp.process_shear._velocity_soundspeed_correction(ADCP)[source]

Corrects along beam velocity data for lack of salinity measurements in ADCP default soundspeed settings.

Inputs

ADCPxr.Dataset

GliderAD2CP format xr.Dataset produced by the gliderad2cp.load_data() function.

Outputs

ADCPxr.Dataset

Same as input, with correction for sound speed applied to along beam velocities.

gliderad2cp.process_shear.load_data(adcp_file_path, glider_file_path, options)[source]

Loads AD2CP netcdf file and creates supplemental variables based on input glider data.

Inputs

adcp_file_pathstr

Path to the AD2CP netcdf files created by the Nortek MIDAS software. Can handle wildcards through glob.

glider_file_pathstr

Path to the glider file containing time, latitude, longitude, soundspeed, and profile_num. Can be csv, pandas or xarray. Can also pass pandas or xarray dataframes directly.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function.

Outputs

ADCPxr.Dataset

xr.Dataset of the AD2CP netcdf with necessary glider variables interpolated onto the time dimension, with some minor cleaning of coordinates.

optionsdict

Same as the input options with the very important addition of ADCP mounting direction if the ‘auto’ option is set for ‘ADCP_mounting_direction’.

glider_datapd.Dataframe

pd.Dataframe of the input glider data. Serves no real purpose but may be helpful in debugging. Discarded when called from .process()

gliderad2cp.process_shear.process(adcp_file_path, glider_file_path, options=None)[source]

Calculate shear from a Nortek AD2CP mounted on a glider. Compatible with any glider as long as the ADCP is returning data for the 4 beams.

Inputs

adcp_file_pathstr

Path to the AD2CP netcdf files created by the Nortek MIDAS software. Can handle wildcards through glob.

glider_file_pathstr

Path to the glider file containing time, latitude, longitude, soundspeed, and profile_num. Can be csv, pandas or xarray. Can also pass pandas or xarray dataframes directly.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function.

Outputs

ADCPxr.Dataset

xr.Dataset of the AD2CP netcdf with many supplemental variables, most importantly X, Y, Z and E, N, U velocities projected onto isobars to avoid shear smearing.

Notes

.process() runs the following functions in this order 1. load_data - load data from a Nortek AD2CP netCDF file and a glider data file or dataset 2. (correct_heading - Awaiting publication, contact Bastien Queste for access) 3. _velocity_soundspeed_correction- Corrects along beam velocity data for lack of salinity measurements in ADCP default soundspeed settings. 4. _quality_control_velocities - Removes bad velocity measurements based on velocity, amplitude and correlation criteria defined in options 5. _determine_velocity_measurement_depths - Determines what depth each velocity measurement was taken at for each beam, account for glider attitude 6. _regrid_beam_velocities_to_isobars - Regrids beam velocities onto isobars to avoid shear smearing in the final shear data 7. _rotate_BEAMS_to_XYZ - Coordinate transform that converts BEAM velocities to glider relative velocities X, Y, Z 8. _rotate_XYZ_to_ENU - Coordinate transform that converts velocity estimates relative to the glider (X, Y, Z) into the earth relative reference frame east, north, up (ENU)

Calculate depth-resolved currents from shear data calculated by the gliderAD2CP.process_shear.process() function. This functionality can handle loiter dives and irregular profiles but it requires that your ADCP is always on so that DAC is representative of the baroclinic profile collected by the ADCP.

gliderad2cp.process_currents

process

The main function which converts shear data from gliderAD2CP.process_shear.process() to referenced velocities.

get_DAC

Calculate dive-averaged currents using the ADCP as a DVL.

_grid_shear

Grid shear according to specifications.

_grid_velocity

Assemble shear measurements to reconstruct velocity profiles.

_reference_velocity

Reference vertical velocity profiles to dive-averaged currents, paying attenting to the time spent at each depth.

Notes

.process() runs the following functions in this order

  1. get_DAC - Calculate dive-averaged currents using the ADCP as a DVL.

  2. _grid_shear - Grid shear according to specifications.

  3. _grid_velocity - Assemble shear measurements to reconstruct velocity profiles.

  4. _reference_velocity - Reference vertical velocity profiles to dive-averaged currents, paying attenting to the time spent at each depth.

(Optional steps:) - Not coded up yet

  1. assess_shear_bias - Not coded up yet

  2. correct_shear_bias - Not coded up yet.

gliderad2cp.process_currents._grid_shear(ADCP, options, xi, yi)[source]

Grid shear according to specifications.

Inputs

ADCPxarray.Dataframe

Output from the gliderAD2CP.process_shear() function.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function.

xinumpy.array

Array of bins in x-axis.

yinumpy.array

Array of bins in y-axis.

Outputs

currentsxr.Dataset

Dataset containing gridded shear and various statistical metrics, as well as time spent per bin by the glider.

gliderad2cp.process_currents._grid_velocity(currents, method='integrate')[source]

Assemble shear measurements to reconstruct velocity profiles. Currently only able to integrate in the vertical, but I have aspirations to add the least-squared method too. Untested and likely not compatible with irregular grids.

Inputs

currentsxr.Dataset

Dataset containing gridded shear produced by the process_currents.grid_shear() function.

methodstr, default = ‘integrate’

Which method to use to reconstruct velocity profiles. Currently only “integrate” is available. “lsq” coming one day. maybe.

Outputs

currentsxr.Dataset

Dataset containing gridded shear, statistical metrics, time spent per bin by the glider, and unreferenced velocity profiles.

gliderad2cp.process_currents._reference_velocity(currents, DAC)[source]

Reference vertical velocity profiles to dive-averaged currents, paying attention to the time spent at each depth. This ensures that dives with irregular vertical speeds or periods of loitering at depth are still reproduced correctly. As a result, one cannot expect the depth-averaged velocity of a dive to match the dive-averaged currents.

Inputs

currentsxr.Dataset

Dataset containing gridded shear produced by the process_currents.grid_shear() function.

DACdictionary containing fields :
dac :

Mx2 np.array containing eastward DAC (column 0) and northward DAC (column 1), for M dives identified.

dive_time :

Mx1 np.array containing mean time for the dive in np.datetime64[ns] format.

Outputs

currentsxr.Dataset

Dataset containing gridded shear, statistical metrics, time spent per bin by the glider, and unreferenced velocity profiles.

gliderad2cp.process_currents.get_DAC(ADCP, gps_predive, gps_postdive)[source]

Calculate dive-averaged currents using the ADCP as a DVL.

Inputs

ADCPxarray.Dataframe

Output from the gliderAD2CP.process_shear() function.

gps_predivenumpy.array

Mx3 numpy array where M in the number of dives performed by the glider. Columns are np.datetime64[ns], longitude and latitude.

gps_postdivenumpy.array

Mx3 numpy array where M in the number of dives performed by the glider. Columns are np.datetime64[ns], longitude and latitude.

Outputs

DACdictionary containing :
dac

Mx2 np.array containing eastward DAC (column 0) and northward DAC (column 1), for M dives identified.

dive_time

Mx1 np.array containing mean time for the dive in np.datetime64[ns] format.

dive_duration

Mx1 np.array containing mean duration for the dive in seconds.

dxy_gps, dxy_dvl

Mx2 np.arrays containing eastward (col 0) and northward (col 1) displacement in m, calculated from GPS and from ADCP as a DVL respectively.

gliderad2cp.process_currents.process(ADCP, gps_predive, gps_postdive, options=None)[source]

Calculate depth-resolved currents from shear data calculated by the gliderAD2CP.process_shear.process() function. This functionality can handle loiter dives and irregular profiles but it requires that your ADCP is always on so that DAC is representative of the baroclinic profile collected by the ADCP.

Inputs

ADCPxarray.Dataframe

Output from the gliderAD2CP.process_shear() function.

gps_predivenumpy.array

Mx3 numpy array where M in the number of dives performed by the glider. Columns are np.datetime64[ns], longitude and latitude.

gps_postdivenumpy.array

Mx3 numpy array where M in the number of dives performed by the glider. Columns are np.datetime64[ns], longitude and latitude.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function.

Outputs

currentsxr.Dataset

Dataset containing gridded shear, statistical metrics, time spent per bin by the glider, unreferenced velocity profiles and DAC-referenced velocities.

Notes

.process() runs the following functions in this order

  1. get_DAC - Calculate dive-averaged currents using the ADCP as a DVL.

  2. _grid_shear - Grid shear according to specifications.

  3. _grid_velocity - Assemble shear measurements to reconstruct velocity profiles.

  4. _reference_velocity - Reference vertical velocity profiles to dive-averaged currents, paying attention to the time spent at each depth.

Correct velocity profiles obtained by ADCP gliders for shear-bias (as described in Todd et al., 2017; Sec.3.b.2 https://doi.org/10.1175/JTECH-D-16-0156.1) Applies a different approach to Todd et al. in that we only utilise variance at depth as validation. Instead, we aim to reduce the slope of the linear regression :

profile_mean(shear - shear_bias_correction) = profile_mean_naturally_occuring_shear + slope * displacement_through_water.

We determine two separate shear_bias_correction coefficients, one in the along-glider direction and one in the across glider direction. This is akin to subtracting a portion of the glider’s travel through water.

A second (potentially better) correction is also coded up which subtracts a shear_bias_correction which scales with glider speed. Preliminary work indicates that shear bias is instrument-velocity dependent, but until this is proven/published, this correction remains the non-default correction. NB: the author of this code uses this one all the time.

gliderad2cp.process_bias

process

The main function which will run through the whole shear bias correction automatically for you.

visualise

Function outputting two plots which can be used to assess shear bias and its correction.

regress_bias

Uses a minimisation function to identify optimal correction parameters

correct_bias

Outputs DAC-referenced velocities that have been corrected for shear bias.

__linear_regression

A weighted, linear least squares regression function with optional plotting and indexing capability.

Notes

.process() runs the following functions in this order

  1. visualise

  2. regress_bias

  3. correct_bias

  4. visualise

gliderad2cp.process_bias._linear_regression(x, y, options, c=None, mask=True, plot=False)[source]

Perform an optionally-weighted linear least squares regression on x and y, providing 95% confidence intervals and optionally plotting the data.

Inputs

x,y,cnp.array

Arrays containing x and y values for the linear regression, and an optional color argument for the scatter plot.

maskbool array

Boolean array of same size as x, indicating which values to keep in the regression.

plotbool

If true, produce a plot of the linear regression.

Outputs

slope :

Returns the slope of the linear regression

gliderad2cp.process_bias.correct_bias(currents, options, bias_along_glider, bias_across_glider)[source]
Calculates the artificial velocity profile created by the shear bias and outputs two new variables:

“velocity_{direction}_DAC_reference_sb_corrected” - DAC referenced, shear-bias corrected velocity profiles. “shear_bias_velocity_{direction}” - the velocity profile error induced by the shear bias.

Inputs

currentsxr.Dataset

Dataset containing gridded shear and velocity data produced by the gliderad2cp.process_currents functions.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function.

bias_along_glider, bias_across_gliderfloat

Floats which define the scaling factor applied to the shear bias correction in the along and across glider directions.

Outputs

currentsxr.Dataset

Dataset containing gridded shear, statistical metrics, time spent per bin by the glider, and unreferenced velocity profiles.

gliderad2cp.process_bias.process(currents, options)[source]

Correct velocity profiles obtained by ADCP gliders for shear-bias (as described in Todd et al., 2017; Sec.3.b.2 https://doi.org/10.1175/JTECH-D-16-0156.1) Applies a different approach to Todd et al. in that we only utilise variance at depth as validation. Instead, we aim to reduce the slope of the linear regression :

profile_mean(shear - shear_bias_correction) = profile_mean_naturally_occuring_shear + slope * displacement_through_water.

We determine two separate shear_bias_correction coefficients, one in the along-glider direction and one in the across glider direction. This is akin to subtracting a portion of the glider’s travel through water.

A second (potentially better) correction is also coded up which subtracts a shear_bias_correction which scales with glider speed. Preliminary work indicates that shear bias is instrument-velocity dependent, but until this is proven/published, this correction remains the non-default correction. NB: the author of this code uses this one all the time.

Inputs

currentsxr.Dataset

Dataset containing gridded shear and velocity data produced by the gliderad2cp.process_currents functions.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function.

Outputs

currentsxr.Dataset

Dataset containing gridded shear, statistical metrics, time spent per bin by the glider, and unreferenced velocity profiles.

Notes

.process() runs the following functions in this order

  1. visualise - Produce collection of plots used to visalise estimated shear bias

  2. regress_bias - Determine shear bias correction coefficients by empirically minimimising the slope of various linear regressions

  3. correct_bias - Calculate the artificial velocity profile created by the shear bias and correct it in a new variable

  4. visualise - Produce collection of plots used to visalise estimated shear bias after correction

gliderad2cp.process_bias.regress_bias(currents, options)[source]

Determines shear bias correction coefficients by empirically minimimising the slope of various linear regressions. Linear regressions are performed on displacement through water and mean shear of the water column in combination of directions.

Inputs

currentsxr.Dataset

Dataset containing gridded shear and velocity data produced by the gliderad2cp.process_currents functions.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function.

Outputs

bias_along_glider, bias_across_gliderfloat

Floats which define the scaling factor applied to the shear bias correction in the along and across glider directions.

gliderad2cp.process_bias.visualise(currents, options, plot_all=True)[source]

Produce collection of plots used to estimate shear bias.

Inputs

currentsxr.Dataset

Dataset containing gridded shear and velocity data produced by the gliderad2cp.process_currents functions.

optionsdict

Set of options for gliderAD2CP, created by the gliderad2cp.tools.get_options() function.

Outputs

None

gliderad2cp.download_example_data

Functions for downloading sample datasets

gliderad2cp.download_example_data.load_sample_dataset(dataset_name='SEA055_M82.nc')[source]

Download sample datasets for use with gliderad2cp

Parameters:

dataset_name (str, optional) – Default is “sea045_20230530T0832_delayed.nc”.

Raises:

ValueError: – If the requests dataset is not known, raises a value error

Returns:

Requested sample dataset

Return type:

xarray.Dataset

gliderad2cp.tools

Helper funcitons for gliderad2cp

gliderad2cp.tools.get_options(verbose=True, **kwargs)[source]

Returns a dictionary containing options compatible with gliderAD2CP. Run with no kwargs to output a default dictionary, or with kwargs to return a full dictionary with the chose options

gliderad2cp.tools.grid2d(x, y, v, xi=1, yi=1, fn='median')[source]

Quick data binning function relying on pandas. x,y,v are flat np.arrays of x, y coordinates and values at these points. xi and yi are either np.arrays of bins to be binned into, or the spacing used between min and max of x or y respectively. fn defines the function applied to all points from v that fall into the same bin.

gliderad2cp.tools.interp(x, y, xi)[source]

Interpolation shortcut that removes NaN data and ignores boundary errors.

gliderad2cp.tools.plog(msg)[source]

Output information to the logger with timestamp.