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.
`clean`	Module containing functions to clean data
`VelBinner`	This is the base binning (averaging) tool.

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.
`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.
`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)
`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) – 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) – 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 and salinity are used to calculate seawater density, which is in turn used with the pressure data to calculate depth.

Parameters

ds (xarray.Dataset) – The full adcp dataset
salinity (numeric) – Water salinity in 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 at normal atmospheric pressure according to the UNESCO 1981 equation of state. Does not include hydrostatic pressure.

dolfyn.adp.clean.nan_beyond_surface(ds, val=nan, 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) – Specifies the value to set the bad values to (default np.nan).
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) – 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) – The length of the median-filtering kernel nfilt must be odd.

Returns

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