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 as dlfn
import dolfyn.adp.api as api

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

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

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

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

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

# And reload the data:
dat_copy = dlfn.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 of depth bins
`find_surface`	Find the surface (water level or seafloor) from amplitude data
`surface_from_P`	Approximates distance to water surface above ADCP from the pressure sensor.
`nan_beyond_surface`	Mask the values of the data that are beyond the surface.
`vel_exceeds_thresh`	Find values of the velocity data that exceed a threshold value, and assign NaN to the velocity data where the threshold is exceeded.
`correlation_filter`	Filters out velocity data where correlation is below a threshold in the beam correlation data.
`medfilt_orient`	Median filters the orientation data (heading-pitch-roll or quaternions)
`fillgaps_time`	Fill gaps (nan values) across time using the specified method
`fillgaps_depth`	Fill gaps (nan values) 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 of depth bins

Parameters

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

Returns

ds (xarray.Dataset) – The adcp dataset with ‘range’ adjusted

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

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

ds (xarray.Dataset) – The full adcp dataset with depth added

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

Approximates distance to water surface above ADCP from the pressure sensor.

Parameters

ds (xarray.Dataset) – The full adcp dataset
salinity (numeric) – Water salinity in psu

Returns

ds (xarray.Dataset) – The full adcp dataset with depth added

Notes

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

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

Mask the values of the data 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).

Returns

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

Notes

Surface interference expected to happen at r > depth * cos(beam_angle)

dolfyn.adp.clean.vel_exceeds_thresh(ds, thresh=5, val=nan)[source]

Find values of the velocity data that exceed a threshold value, and assign NaN to the velocity data where the threshold is exceeded.

Parameters

ds (xr.Dataset) – The adcp dataset to clean
thresh (numeric) – The maximum value of velocity to screen
val (nan or numeric) – Specifies the value to set the bad values to (default np.nan)

Returns

ds (xarray.Dataset) – The adcp dataset with datapoints beyond thresh are set to val

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

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

Parameters

ds (xarray.Dataset) – The adcp dataset to clean.
thresh (numeric) – The maximum value of correlation to screen, in counts or %
val (numeric) – Value to set masked correlation data to, default is nan

Returns

ds (xarray.Dataset) – The adcp dataset with low correlation values set to val

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