read.adp.ad2cp: Read a Nortek AD2CP File

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().

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