read.adv {oce} | R Documentation |
Read an ADV data file, producing an object of type adv
.
read.adv(file, from=1, to, by=1, tz=getOption("oceTz"), type=c("nortek", "sontek", "sontek.adr", "sontek.text"), header=TRUE, longitude=NA, latitude=NA, start, deltat, debug=getOption("oceDebug"), monitor=FALSE, processingLog) read.adv.nortek(file, from=1, to, by=1, tz=getOption("oceTz"), header=TRUE, longitude=NA, latitude=NA, type=c("vector", "aquadopp"), haveAnalog1=FALSE, haveAnalog2=FALSE, debug=getOption("oceDebug"), monitor=FALSE, processingLog) read.adv.sontek.serial(file, from=1, to, by=1, tz=getOption("oceTz"), longitude=NA, latitude=NA, start, deltat, debug=getOption("oceDebug"), monitor=FALSE, processingLog) read.adv.sontek.adr(file, from=1, to, by=1, tz=getOption("oceTz"), header=TRUE, longitude=NA, latitude=NA, debug=getOption("oceDebug"), monitor=FALSE, processingLog) read.adv.sontek.text(basefile, from=1, to, by=1, tz=getOption("oceTz"), originalCoordinate="xyz", transformationMatrix, longitude=NA, latitude=NA, debug=getOption("oceDebug"), monitor=FALSE, processingLog)
file |
a connection or a character string giving the name of the file to load. It is also
possible to give |
basefile |
character string naming the base of filenames to load (used only by
|
from |
index number of the first profile to be read, or the time of that profile, as created
with |
haveAnalog1 |
optional argument, only for Nortek devices: indicates whether to extract the “analog1” (8-bit) data. |
haveAnalog2 |
optional argument, only for Nortek devices: indicates whether to extract the “analog2” (16-bit) data. |
to |
indication of the last profile to read, in a format matching that of |
by |
an indication of the stride length to use while walking through the file. This is
ignored if |
header |
a boolean indicating whether the file contains a header at the start. (This will not be the case for files that are created by data loggers that chop the raw data up into a series of sub-files, e.g. once per hour.) |
longitude |
optional signed number indicating the longitude in degrees East. |
latitude |
optional signed number indicating the latitude in degrees North. |
start |
the time of the first sample, typically created with |
deltat |
the time between samples. (This is mandatory if |
originalCoordinate |
character string indicating coordinate system, one of |
transformationMatrix |
transformation matrix to use in converting beam coordinates to xyz
coordinates. This will over-ride the matrix in the file header, if there is one. An example is
|
type |
character string indicating type of file, and used by |
tz |
character string indicating time zone to be assumed in the data. |
debug |
a flag that turns on debugging. The value indicates the depth within the call stack
to which debugging applies. For example, |
monitor |
boolean, set to |
processingLog |
if provided, the action item to be stored in the log. This parameter is typically only provided for internal calls; the default that it provides is better for normal calls by a user. |
Reads a binary-format ADV file. This is straightforward for files with headers, since the headers contain all the information required for further processing.
Files without headers may be created in experiments in which a data logger was set up to monitor the serial data stream from an instrument. The lack of header information places a burden on the user, who must supply such basic information as the times of observations, the instrument orientation, the instrument coordinate system, etc. Example 3 below shows how to deal with such files. Three things should be noted.
The use must choose the appropriate read.adv
variant corresponding to the
instrument in question. (This is necessary because oceMagic
, which is used by the
generic read.oce
routine, cannot determine the type of instrument by examining a
file that lacks a header.)
The call to the read
function must include a start time (start
) and the
number of seconds between data (deltat
), again, because the instrument data stream may
lack those things when the device is set to a serial mode. Also, of course, it is necessary to
set header=FALSE
in the function call.
Once the file has been read in, the user will be obliged to specify other information, for
the object to be well-formed. For example, the read
function will have no way of knowing
the instrument orientation, the coordinate system being used, the transformation matrix to go
from "beam"
to "xyz"
coordinates, or the instrument heading, pitch, and roll, to
go from "xyz"
coordinates to "enu"
coordinates. Such things are illustrated in
example 3 below.
In ADV data files, velocities are coded to signed 2-byte integers, with a
scale factor being used to convert to velocity in metres per second. These
two facts control the maximum recordable velocity and the velocity
resolution, values that may be retrieved for an ADV object name d
with
d[["velocityMaximum"]]
and d[["velocityResolution"]]
.
An object of class
"adv"
, which contains measurements made with an
ADV device. This is a list containing lists named metadata
, data
, and
processingLog
.
The metadata
contains information as given in the following table. The “Nortek name” is
the name used in the Nortek System Integrator Guide [reference 1] and the “Sontek name” is the
name used in the relevant Sontek documentation. References are given in square brackets.
metadata name | Nortek name | Sontek name | Meaning |
manufacturer | - | - | Either "nortek" or "sontek" |
instrumentType | - | - | Either "vector" or "adv" |
filename | - | - | Name of data file(s) |
latitude | - | - | Latitude of mooring (if applicable) |
longitude | - | - | Longitude of mooring (if applicable) |
numberOfSamples | - | - | Number of data samples in file |
numberOfBeams | NBeams [1 p18] | - | Number of beams (always 3) |
numberOfBeamSequencesPerBurst | NPings | - | number of beam sequences per burst |
measurementInterval | MeasInterval [1 p31] | - | |
samplingRate | 512/(AvgInterval) [1 p30; 4] | - | |
The data
list contains items with names corresponding to adp
objects, with an
exception for Nortek data. Nortek instruments report some things at a time interval that is
longer than the velocity sampling, and these are stored in data
as timeSlow
,
headingSlow
, pitchSlow
, rollSlow
, and temperatureSlow
; if burst
sampling was used, there will also be items recordsBurst
and timeBurst
.
The processingLog
is in the standard format.
The data format is inferred from the System Integrator Guide [1]. This document lacks clarity
in spots, and so read.adv.nortek
contains some assumptions that are noted here, so that
users will be aware of possible problems.
A prominent example is the specification of the sampling rate, stored in
metadata$sampingRate
in the return value. Repeated examination of the System Integrator
Guide [1] failed to indicate where this value is stored in the various headers contained in
Vector datasets. After some experimentation with a few data files, read.adv.nortek
was
set up to calculate metadata$samplingRate
as 512/AvgInterval
where
AvgInterval
is a part of the “User Configuration” header [1 p30], where the
explanation is “average interval in seconds”). This formula was developed through trial and
error, but it was confirmed later on the Nortek discussion group, and it should appear in
upcoming versions of [1].
Another basic issue is the determination of whether an instrument had recorded in continuous
mode or burst mode. One might infer that TimCtrlReg
in the “User Configuration” header
[1 p30] determines this, in bits 1 and 2. However, this was the case in test files available to
the author. For this reason, read.adv.nortek
infers the mode by reverse engineering of
data files of known configuration. The present version of read.adv.nortek
determines the
sampling mode from the “NRecords
” item of the “Vector Velocity Data” header, which
seems to be 0 for data collected continuously, and non-zero for data collected in bursts.
Taking these things together, we come upon the issue of how to infer sampling times for Nortek
instruments. There do not seem to be definitive documents on this, and so
read.adv.nortek
is based partly on information (of unknown quality) found on Nortek
discusson boards. The present version of read.adv.nortek
infers the times of velocity
observations differently, depending on whether the instrument was set to record in burst mode or
continuous mode. For burst mode, times stated in the burst headers are used, but for continous
mode, times stated in the “vector system data” are used. On the advice found on a Nortek
discussion board, the burst-mode times are offset by 2 seconds to allow for the instrument
warm-up period.
The binary format is inferred from Appendix 2.2.3 of the Sontek ADV operation Manual [3], with the following exceptions and notes.
The documentation says sampling rate is in units of 0.1Hz, but a test file indicates that it is in 0.01 Hz.
Bursts are recognized by byte sequences [2 p95]. In each case, a signalling byte is to be followed by a certain number of bytes, and so this code checks for two-byte sequences. The are as follows:
c(0x81,0x12)
for an ADV with no optional sensors
installed.
c(0x83,0x18)
if a compass/tilt sensor is installed,
but no temperature or pressure sensors.
c(0x85,0x16)
if temperature and/or pressure sensors
are installed, but no compass/tilt sensor.
c(0x87,0x1c)
if a compass/tilt sensor is installed
in addition to temperature and/or pressure sensors.
Bug: only the second-last of these is handled in the present version of the package.
The by
argument only has an effect on quickly-varying variables, such as the
fast timescale, velocity, backscatter, and amplitude It has no effect on slowly-varying
variables, such as heading, temperature, etc. And, for the Nortek case, it also has no effect on
the burst information. The reason for all of this is that it is not altogether clear what
by
should mean, for those variables. Indeed, this is an argument for deleting
by
from the argument list, and this may be done in a future version of read.adv
.
Dan Kelley
1. Nortek AS. System Integrator Guide (paradopp family of products). June 2008. (Doc No: PSI00-0101-0608). (Users may find it helpful to also examine newer versions of the guide.)
2. SonTek/YSI ADVField/Hydra Acoustic Doppler Velocimeter (Field) Technical Documentation (Sept 1, 2001).
3. Appendix 2.2.3 of the Sontek ADV operation Manual, Firmware Version 4.0 (Oct 1997).
4. Nortek Knowledge Center http://www.nortekusa.com/en/knowledge-center
The documentation for adv-class
explains the structure
of ADV objects, and also outlines the other functions dealing with them.
## Not run: library(oce) # A nortek Vector file d <- read.oce("/data/archive/sleiwex/2008/moorings/m05/adv/nortek_1943/raw/adv_nortek_1943.vec", from=as.POSIXct("2008-06-26 00:00:00", tz="UTC"), to=as.POSIXct("2008-06-26 00:00:10", tz="UTC")) plot(d, which=c(1:3,15)) ## End(Not run)