Read a Seabird CTD File
read.ctd.sbe(
file,
columns = NULL,
station = NULL,
missingValue,
deploymentType = "unknown",
btl = FALSE,
monitor = FALSE,
debug = getOption("oceDebug"),
processingLog,
...
)a connection or a character string giving the name of the file to
load. For read.ctd.sbe() and read.ctd.woce(), this may be a
wildcard (e.g. "*.cnv" or "*.csv") in which case the return
value is a vector containing CTD objects created by reading the files from
list.files() with pattern set to the specified wildcard
pattern.
an optional list that can be used to convert unrecognized
data names to resultant variable names. This is used only by
read.ctd.sbe() and read.ctd.odf(). For example,
if a data file named salinity as "SAL", then using
d <- read.ctd(f, columns=list(
salinity=list(name="SAL",
unit=list(unit=expression(),
scale="PSS-78"))))
would assign the "SAL" column to the salinity entry in the data
slot of the CTD object returned by the read.* function.
optional character string containing an identifying name or number for the station. This can be useful if the routine cannot determine the name automatically, or if another name is preferred.
optional missing-value flag; data matching this value will
be set to NA upon reading. If this is provided, then it overrules any
missing-value flag found in the data. For Seabird (.cnv) files, there is
usually no need to set missingValue, because it can be inferred from the
header (typically as -9.990e-29). Set missingValue=NULL to turn off
missing-value detection, even in .cnv files that contain missing-value
codes in their headers. If missingValue is not specified,
then an attempt is made to infer such a value from the data, by testing
whether salinity and/or temperature has a minimum that is under -8 in value;
this should catch common values in files, without false positives. A warning
will be issued in this case, and a note inserted in the processing log of
the return value.
character string indicating the type of deployment. Use
"unknown" if this is not known, "profile" for a profile (in
which the data were acquired during a downcast, while the device was lowered
into the water column, perhaps also including an upcast; "moored" if
the device is installed on a fixed mooring, "thermosalinograph" (or
"tsg") if the device is mounted on a moving vessel, to record
near-surface properties, or "towyo" if the device is repeatedly
lowered and raised.
a logical value, with TRUE indicating that this is a .BTL file and FALSE
(the default) indicating a .CNV file. Note that if btl is TRUE, the data column
names are taken directly from the file (without e.g. translating to "Sal00"
to "salinity". Also, the "avg" and "sdev" columns are blended together, with
all the latter named as in the file, but with "_sdev" appended.
boolean, set to TRUE to provide an indication of
progress. This is useful if filename is a wildcard.
an integer specifying whether debugging information is
to be printed during the processing. This is a general parameter that
is used by many oce functions. Generally, setting debug=0
turns off the printing, while higher values suggest that more information
be printed.
if provided, the action item to be stored in the log. This is typically only provided for internal calls; the default that it provides is better for normal calls by a user.
additional arguments, passed to called routines.
a '>ctd object. The details of the contents
depend on the source file. The metadata slot is particularly
variable across data formats, because the meta-information provided
in those formats varies so widely.
Until November of 2018,
there was a possibility for great confusion in the storage
of the time entries within the data slot, because read.ctd.sbe
renamed each of the ten variants of time (see reference 2 for a list)
as "time" in the data slot of the returned value.
For CTD profiles, this was perhaps not a great problem, but it could
lead to great confusion for moored data. Therefore, a change to read.ctd.sbe was
made, so that it would Seabird times, using the start_time entry in
the CNV file header (which is stored as startTime in the object
metadata slot), along with specific time columns as follows
(and as documented, with uneven clarity, in the
SBE Seasoft data processing manual, revision 7.26.8, Appendix VI):
| Item | Meaning |
timeS |
seconds elapsed since start_time |
timeM |
minutes elapsed since start_time |
timeH |
hours elapsed since start_time |
timeJ |
Julian days since the start of the year of the first observation |
timeN |
NMEA-based time, in seconds past Jan 1, 1970 |
timeQ |
NMEA-based time, in seconds past Jan 1, 2000 |
timeK |
NMEA-based time, in seconds past Jan 1, 2000 |
timeJV2 |
as timeJ |
timeSCP |
as timeJ |
timeY |
computer time, in seconds past Jan 1, 1970 |
NOTE: not all of these times have been tested properly, and so users
are asked to report incorrect times, so that read.ctd.sbe can
be improved.
The user might encounter data files with a variety of scales for temperature and
salinity. Oce keeps track of these scales in the units it sets up for the stored
variables. For example, if A is a CTD object, then
A[["temperatureUnit"]]$scale is a character string that will indicate the scale.
Modern-day data will have "ITS-90" for that scale, and old data may have
"IPTS-68". The point of saving the scale in this way is so that the various
formulas that deal with water properties can account for the scale, e.g. converting
from numerical values saved on the "IPTS-68" scale to the newer scale, using
T90fromT68() before doing calculations that are expressed in
terms of the "ITS-90" scale. This is taken care of by retrieving temperatures
with the accessor function, e.g. writing A[["temperature"]] will either
retrieve the stored values (if the scale is ITS-90) or converted values (if
the scale is IPTS-68). Even though this procedure should work, users who
really care about the details of their data are well-advised to do a couple
of tests after examining the first data line of their data file in an editor.
Note that reading a file that contains IPTS-68 temperatures produces a warning.
This function reads files stored in Seabird .cnv format.
Note that these files can contain multiple sensors for a given field. For example,
the file might contain a column named t090C for one
temperature sensor and t190C for a second. The first will be denoted
temperature in the data slot of the return value, and the second
will be denoted temperature1. This means that the first sensor
will be used in any future processing that accesses temperature. This
is for convenience of processing, and it does not pose a limitation, because the
data from the second sensor are also available as e.g. x[["temperature1"]],
where x is the name of the returned value. For the details of the
mapping from .cnv names to ctd names, see cnvName2oceName().
The names of the elements in the data slot of the returned value depend on
the file type, as signalled by the btl argument. For the default case of .cnv files,
the original data names as stored in file are stored within the metadata
slot as dataNamesOriginal, and are displayed with summary alongside the
numerical summary; see the Appendix VI of reference 2 for the meanings of these
names (in the "Short Name" column of the table spanning pages 161 through 172).
However, for the case of .btl files, the column names are as described
in the documentation entry for the btl argument.
The Sea-Bird SBE 19plus profiler is described at
http://www.seabird.com/products/spec_sheets/19plusdata.htm. Some more
information is given in the Sea-Bird data-processing manual
(next item).
A SBE data processing manual was once at
http://www.seabird.com/document/sbe-data-processing-manual,
but as of summer 2018, this no longer seems to be provided by SeaBird.
A web search will turn up copies of the manual that have been put
online by various research groups and data-archiving agencies.
As of 2018-07-05, the latest version was named
SBEDataProcessing_7.26.4.pdf and had release date 12/08/2017,
and this was the reference version used in coding oce.
Other things related to ctd data:
CTD_BCD2014666_008_1_DN.ODF.gz,
[[,ctd-method,
[[<-,ctd-method,
as.ctd(),
cnvName2oceName(),
ctd-class,
ctd.cnv,
ctdDecimate(),
ctdFindProfiles(),
ctdRaw,
ctdTrim(),
ctd,
d200321-001.ctd,
d201211_0011.cnv,
handleFlags,ctd-method,
initialize,ctd-method,
initializeFlagScheme,ctd-method,
oceNames2whpNames(),
oceUnits2whpUnits(),
plot,ctd-method,
plotProfile(),
plotScan(),
plotTS(),
read.ctd.itp(),
read.ctd.odf(),
read.ctd.odv(),
read.ctd.woce.other(),
read.ctd.woce(),
read.ctd(),
setFlags,ctd-method,
subset,ctd-method,
summary,ctd-method,
woceNames2oceNames(),
woceUnit2oceUnit(),
write.ctd()
Other functions that read ctd data:
read.ctd.itp(),
read.ctd.odf(),
read.ctd.woce.other(),
read.ctd.woce(),
read.ctd()
# NOT RUN {
f <- system.file("extdata", "ctd.cnv", package="oce")
## Read the file in the normal way
d <- read.ctd(f)
## Read an imaginary file, in which salinity is named 'salt'
d <- read.ctd(f, columns=list(
salinity=list(name="salt", unit=list(unit=expression(), scale="PSS-78"))))
# }
Run the code above in your browser using DataLab