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
load_data
(correct_heading - Awaiting publication, contact Bastien Queste for access)
_velocity_soundspeed_correction
_quality_control_velocities
_determine_velocity_measurement_depths
_regrid_beam_velocities_to_isobars
_rotate_BEAMS_to_XYZ
_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
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.
(Optional steps:) - Not coded up yet
assess_shear_bias - Not coded up yet
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
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 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
visualise
regress_bias
correct_bias
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
visualise - Produce collection of plots used to visalise estimated shear bias
regress_bias - Determine shear bias correction coefficients by empirically minimimising the slope of various linear regressions
correct_bias - Calculate the artificial velocity profile created by the shear bias and correct it in a new variable
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.