processingLog is in standard form and needs little comment. The
rest of this section discusses the metadata and data slots,
and the notation used assumes an object of class adp that is named
``adp.'' The metadata slot contains various items relating to the dataset,
including source file name, sampling rate, velocity resolution, velocity
maximum value, and so on. Some of these are particular to particular
instrument types, and prudent researchers will take a moment to examine the
whole contents of the metdata, either in summary form (with
str(adp[["metadata"]])) or in detail (with
adp[["metadata"]]). Perhaps the most useful general properties are
adp[["bin1Distance"]] (the distance, in metres, from the sensor to
the bottom of the first bin), adp[["cellSize"]] (the cell height, in
metres, in the vertical direction, not along the beam), and
adp[["beamAngle"]] (the angle, in degrees, between beams and an
imaginary centre line that bisects all beam pairs).
The diagram provided below indicates the coordinate-axis and beam-numbering
conventions for three- and four-beam ADP devices, viewed as though the
reader were looking towards the beams being emitted from the tranducers.
adp[["beamAngle"]] equal to 20 degrees, adp[["bin1Distance"]]
equal to 2m, and adp[["cellSize"]] equal to 1m. In the diagram,
the viewer is in the plane containing two beams that are not shown, so the
two visible beams are separated by 40 degrees. Circles indicate the centres
of the range-gated bins within the beams. The lines enclosing those
circles indicate the coverage of beams that spread plus and minus 2.5
degrees from their centreline.
Note that adp[["oceCoordinate"]] stores the present coordinate
system of the object, and it has possible values "beam",
"xyz" or "enu". (This should not be confused with
adp[["originalCoordinate"]], which stores the coordinate system used
in the original data file.)
In contrast to the metadata slot, which holds many items that are
instrument-specific, the data slot enforces a single pattern on all
instrument types. To begin with, adp[["v"]] is a three-dimensional
numeric matrix of velocities in m/s. In this matrix, the first index
indicates time, the second bin number, and the third beam number. The
meanings of the beams depends on whether the object is in beam coordinates,
frame coordinates, or earth coordinates.
Corresponding to the velocity matrix are two matrices of type raw, and
identical dimension, accessed by adp[["a"]] and adp[["q"]],
holding measures of signal strength and data quality quality, respectively.
(The exact meanings of these depend on the particular type of instrument,
and it is assumed that users will be familiar enough with instruments to
know both the meanings and their practical consequences in terms of
data-quality assessment, etc.)
In addition to the matrices, there are time-based vectors. The vector
adp[["time"]] (of length equal to the first index of
adp[["v"]], etc.) holds POSIXt times of observation. Depending on
type of instrument and its configuration, there may also be corresponding
vectors for sound speed (adp[["soundSpeed"]]), pressure
(adp[["pressure"]]), temperature (adp[["temperature"]]),
heading (adp[["heading"]]) pitch (adp[["pitch"]]), and roll
(adp[["roll"]]), depending on the setup of the instrument.
The precise meanings of the data items depend on the instrument
type. All instruments have v (for velocity), q (for a
measure of data quality) and a (for a measure of backscatter
amplitude, also called echo intensity). Devices from Teledyne-RDI
profilers have an additional item g (for percent-good).
For RDI profilers, there are four three-dimensional arrays holding beamwise
data. In these, the first index indicates time, the second bin number, and
the third beam number (or coordinate number, for data in xyz,
enu or other coordiante systems). In the list below, the
quoted phrases are quantities as defined in Figure 9 of reference 1.
vis ``velocity'' in m/s, inferred from two-byte signed
integer values (multiplied by the scale factor that is stored invelocityScalein the metadata).qis ``correlation magnitude'' a one-byte quantity stored
as typerawin the object. The values may range from 0 to 255.ais ``backscatter amplitude``, also known as
``echo intensity'' a one-byte quantity stored as typerawin the object. The values may range from 0 to 255.gis ``percent good'' a one-byte quantity stored asrawin the object. The values may range from 0 to 100.adp[["distance"]] that indicates the bin
distances from the sensor, meaasured in metres along an imaginary centre
line bisecting beam pairs. The length of this vector equals
dim(adp[["v"]])[2].adv, the data are provided
by adp[["v"]], adp[["a"]], and adp[["q"]]. As a
convenience, the last two of these can be accessed as numeric (as
opposed to raw) values by e.g. adp[["a", "numeric"]]. The
vectors are accessed in a similar way, e.g. adp[["heading"]], etc.
Quantities in the metadata slot are also available by name, e.g.
adp[["velocityResolution"]], etc.} adp[["v"]] <- 0.01 +
adp[["v"]].}
show method (e.g.
show(d)) displays information about an ADP object named
d.}
adp devices, owing partly to the flexibility that manufacturers
provide in the setup. Prudent users will undertake many tests before
trusting the details of the data. Are mean currents in the expected
direction, and of the expected magnitude, based on other observations or
physical constraints? Is the phasing of currents as expected? If the
signals are suspect, could an incorrect scale account for it? Could the
transformation matrix be incorrect? Might the data have exceeded the
maximum value, and then ``wrapped around'' to smaller values? Time spent
on building confidence in data quality is seldom time wasted.read.oce will usually read the data. If not, one may use the
general ADP function read.adp or specialized variants
read.adp.rdi, read.adp.nortek or
read.adp.sontek or
read.adp.sontek.serial. ADP data may be plotted with plot.adp function, which is a
generic function so it may be called simply as plot.
Statistical summaries of ADP data are provided by the generic function
summary, while briefer overviews are provided with show.
Conversion from beam to xyz coordinates may be done with
beamToXyzAdp, and from xyz to enu (east north up) may be done
with xyzToEnuAdp. toEnuAdp may be used to
transfer either beam or xyz to enu. Enu may be converted to other
coordinates (e.g. aligned with a coastline) with
enuToOtherAdp.