read.rsk: Read an RBR rsk or Ruskin export file

Description

Read an RBR rsk or txt file, e.g. as produced by an RBR logger, producing an object of class rsk.

Usage

read.rsk(file, from=1, to, by=1, type,
            tz=getOption("oceTz", default="UTC"), patm=FALSE,
            processingLog, debug=getOption("oceDebug"))

Arguments

file

a connection or a character string giving the name of the file to load. Note that file must be a character string, because connections are not used in that case, which is instead handled with database calls.

from

indication of the first datum to read. This can a positive integer to indicate sequence number, the POSIX time of the first datum, or a character string that can be converted to a POSIX time. (For POSIX times, be careful about the tz

to

an indication of the last datum to be read, in the same
    format as from.  If to is missing, data will be read
    to the end of the file.

by

an indication of the stride length to use while walking
    through the file.  If this is an integer, then by-1
    samples are skipped between each pair of samples that is read.  If
    this is a string representing a time interval, in colon

type

optional file type, presently can be rsk or
  txt (for a text export of an RBR rsk or hex file). If
    this argument is not provided, an attempt will be made to infer the type
    from the file name and contents.

tz

time zone. The value oceTz is set at package setup.

patm

controls the handling of atmospheric pressure, an important issue
    for RBR instruments that record absolute pressure; see Details.

processingLog

if provided, the action item to be stored in the log.
    (Typically only provided for internal calls; the default that it provides is
    better for normal calls by a user.)

debug

a flag that can be set to TRUE to turn on debugging.

`Value`

An object of rsk-class.

`Details`

This can read files produced by several RBR instruments.  At the
  moment, five styles are understood: (1) text file produced as an
  export of an RBR hex or rsk file; (2) text file with columns for temperature
  and pressure (with sampling times indicated in the header); (3) text file with
  four columns, in which the date the time of day are given in the first two
  columns, followed by the temperature, and pressure; (4) text file with five
  columns, in which depth in the water column is given after the pressure; (5)
  an SQLite-based database format. The first four options are provided mainly
  for historical reasons, since RBR instruments at the date of writing commonly
  use the SQLite format, though the first option is common for all
  instruments that produce a hex file that can be read using
  Ruskin.
  Options 2-4 are mostly obsolete, and will be removed from future versions.
  A note on conductivity. RBR devices record conductivity in
  mS/cm, and it is this value that is stored in the object returned by
  read.rsk. This can be converted to conductivity ratio (which is
  what many other instruments report) by dividing by 42.914 (see Culkin and
  Smith, 1980) which will be necessary in any seawater-related function that
  takes conductivity ratio as an argument (see Examples).
    
  A note on pressure. RBR devices tend to record absolute pressure (i.e.
  sea pressure plus atmospheric pressure), unlike most oceanographic instruments
  that record sea pressure (or an estimate thereof).  The handling of pressure
  is controlled with the patm argument, for which there are three
  possibilities.  (1) If patm is FALSE (the default), then
  pressure read from the data file is stored in the data slot of return
  value, and the metadata item pressureType is set to the string
  "absolute".  (2) If patm is TRUE, then an estimate of
  atmospheric pressure is subtracted from the raw data. For data files in the
  SQLite format (i.e.  *.rsk files), this estimate will be the value read
  from the file, or the ``standard atmosphere'' value 10.1325 dbar, if the file
  lacks this information.  (3) If patm is a numerical value (or list of
  values, one for each sampling time), then patm is subtracted from the
  raw data.  In cases 2 and 3, an additional column named
  pressureOriginal is added to the data slot to store the value
  contained in the data file, and pressureType is set to a string
  starting with "sea".  See as.ctd for details of how this
  setup facilitates the conversion of rsk-class objects to
  ctd-class objects.

`References`

Culkin, F., and Norman D. Smith, 1980. Determination of the
  concentration of potassium chloride solution having the same
  electrical conductivity, at 15 C and infinite frequency, as standard
  seawater of salinity 35.0000 ppt (Chlorinity 19.37394 ppt). IEEE Journal
  of Oceanic Engineering, 5, pp 22-23.

`See Also`

The documentation for rsk-class explains the structure of
  rsk objects, and also outlines other functions dealing with them.
  Since RBR has a wide variety of instruments, rsk datasets can be quite
  general, and it is common to coerce rsk objects to other forms for
  specialized work, e.g. as.ctd can be used to create CTD object,
  so that the generic plot obeys the CTD format.