ADCP Module

This module contains routines for reading and working with ADP/ADCP data. It contains:

`read`	Read a binary Nortek (e.g., .VEC, .wpr, .ad2cp, etc.) or RDI (.000, .PD0, .ENX, etc.) data file.
`load`	Load xarray dataset from netCDF (.nc)
`rotate2`	Rotate a dataset to a new coordinate system.
`calc_principal_heading`	Compute the principal angle of the horizontal velocity.
`clean`	Module containing functions to clean data
`VelBinner`	This is the base binning (averaging) tool.
`ADPBinner`	A class for calculating turbulence statistics from ADCP data

Quick Example

# Start by importing DOLfYN:
import dolfyn
import dolfyn.adp.api as api

# Then read a file containing adv data:
ds = dolfyn.read_example('BenchFile01.ad2cp')

# This ADCP was sitting 0.5 m up from the seabed
# in a tripod
api.clean.set_range_offset(ds, h_deploy=0.5)

# Filter the data by low correlation values (< 50% here)
ds = api.clean.correlation_filter(ds, thresh=50)

# Rotate data from the instrument to true ENU (vs magnetic) frame:
# First set the magnetic declination
dolfyn.set_declination(ds, 10)  # 10 degrees East
dolfyn.rotate2(ds, 'earth')

# At any point you can save the data:
#dolfyn.save(dat_cln, 'adcp_data.nc')

# And reload the data:
#dat_copy = dolfyn.load('adcp_data.nc')

Cleaning Data

`set_range_offset`	Adds an instrument's height above seafloor (for an up-facing instrument) or depth below water surface (for a down-facing instrument) to the range coordinate.
`find_surface`	Find the surface (water level or seafloor) from amplitude data and adds the variable "depth" to the input Dataset.
`find_surface_from_P`	Calculates the distance to the water surface.
`nan_beyond_surface`	Mask the values of 3D data (vel, amp, corr, echo) that are beyond the surface.
`correlation_filter`	Filters out data where correlation is below a threshold in the along-beam correlation data.
`medfilt_orient`	Median filters the orientation data (heading-pitch-roll or quaternions)
`val_exceeds_thresh`	Find values of a variable that exceed a threshold value, and assign "val" to the velocity data where the threshold is exceeded.
`fillgaps_time`	Fill gaps (nan values) in var across time using the specified method
`fillgaps_depth`	Fill gaps (nan values) in var along the depth profile using the specified method

Module containing functions to clean data

dolfyn.adp.clean.set_range_offset(ds, h_deploy)[source]

Adds an instrument’s height above seafloor (for an up-facing instrument) or depth below water surface (for a down-facing instrument) to the range coordinate. Also adds an attribute to the Dataset with the current “h_deploy” distance.

Parameters:

ds (xarray.Dataset) – The adcp dataset to ajust ‘range’ on
h_deploy (numeric) – Deployment location in the water column, in [m]

Returns:

None, operates “in place”

Notes

Center of bin 1 = h_deploy + blank_dist + cell_size

Nortek doesn’t take h_deploy into account, so the range that DOLfYN calculates distance is from the ADCP transducers. TRDI asks for h_deploy input in their deployment software and is thereby known by DOLfYN.

If the ADCP is mounted on a tripod on the seafloor, h_deploy will be the height of the tripod +/- any extra distance to the transducer faces. If the instrument is vessel-mounted, h_deploy is the distance between the surface and downward-facing ADCP’s transducers.

dolfyn.adp.clean.find_surface(ds, thresh=10, nfilt=None)[source]

Find the surface (water level or seafloor) from amplitude data and adds the variable “depth” to the input Dataset.

Parameters:

ds (xarray.Dataset) – The full adcp dataset
thresh (int (default: 10)) – Specifies the threshold used in detecting the surface. (The amount that amplitude must increase by near the surface for it to be considered a surface hit)
nfilt (int (default: None)) – Specifies the width of the median filter applied, must be odd

Returns:

None, operates “in place”

dolfyn.adp.clean.find_surface_from_P(ds, salinity=35)[source]

Calculates the distance to the water surface. Temperature, salinity, and pressure are used to calculate seawater density, which is in turn used to calculate depth.

Parameters:

ds (xarray.Dataset) – The full adcp dataset
salinity (numeric (default: 35)) – Water salinity in parts per thousand (ppt) or practical salinity units (psu)

Returns:

None, operates “in place” and adds the variables “water_density” and
”depth” to the input dataset.

Notes

Requires that the instrument’s pressure sensor was calibrated/zeroed before deployment to remove atmospheric pressure.

Calculates seawater density using a linear approximation of the sea water equation of state:

\[\rho - \rho_0 = -\alpha (T-T_0) + \beta (S-S_0) + \kappa P\]

Where \(\rho\) is water density, \(T\) is water temperature, \(P\) is water pressure, \(S\) is practical salinity, \(\alpha\) is the thermal expansion coefficient, \(\beta\) is the haline contraction coefficient, and \(\kappa\) is adiabatic compressibility.

dolfyn.adp.clean.nan_beyond_surface(ds, val=nan, beam_angle=None, inplace=False)[source]

Mask the values of 3D data (vel, amp, corr, echo) that are beyond the surface.

Parameters:

ds (xarray.Dataset) – The adcp dataset to clean
val (nan or numeric (default: np.nan)) – Specifies the value to set the bad values to
beam_angle (int (default: dataset.attrs['beam_angle'])) – ADCP beam inclination angle
inplace (bool (default: False)) – When True the existing data object is modified. When False a copy is returned.

Returns:

ds (xarray.Dataset) – Sets the adcp dataset where relevant arrays with values greater than depth set to NaN

Notes

Surface interference expected to happen at distance > range * cos(beam angle) - cell size

dolfyn.adp.clean.correlation_filter(ds, thresh=50, inplace=False)[source]

Filters out data where correlation is below a threshold in the along-beam correlation data.

Parameters:

ds (xarray.Dataset) – The adcp dataset to clean.
thresh (numeric (default: 50)) – The maximum value of correlation to screen, in counts or %
inplace (bool (default: False)) – When True the existing data object is modified. When False a copy is returned.

Returns:

ds (xarray.Dataset) – Elements in velocity, correlation, and amplitude are removed if below the correlation threshold

Notes

Does not edit correlation or amplitude data.

dolfyn.adp.clean.medfilt_orient(ds, nfilt=7)[source]

Median filters the orientation data (heading-pitch-roll or quaternions)

Parameters:

ds (xarray.Dataset) – The adcp dataset to clean
nfilt (numeric (default: 7)) – The length of the median-filtering kernel nfilt must be odd.

Returns:

ds (xarray.Dataset) – The adcp dataset with the filtered orientation data