This function reads Nortek AD2CP files, storing data elements in lists within
the data slot. Those elements are named for the ID type in question. For
example, data with ID code 0x16 are stored in data$average; see
ad2cpCodeToName() for the code mapping.
read.adp.ad2cp(
file,
from = 1,
to = 0,
by = 1,
which = "all",
tz = getOption("oceTz"),
ignoreChecksums = FALSE,
longitude = NA,
latitude = NA,
orientation,
distance,
plan,
type,
monitor = FALSE,
despike = FALSE,
processingLog,
debug = getOption("oceDebug"),
...
)An adp object with metadata$fileType equal to "AD2CP", a
table (if which="?"), a data frame (if which="??"), or a vector of
character (if which="text").
a connection or a character string giving the name of the file to load.
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.)
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.
ignored.
a character value indicating the data type(s) to be read, and
stored in the data slot of the returned value. The default, which="all",
means to read all the types. In many cases, though, the user does not want
to read everything at once, either as a way to speed processing or to avoid
running out of memory. For this reason, a common first step is instead to
use which="?", which gives a table of data types in the file or
which="??", which gives a data frame summarizing the data 'chunks'; after
doing those things, the next step is usually to extract all the data, or an
individual type of interest is extracted. The choices of individual type are
as follows:
"burst" for ID code 0x15,
"average" for ID code 0x16,
"bottomTrack" for ID code 0x17,
"interleavedBurst" for ID code 0x18,
"burstAltimeterRaw" for ID code 0x1a,
"DVLBottomTrack" for ID code 0x1b,
"echosounder" for ID code 0x1c,
"DVLWaterTrack" for ID code 0x1d,
"altimeter" for ID code 0x1e,
and
"averageAltimeter" for ID code 0x1f.
a character value indicating time zone. This is used in interpreting times stored in the file.
a logical value indicating whether to ignore checksums. This is FALSE by default, meaning that any data chunk with an improper checksum is ignored. It may be necessary to set this to TRUE to parse some problematic files.
numerical values indicating the observation location.
ignored by read.adp.ad2cp(), and provided only for
similarity to other read.adp.* functions.
ignored by read.adp.ad2cp(), and provided only for similarity
to other read.adp.* functions.
optional integer specifying which 'plan' to focus on (see reference 1 for the meaning of 'plan'). If this is not given, it defaults to the most common plan in the requested subset of the data.
optional character value indicating the type of Nortek
instrument. If this is not provided, an attempt is made to infer it from the
file header (if there is one), and "Signature1000" is used, otherwise. The
importance of knowing the type is for inferring the slantwise beam angle,
which is usd in the conversion from beam coordinates to xyz coordinates. If
type is provided, it must be one of "Signature250", "Signature500", or
"Signature1000"; the first of these has a 20 degree slant-beam angle, while
the others each have 20 degrees (see reference 2, section 2 on page 6). Note
that oceSetMetadata() can be used to alter the slantwise beam angle of an
existing object, and this will alter any later conversion from beam to xyz
coordinates.
a boolean value indicating whether to indicate the progress of
reading the file, by using txtProgressBar() or otherwise. The value of
monitor is changed to FALSE automatically, for non-interactive sessions.
ignored by read.adp.ad2cp(), and provided only for similarity
to other read.adp.* functions.
a character value that, if provided, is saved within the
processingLog slot of the returned value.
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.
ignored.
Early in the year 2022, support was added for 12-byte headers. These are not
described in any Nortek document in the possession of the author of
read.adp.ad2cp(), although some personal communications made via
https://github.com/dankelley/oce/issues have exposed some clues that have led
to provisional, but largely untested, code here.
The “References” section lists some manuals that were consulted during the coding of `read.adp.ad2cp()]. Since instruments evolve over time, one might think that Nortek (2022) would be the best place to start, in coding to read AD2CP files. That would be a mistake, and a big one, at that. There are two reasons for this.
First, Nortek (2022) is not as clear in its description of the data format as Nortek (2017) and Nortek (2018), as exemplified by a few examples.
Nortek (2022) has dropped the explanation of how to compute checksums, which was present in the earlier documents.
The Nortek (2022) explanation of the data format differs from the older explanations and is arguably more difficult to understand. With the new leading-underscore format (see Nortek 2022, page 79), information is spread throughout the document, making it challenging to understand data fields in isolation. The older documents laid things out more clearly, e.g. the average/burst format is laid out in detail, in one place on pages 57 to 64 of Nortek, with the optional fields being clearly labelled in the rightmost column of Table 6.1.3.
Nortek (2022) does not always specify units correctly. For example, on page 82, Pressure is said to have "Unit [dBar]" in green text, but the black text above states "Raw data given as 0.001 dBar". If the stated storage class (uint32) is to be believed, then it seems clear that the unit must be 0.001 dBar, so the green text should be ignored. The same can be said of items throughout the data-format tables. In coding `read.adp.ad2cp()], the green "Unit" text was ignored in basically every case.
Second, Nortek (2022) contains significant errors, e.g. the following.
Nortek (2022 page 89) states the storage class for "Altimeter
data. Altimeter distance" (called AltimeterDistance by the present function)
to be int32, but Nortek (2017, 2018) both state it to be float32. Tests
with actual datasets make it clear that the format is float32, since wild
result are inferred by following the Nortek (2022) guidance.
As above, but for "AST data.AST distance" (called ASTDistance by the
present function).
Dan Kelley
By default, read.adp.ad2cp() reads all ID codes that are in the file.
This can yield very large objects, so if only certain IDs are of interest,
try setting the which document accordingly.
It is important to realize that read.adp.ad2cp() is incomplete, and has not
been well tested. The data format is not documented thoroughly in the
available Nortek manuals, and contradictions between the manuals require an
uncomfortable degree of guesswork; see “Cautionary Notes”.
Nortek AS. “Signature Integration 55|250|500|1000kHz.” Nortek AS, 2017.
Nortek AS. “Signature Integration 55|250|500|1000kHz.” Nortek AS, 2018. (This revision includes new information about instrument orientation.)
Nortek AS. “Signature Integration 55|250|500|1000kHz.” Nortek AS, March 31, 2022. (This version is incomplete and quite confusing, so the 2017 and 2018 versions are preferable, albeit perhaps out-of-date.)
Other things related to adp data:
[[,adp-method,
[[<-,adp-method,
ad2cpCodeToName(),
ad2cpHeaderValue(),
adp-class,
adpAd2cpFileTrim(),
adpConvertRawToNumeric(),
adpEnsembleAverage(),
adpFlagPastBoundary(),
adpRdiFileTrim(),
adp_rdi.000,
adp,
as.adp(),
beamName(),
beamToXyzAdpAD2CP(),
beamToXyzAdp(),
beamToXyzAdv(),
beamToXyz(),
beamUnspreadAdp(),
binmapAdp(),
enuToOtherAdp(),
enuToOther(),
handleFlags,adp-method,
is.ad2cp(),
plot,adp-method,
read.adp.nortek(),
read.adp.rdi(),
read.adp.sontek.serial(),
read.adp.sontek(),
read.adp(),
read.aquadoppHR(),
read.aquadoppProfiler(),
read.aquadopp(),
rotateAboutZ(),
setFlags,adp-method,
subset,adp-method,
subtractBottomVelocity(),
summary,adp-method,
toEnuAdp(),
toEnu(),
velocityStatistics(),
xyzToEnuAdpAD2CP(),
xyzToEnuAdp(),
xyzToEnu()
Other things related to ad2cp data:
ad2cpCodeToName(),
ad2cpHeaderValue(),
adpAd2cpFileTrim(),
is.ad2cp()
Other functions that read adp data:
read.adp.nortek(),
read.adp.rdi(),
read.adp.sontek.serial(),
read.adp.sontek(),
read.adp(),
read.aquadoppHR(),
read.aquadoppProfiler(),
read.aquadopp()
# 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