read.adp.ad2cp: Read an adp File in Nortek AD2CP Format

Description

This function is under active development and may change without notice. In contrast with other oce reading functions, read.adp.ad2cp() focusses just on one data type within the source file. Another difference is that it can either return an object holding the data or just a data frame holding a description of the data types in the file; indeed, the latter is the default. See “Details” for more on the reasons for these departures from the usual oce pattern.

Usage

read.adp.ad2cp(
  file,
  from = 1L,
  to = 0L,
  by = 1L,
  dataType = NULL,
  dataSet = 1L,
  tz = getOption("oceTz"),
  longitude = NA,
  latitude = NA,
  plan,
  TOC = FALSE,
  debug = getOption("oceDebug"),
  orientation,
  distance,
  monitor,
  despike,
  ...
)

Value

read.adp.ad2cp() returns either an adp object or the number of data sets within the file, according to the value of TOC.

Arguments

file: a connection or a character string giving the name of the file to load.
from: an integer indicating the index number of the first record to read. This must equal 1, for this version of read.adp.ad2cp. (If not provided, from defaults to 1.)
to: an integer indicating the final record to read. If to is 0L, which is the default, then the value is changed internally to 1e9, and reading stops at the end of the file.
by: ignored.
dataType: an indication of the data type to be extracted. If this is NULL (the default) then read.adp.ad2cp() returns a data frame indicating the data type occurrence rate in the file. Otherwise, dataType must be either a numeric or character value (see “Details”). In the numeric case, which includes both base-10 numbers and raw values, dataType is converted to an integer that is taken to indicate the data type via ID. The permitted values follow the Nortek convention, a summary of which is shown the table at the start of the “Details” section. In the character case, it must be a string taken from that same table.
dataSet: a positive integer that indicates which of the possibly several data sets stored within a file is to be focussed upon. By default, the first data set is chosen. Note that data sets are found by trying to match each text data chunk against the regular expression "^GETCLOCKSTR,TIME=".
tz: a character value indicating time zone. This is used in interpreting times stored in the file.
longitude, latitude: numerical values indicating the observation location.
plan: optional integer specifying which 'plan' to focus on (see
TOC: a logical value. If this is FALSE (the default) then the other parameters of the function are used to select data from the indicated filename, and an adp object is returned. However, if TOC is TRUE, then the number of datasets held within the file is returned.
debug: an integer value indicating the level of debugging. Set to 1 to get a moderate amount of debugging information, from the R code only, to 2 to get some debugging information from the C++ code that is used to parse the data chunks, or to 3 for intensive debugging at both levels.
orientation, distance, monitor, despike: ignored, provided only for calling compatibility with other functions that read adp files. A warning is issued if any of these is supplied in a call to read.adp.ad2cp().
...: ignored parameters that might be passed to read.adp.ad2cp() by read.oce().

Sample of Usage


d <- read.adp.ad2cp("~/test.ad2cp", to=100) # or read.oce()

How the binary file is decoded

This file type, like other acoustic-Doppler types, is read with a hybrid R/C++ system, for efficiency. The processing steps are sketched below, for users who want to inspect the code or build upon it.

In R, readBin() is used to insert the file contents into a vector of type raw.
In C++, this raw vector is scanned byte by byte, to find the starting indices of data "chunks", or subsections of the data that correspond to individual sampling times. Checksum computations are also done at this stage, to detect possible data corruption. Warnings are issued for any bad chunks, and they are skipped in further processing. The valid starting points are then passed back to R as a vector of type integer.
In R, readBin() is used to read the components of each chunk. For speed, this is done in a vectorized fashion. For example, all the velocities in the whole file are read in a single call to readBin(). This process is done for each of the data fields that are to be handled. Importantly, these readBin() calls are tailored to the data, using values of the size, endian and signed parameters that are tailored to the structure of the given component. Scaling factors are then applied as required, to convert the components to physical units.
Finally, in R, the acquired items are inserted into the data or metadata slot of the return value, according to oce convention.

Author

Dan Kelley

Details

Why does read.adp.ad2cp() focus only on parts of the data file? The answer lies in the AD2CP format itself, which may combine data subsets of such differing natures as to break with the oce system of pairing a metadata slot with a data slot. For example, in a conventional ADP dataset, the metadata slot has items for the sampling times, the number of beams, the blanking distance, the cell size, the number of cells, etc. Such items have a natural pairing with elements of the data slot, and oce uses this pairing in constructing plots and other items. However, an AD2CP file might combine such data with echosounder measurements, and these will have different values for number of beams and so forth. This poses a challenge in naming conventions within the oce object, with ripple effects for plotting and data access. Those ripple effects would extend beyond oce itself to user code. To avoid such problems, read.adp.ad2cp() is designed to focus on one data type at a time, relying on users to keep track of the resultant object, perhaps to combine it with other objects from within the AD2CP file or other files, in the normal R manner.

The permitted values for dataType are shown in the table below; the dataType argument of read.adp.ad2cp() may be chosen from any of the three columns in this table.

code (raw)	code (integer)	oce name
----------	--------------	-----------------
`0x15`	21	`burst`
`0x16`	22	`average`
`0x17`	23	`bottomTrack`
`0x18`	24	`interleavedBurst`
`0x1a`	26	`burstAltimeterRaw`
`0x1b`	27	`DVLBottomTrack`
`0x1c`	28	`echosounder`
`0x1d`	29	`DVLWaterTrack`
`0x1e`	30	`altimeter`
`0x1f`	31	`averageAltimeter`
`0x23`	35	`echosounderRaw`
`0xa0`	160	`text`

References

Nortek AS. “Signature Integration 55|250|500|1000kHz.” Nortek AS, 2017.

Nortek AS. “Signature Integration 55|250|500|1000kHz.” Nortek AS, 2018.

Nortek AS. “Signature Integration 55|250|500|1000kHz.” Nortek AS, March 31, 2022.

Examples

Run this code

library(oce)
# You can run this within the oce directory, if you clone from github.
file <- "tests/testthat/local_data/ad2cp/S102791A002_Barrow_v2.ad2cp"
if (file.exists(file)) {
    library(oce)
    d <- read.oce(file)
}

Run the code above in your browser using DataLab