% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/adp.nortek.ad2cp.R
\name{read.adp.ad2cp}
\alias{read.adp.ad2cp}
\title{Read an adp File in Nortek AD2CP Format}
\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,
  ...
)
}
\arguments{
\item{file}{a connection or a character string giving the name of the file to
load.}

\item{from}{an integer indicating the index number of the first record to
read. This must equal 1, for this version of \code{read.adp.ad2cp}.  (If not
provided, \code{from} defaults to 1.)}

\item{to}{an integer indicating the final record to read. If \code{to} is 0L,
which is the default, then the value is changed internally to 1e9, and
reading stops at the end of the file.}

\item{by}{ignored.}

\item{dataType}{an indication of the data type to be extracted.  If this is
NULL (the default) then \code{read.adp.ad2cp()} returns a data frame indicating
the data type occurrence rate in the file.  Otherwise, \code{dataType} must be
either a numeric or character value (see \dQuote{Details}).  In the numeric
case, which includes both base-10 numbers and \code{raw} values, \code{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 \dQuote{Details} section.  In the character
case, it must be a string taken from that same table.}

\item{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
\code{"^GETCLOCKSTR,TIME="}.}

\item{tz}{a character value indicating time zone. This is used in
interpreting times stored in the file.}

\item{longitude, latitude}{numerical values indicating the observation
location.}

\item{plan}{optional integer specifying which 'plan' to focus on (see}

\item{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
\code{filename}, and an \linkS4class{adp} object is returned. However, if \code{TOC} is TRUE,
then a dataframe detailing the number of entries in each of the datasets
stored within the file is returned.}

\item{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.}

\item{orientation, distance, monitor, despike}{ignored, provided only for
calling compatibility with other functions that read \linkS4class{adp} files.  A
warning is issued if any of these is supplied in a call to
\code{read.adp.ad2cp()}.}

\item{\dots}{ignored parameters that might be passed to \code{read.adp.ad2cp()} by
\code{\link[=read.oce]{read.oce()}}.}
}
\value{
\code{read.adp.ad2cp()} returns either an \linkS4class{adp} object or the number
of data sets within the file, according to the value of \code{TOC}.
}
\description{
This function is under active development and may change without notice.  In
contrast with other \code{oce} reading functions, \code{\link[=read.adp.ad2cp]{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 \dQuote{Details} for more on the reasons for these departures from the
usual \code{oce} pattern.
}
\details{
Why does \code{\link[=read.adp.ad2cp]{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 \code{oce} system of pairing a \code{metadata}
slot with a \code{data} slot.  For example, in a conventional ADP dataset, the
\code{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 \code{data} slot, and \code{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 \code{oce} object, with ripple effects for plotting
and data access.  Those ripple effects would extend beyond \code{oce} itself to
user code.  To avoid such problems, \code{\link[=read.adp.ad2cp]{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 \code{dataType} are shown in the table below; the
\code{dataType} argument of \code{\link[=read.adp.ad2cp]{read.adp.ad2cp()}} may be given as listed in any of
the first 3 columns of this table.\tabular{rrrr}{
   code (raw) \tab code (integer) \tab oce name \tab notes \cr
   ---------- \tab -------------- \tab ------------------- \tab ------ \cr
   \code{0x15} \tab 21 \tab \code{burst} \tab - \cr
   \code{0x16} \tab 22 \tab \code{average} \tab - \cr
   \code{0x17} \tab 23 \tab \code{bottomTrack} \tab 1 \cr
   \code{0x18} \tab 24 \tab \code{interleavedBurst} \tab - \cr
   \code{0x1a} \tab 26 \tab \code{burstAltimeterRaw} \tab 2 \cr
   \code{0x1b} \tab 27 \tab \code{DVLBottomTrack} \tab - \cr
   \code{0x1c} \tab 28 \tab \code{echosounder} \tab - \cr
   \code{0x1d} \tab 29 \tab \code{DVLWaterTrack} \tab - \cr
   \code{0x1e} \tab 30 \tab \code{altimeter} \tab - \cr
   \code{0x1f} \tab 31 \tab \code{averageAltimeterRaw} \tab 3 \cr
   \code{0x23} \tab 35 \tab \code{echosounderRaw} \tab - \cr
   \code{0x24} \tab 36 \tab \code{echosounderRawTx} \tab 4 \cr
   \code{0x30} \tab 48 \tab \code{waves} \tab 5 \cr
   \code{0xa0} \tab 160 \tab \code{text} \tab 6 \cr
}


Note 1. Tentative support for reading \code{dataType=bottomTrack} was added in
April of 2026. The problem with this \code{dataType} is that the most recent
Nortek manuals (e.g. Reference 3) do not provide any documentation, and there
are contradictions between an older manual (Reference 4) and information
provided in a Nortek email to Dan Kelley and Clark Richards, dated 2026-03-24
(Reference 5). The known problems include the following (see
\verb{https://github.com/dankelley/oce/issues/2368} for discussion),  (1) The
\code{ensembleCounter} field is certainly incorrect, as it cycles from 1 to 60 in
test files, instead of increasing monotonically. (2) The byte that is
supposed to hold both the coordinate system and the number of beams seems not
to be configured identically across the handful of test files used during oce
development. As a remedy, the function tries to detect faulty values, and
switches to using the header record if so (issuing a warning so the user will
know that assumptions have been made).

Note 2. In reading a file with \code{burstAltimeterRaw} data components, a potential problem
was noticed with that the part of the file that indicates the number of
altimeter samples (called \code{NSAMP} in the Nortek documentation). The stated
value was 2 times the value held in the header (text) portion of the file,
and reading the larger value created a matrix that had
the upper half filled with odd striping patterns. Therefore, the function
checks the two indications of length, and uses the value in the text block if
they disagree.  (See https://github.com/dankelley/oce/issues/2326.)

Note 3. In April 2026, the name \code{averageAltimeter} (hex code 0x14) was changed to
\code{averageAltimeterRaw}, to be more consistent with names used in Reference 3.
The old name will still work, but a warning will be issued indicating that the
name was automatically replaced with the new name.

Note 4: Code 0x24 (\code{echosounderRawTx}) has some coding done, but it is
untested, as the developers lack a data file exemplar. For now, this data
type is read as though it were 0x23, which is likely to produce poor results
or cause errors in processing.

Note 5: Code 0x30 (\code{waves}) is recognized but not handled yet.

Note 6: Code 0xa0 (\code{text}) holds a text string that defines the settings used
in creating the file.  This can be quite helpful in debugging and analysis.
}
\section{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.
\enumerate{
\item In R, \code{\link[=readBin]{readBin()}} is used to insert the file contents into
a \link{vector} of type \code{raw}.
\item 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 \link{vector} of
type \code{integer}.
\item In R, \code{\link[=readBin]{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 \code{\link[=readBin]{readBin()}}. This process is done for each of the data
fields that are to be handled.  Importantly, these \code{\link[=readBin]{readBin()}}
calls are tailored to the data, using values of
the \code{size}, \code{endian} and \code{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.
\item Finally, in R, the acquired items are inserted into the \code{data} or
\code{metadata} slot of the return value, according to oce convention.
}
}

\section{Problems}{

\enumerate{
\item It is unclear from the manufacturer's manuals whether
\code{NSAMP} is a 2-byte value (as stated in old manuals) or a 4-byte value (as
in a manual available in or around June 2025). The present function assumes a 4-byte
value, which works with a test file available to the authors.
The manufacturer has been asked for clarity on this; see
https://github.com/dankelley/oce/issues/2326.
}
}

\examples{
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)
    print(read.oce(file, TOC = TRUE))
    d <- read.oce(file, dataType = "burstAltimeterRaw")
    imagep(d[["time"]], d[["altimeterRawDistance"]], d[["altimeterRawSamples"]])
}

}
\references{
\enumerate{
\item Nortek AS. “Integrator's Guide: Signature.” Nortek AS, April 30, 2025.
\code{https://support.nortekgroup.com/hc/en-us/article_attachments/19830760385436}
(this link failed in a test on 2025-07-30).
\item Nortek AS. \dQuote{Signature Integration 55|250|500|1000kHz (2024.1),}
2024. (This was once at
\code{https://support.nortekgroup.com/hc/en-us/articles/360029513952-Integrators-Guide-Signature}
but a test on 2025-05-26 revealed that this link no longer worked.)
\item Nortek AS. \dQuote{Integrator's Guide Signature.} March 5, 2026.
\url{https://support.nortekgroup.com/hc/en-us/article_attachments/25920785046428}.
\item Nortek AS. \dQuote{Signature Integration 55|250|500|1000kHz (2017).}
February 10, 2017.
\url{https://assets.nortekgroup.com/software/N3015-007-Integrators-Guide-AD2CP_1018.pdf}.
\item \url{https://github.com/dankelley/oce/issues/2368}
}
}
\seealso{
Other things related to adp data: 
\code{\link{[[,adp-method}},
\code{\link{[[<-,adp-method}},
\code{\link{ad2cpCodeToName}()},
\code{\link{ad2cpHeaderValue}()},
\code{\link{adp}},
\code{\link{adp-class}},
\code{\link{adpAd2cpFileTrim}()},
\code{\link{adpConvertRawToNumeric}()},
\code{\link{adpEnsembleAverage}()},
\code{\link{adpFlagPastBoundary}()},
\code{\link{adpRdiFileTrim}()},
\code{\link{adp_rdi.000}},
\code{\link{applyMagneticDeclination,adp-method}},
\code{\link{as.adp}()},
\code{\link{beamName}()},
\code{\link{beamToXyz}()},
\code{\link{beamToXyzAdp}()},
\code{\link{beamToXyzAdpAD2CP}()},
\code{\link{beamToXyzAdv}()},
\code{\link{beamUnspreadAdp}()},
\code{\link{binmapAdp}()},
\code{\link{enuToOther}()},
\code{\link{enuToOtherAdp}()},
\code{\link{handleFlags,adp-method}},
\code{\link{is.ad2cp}()},
\code{\link{plot,adp-method}},
\code{\link{read.adp}()},
\code{\link{read.adp.nortek}()},
\code{\link{read.adp.rdi}()},
\code{\link{read.adp.sontek}()},
\code{\link{read.adp.sontek.serial}()},
\code{\link{read.aquadopp}()},
\code{\link{read.aquadoppHR}()},
\code{\link{read.aquadoppProfiler}()},
\code{\link{rotateAboutZ}()},
\code{\link{setFlags,adp-method}},
\code{\link{subset,adp-method}},
\code{\link{subtractBottomVelocity}()},
\code{\link{summary,adp-method}},
\code{\link{toEnu}()},
\code{\link{toEnuAdp}()},
\code{\link{velocityStatistics}()},
\code{\link{xyzToEnu}()},
\code{\link{xyzToEnuAdp}()},
\code{\link{xyzToEnuAdpAD2CP}()}

Other things related to ad2cp data: 
\code{\link{ad2cpCodeToName}()},
\code{\link{ad2cpHeaderValue}()},
\code{\link{adpAd2cpFileTrim}()},
\code{\link{is.ad2cp}()}

Other functions that read adp data: 
\code{\link{read.adp}()},
\code{\link{read.adp.nortek}()},
\code{\link{read.adp.rdi}()},
\code{\link{read.adp.sontek}()},
\code{\link{read.adp.sontek.serial}()},
\code{\link{read.aquadopp}()},
\code{\link{read.aquadoppHR}()},
\code{\link{read.aquadoppProfiler}()}
}
\author{
Dan Kelley and Clark Richards
}
\concept{functions that read adp data}
\concept{things related to ad2cp data}
\concept{things related to adp data}
