Example: Reading ADCP Data with MHKiT

The following example demonstrates a simple workflow for analyzing Acoustic Doppler Current Profiler (ADCP) data using MHKiT. MHKiT has brought the DOLfYN codebase in as an MHKiT module for working with ADCP and Acoustic Doppler Velocimeter (ADV) data. The DOLfYN MHKiT module is transferring functionality in two parts. In phase 1 the basic IO and core functions of DOLfYN are brought in. These functions include reading instrument data and rotating thru coordinate systems. In phase 2 DOLfYN analysis functions will be brought in. As phase 2 is still in progress, the analysis tools from the DOLfYN package are only available in python.
A typical ADCP data workflow is broken down into
  1. Review the raw data (Check timestamps, Calculate/check that the depth bin locations are correct, Look at velocity, beam amplitude and/or beam correlation data quality)
  2. Remove data located above the water surface or below the seafloor
  3. Check for spurious datapoints and remove if necessary
  4. If not already done within the instrument, average the data into time bins of a set time length (normally 5 to 10 min)
  5. Conduct further analysis as required

Read Raw Instrument Data

The core benefit of DOLfYN is that it can read in raw data directly after transferring it off of the ADCP. The ADCP used here is a Nortek Signature1000, with the file extension '.ad2cp'. This specific dataset contains several hours worth of velocity data collected at 1 Hz from the ADCP mounted on a bottom lander in a tidal inlet. The instruments that DOLfYN supports are listed in the docs.
Start by reading in the raw datafile downloaded from the instrument. The read function reads the raw file and dumps the information into an matlab structure, which contains a few groups of variables:
  1. Velocity in the instrument-saved coordinate system (beam, XYZ, ENU)
  2. Beam amplitude and correlation data
  3. Measurements of the instrument's bearing and environment
  4. Orientation matrices DOLfYN uses for rotating through coordinate frames.
Matlab's binary read takes a while to complete (usually around 3 minutes for this file). Using the optional nens keyword, it is possible to only read part of the data. Reading the first 5,000 pings could be accomplished with the command below that is commented out.
ds = dolfyn_read('data/dolfyn/Sig1000_tidal.ad2cp');
Reading file data/dolfyn/Sig1000_tidal.ad2cp
%ds = dolfyn_read('data/dolfyn/Sig1000_tidal.ad2cp','nens',5000);
To see whats in the dataset, it is recommended that users open the ds variable in the workspace. Alternatively, removing the semicolon in the above line will print the connents of ds.

First Steps and QC'ing Data

In future updates to MHKiT-Matlab's Dolfyn functionality users will be able to QC data and set certain helpful parameters such as deployment height.

Review the Data

Now that the data has been cleaned, the next step is to rotate the velocity data into true East, North, Up coordinates.
ADCPs use an internal compass or magnetometer to determine magnetic ENU directions. The set_declination function takes the user supplied magnetic declination (which can be looked up online for specific coordinates) and adjusts the velocity data accordingly.
Instruments save vector data in the coordinate system specified in the deployment configuration file. To make the data useful, it must be rotated through coordinate systems ("beam"<->"inst"<->"earth"<->"principal"), done through the `rotate2` function. If the "earth" (ENU) coordinate system is specified, DOLfYN will automatically rotate the dataset through the necessary coordinate systems to get there.
Because this ADCP data was already in the "earth" coordinate system, `rotate2` will return the input dataset. `set_declination` will run correctly no matter the coordinate system.
ds = set_declination(ds, 15.8);
ds = rotate2(ds, 'earth');
Data is already in the earth coordinate system
To rotate into the principal frame of reference (streamwise, cross-stream, vertical), if desired, we must first calculate the depth-averaged principal flow heading and add it to the dataset attributes. Then the dataset can be rotated using the same `rotate2` function.
depth_averaged_velocity = mean(squeeze(ds.vel.data), 2);
Here we average the data over the depth or 'range'. To determine what each dimension represents, users can look at the dims field of each variable.
ds.vel.dims
ans = 1×3 cell
'time' 'range' 'dir'
ds.attrs.principal_heading = calc_principal_heading(depth_averaged_velocity, true);
ds_streamwise = rotate2(ds, 'principal');
Because this deployment was set up in "burst mode", the next standard step in this analysis is to average the velocity data into time bins. This and other features (such as the QC mentioned above will be in the next stage of Dolfyn development).

Saving and Loading Dolfyn datasets

Datasets can be saved and loaded using the write_netcdf and read_netcdf functions, respectively.
% Uncomment these lines to save and load to your current working directory
% write_netcdf(ds, 'your_data.nc');
% ds_saved = read_netcdf('your_data.nc');