% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ctd.sbe.R
\name{read.ctd.sbe}
\alias{read.ctd.sbe}
\title{Read a ctd File in Seabird Format}
\usage{
read.ctd.sbe(
  file,
  columns = NULL,
  station = NULL,
  missingValue,
  deploymentType = "unknown",
  btl = FALSE,
  monitor = FALSE,
  encoding = "latin1",
  rename = TRUE,
  requireSalinity = TRUE,
  debug = getOption("oceDebug"),
  processingLog,
  ...
)
}
\arguments{
\item{file}{either a connection or a character value naming a file.
For \code{\link[=read.ctd.sbe]{read.ctd.sbe()}} and \code{\link[=read.ctd.woce]{read.ctd.woce()}}, this may be a
wildcard (e.g. \code{"*.cnv"} or \code{"*.csv"}) in which case the return
value is a vector containing CTD objects created by reading the files from
\code{\link[=list.files]{list.files()}} with \code{pattern} set to the specified wildcard
pattern.}

\item{columns}{an optional \link{list} that can be used to convert unrecognized
data names to resultant variable names.  This is used only by
\code{\link[=read.ctd.sbe]{read.ctd.sbe()}} and \code{\link[=read.ctd.odf]{read.ctd.odf()}}. For example,
if a data file named salinity as \code{"SAL"}, then using

\if{html}{\out{<div class="sourceCode">}}\preformatted{d <- read.ctd(f, columns=list(
    salinity=list(name="SAL",
                  unit=list(unit=expression(),
                  scale="PSS-78"))))
}\if{html}{\out{</div>}}

would assign the \code{"SAL"} column to the \code{salinity} entry in the data
slot of the CTD object returned by the \verb{read.*} function.}

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

\item{missingValue}{optional missing-value flag; data matching this value will
be set to \code{NA} upon reading. If this is provided, then it overrules any
missing-value flag found in the data. For Seabird (\code{.cnv}) files, there is
usually no need to set \code{missingValue}, because it can be inferred from the
header (typically as -9.990e-29). Set \code{missingValue=NULL} to turn off
missing-value detection, even in \code{.cnv} files that contain missing-value
codes in their headers. If \code{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.}

\item{deploymentType}{character string indicating the type of deployment. Use
\code{"unknown"} if this is not known, \code{"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; \code{"moored"} if
the device is installed on a fixed mooring, \code{"thermosalinograph"} (or
\code{"tsg"}) if the device is mounted on a moving vessel, to record
near-surface properties, or \code{"towyo"} if the device is repeatedly
lowered and raised.}

\item{btl}{a logical value, with \code{TRUE} indicating that this is a \code{.BTL} file
and \code{FALSE} (the default) indicating a \code{.CNV} file.  Note that if \code{btl} is
\code{TRUE}, the data column names are taken directly from the file (without e.g.
translating to \code{"Sal00"} to \code{"salinity"}.  Also, the "avg" and "sdev" columns
are blended together, with all the latter named as in the file, but with
\code{"_sdev"} appended.}

\item{monitor}{boolean, set to \code{TRUE} to provide an indication of
progress.  This is useful if \code{filename} is a wildcard.}

\item{encoding}{a character value that indicates the encoding to be used for
this data file, if it is textual.  The default value for most functions is
\code{"latin1"}, which seems to be suitable for files containing text written in
English and French.}

\item{rename}{optional logical value indicating whether to rename variables
from the values in the file to the oce convention, using \code{\link[=cnvName2oceName]{cnvName2oceName()}}
for the translation. This is done by default, but setting \code{rename=FALSE} can
be helpful if there is a wish to control the renaming, either using a
built-in dictionary or using a dictionary set up by the user.  See Examples 1
and 2, the latter dealing with the case of using \code{\link[=oceRename]{oceRename()}} to rename
the variables after the file has been read.}

\item{requireSalinity}{logical value indicating what to do if the dataset
lacks both salinity and conductivity. If \code{requireSalinity} is TRUE (the
default) then an error results in this situation; otherwise, a warning is
issued.}

\item{debug}{an integer specifying whether debugging information is
to be printed during the processing. This is a general parameter that
is used by many \code{oce} functions. Generally, setting \code{debug=0}
turns off the printing, while higher values suggest that more information
be printed.}

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

\item{...}{additional arguments, passed to called routines.}
}
\value{
This function returns a \linkS4class{ctd} object.
}
\description{
Read a ctd File in Seabird Format
}
\details{
This function reads files stored in Seabird \code{.cnv} format. Note that these
files can contain multiple sensors for a given field. For example, the file
might contain a column named \code{t090C} for one temperature sensor and \code{t190C}
for a second. The first will be denoted \code{temperature} in the \code{data} slot of
the return value, and the second will be denoted \code{temperature1}. This means
that the first sensor will be used in any future processing that accesses
\code{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. \code{x[["temperature1"]]}, where \code{x} is the name of the returned value.  For
the details of the mapping from \code{.cnv} names to \code{ctd} names, see
\code{\link[=cnvName2oceName]{cnvName2oceName()}}.

The names of the elements in the \code{data} slot of the returned value depend on
the file type, as signalled by the \code{btl} argument.  For the default case of \code{.cnv} files,
the original data names as stored in \code{file} are stored within the \code{metadata}
slot as \code{dataNamesOriginal}, and are displayed with \code{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 \code{.btl} files, the column names are as described
in the documentation entry for the \code{btl} argument.
}
\section{A note on freshwater files}{


As of version 1.8-4 of the package, \code{read.ctd.sbe()} can handle
files that lack both salinity data and conductivity data. The existence of
such files is possible for sampling done in lakes. In prior versions,
the function reported an error, but as of 1.8-4, it reports only
a warning. The recommended practice in such a case is to do e.g.

\if{html}{\out{<div class="sourceCode">}}\preformatted{d <- read.ctd.sbe("file.cnv")
d <- ctdAddData(d, "salinity", rep(0.0, length(d[["pressure"]]))
}\if{html}{\out{</div>}}

to add a salinity column. That will permit e.g. density calculations,
although the accuracy of such calculations is questionable, since the
equations of state are meant to apply to salt water.
}

\section{A note on hand-entered headers}{


CNV files may have a section that contains human-entered information. This is
detected by \code{read.ctd.sbe()} as lines that begin with two asterisks. Decoding
this information can be tricky, because humans have many ways of writing
things.

For example, consider the \code{date} item in the \code{metadata} slot of the returned
value.  \code{read.ctd.sbe()} infers this value in one of two ways.  First, if
there is a header line staring with

\if{html}{\out{<div class="sourceCode">}}\preformatted{* NMEA UTC (Time) =
}\if{html}{\out{</div>}}

then that value is decoded and used for \code{date}.  This header line, preceded
by a single asterisk, is not human-entered, and so there is reason to hope
for a uniform format that can be handled by \code{read.ctd.sbe()}.  However, if
there is no NMEA header line, then \code{read.ctd.sbe()} will look for a line
starting with

\if{html}{\out{<div class="sourceCode">}}\preformatted{** Date:
}\if{html}{\out{</div>}}

which was human-entered. This is the second choice, because humans write
dates in a bewildering variety of ways, and \code{\link[=as.POSIXct]{as.POSIXct()}}, which
\code{read.ctd.sbe} uses to parse the date, cannot handle them all. If there is a
problem, \code{read.ctd.sbe()} issues a warning and stores NA in \code{date}.

A similar error-detection procedure is used for human-entered location data,
which appear in lines starting with either

\if{html}{\out{<div class="sourceCode">}}\preformatted{** Longitude:
}\if{html}{\out{</div>}}

or

\if{html}{\out{<div class="sourceCode">}}\preformatted{** Latitude:
}\if{html}{\out{</div>}}

which often take forms that \code{read.ctd.sbe()} cannot parse.

It is important to note that, even if no warnings are issued, there is a
reasonably high chance that human-entered data will be scanned incorrectly.
(Did the operator remember to indicate the hemisphere? Does 123.456 indicate
decimal degrees, or 123 degrees plus 45.6 minutes? Is hemisphere indicated by
sign or by letter, and, if the latter, where does it appear?)

In deep-sea work, a ship might steam for 6 hours between CTD stations, so the
ship-time cost of each CTD file can be several thousand dollars.  Surely it
is not unreasonable for an analyst to take a minute to glance at the CNV
file, to ascertain whether \code{read.ctd.sbe()} inferred correct values.

\code{\link[=oceSetMetadata]{oceSetMetadata()}} is helpful for correcting problems with individual files,
but if many files are systematically problematic, say for a whole cruise or
perhaps even for a whole institution, then it might sense to set up a wrapper
function to correct deficiencies in the CNV files. As an example, the
following handles dates specified in a particular nonstandard way.

\if{html}{\out{<div class="sourceCode">}}\preformatted{read.ctd.sbe.wrapper <- function(cnv)
\{
    lines <- readLines(cnv)
    # Change month-day-year to year-month-day, so as.POSIXct() can parse it.
    lines <- gsub("^\\\\*\\\\* Date: (.*)-(.*)-(.*)", "** Date: \\\\3-\\\\1-\\\\2", lines)
    read.ctd.sbe(textConnection(lines))
\}
}\if{html}{\out{</div>}}
}

\section{A note on sampling times}{


Until November of 2018, there was a possibility for great confusion in the
storage of the time entries within the \code{data} slot, because \code{read.ctd.sbe}
renamed each of the ten variants of time (see reference 2 for a list) as
\code{"time"} in the \code{data} slot of the returned value.  For CTD profiles, this
was perhaps not a great problem, but it could lead to significant confusion
for moored data. Therefore, a change to \code{read.ctd.sbe} was made, so that it
would Seabird times, using the \code{start_time} entry in the CNV file header
(which is stored as \code{startTime} in the object \code{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):

\tabular{rl}{
\strong{Item} \tab \strong{Meaning}\cr
\code{timeS}   \tab seconds elapsed since \code{start_time}\cr
\code{timeM}   \tab minutes elapsed since \code{start_time}\cr
\code{timeH}   \tab hours elapsed since \code{start_time}\cr
\code{timeJ}   \tab Julian days since the start of the year of the first observation\cr
\code{timeN}   \tab NMEA-based time, in seconds past Jan 1, 1970\cr
\code{timeQ}   \tab NMEA-based time, in seconds past Jan 1, 2000\cr
\code{timeK}   \tab NMEA-based time, in seconds past Jan 1, 2000\cr
\code{timeJV2} \tab as \code{timeJ}\cr
\code{timeSCP} \tab as \code{timeJ}\cr
\code{timeY}   \tab computer time, in seconds past Jan 1, 1970\cr
}
NOTE: not all of these times have been tested properly, and so users
are asked to report incorrect times, so that \code{read.ctd.sbe} can
be improved.
}

\section{A note on scales}{


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 \code{A} is a CTD object, then
\code{A[["temperatureUnit"]]$scale} is a character string that will indicate the scale.
Modern-day data will have \code{"ITS-90"} for that scale, and old data may have
\code{"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 \code{"IPTS-68"} scale to the newer scale, using
\code{\link[=T90fromT68]{T90fromT68()}} before doing calculations that are expressed in
terms of the \code{"ITS-90"} scale. This is taken care of by retrieving temperatures
with the accessor function, e.g. writing \code{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.
}

\examples{
# Example 1: default variable renaming
f <- system.file("extdata", "ctd.cnv.gz", package = "oce")
d1 <- read.ctd(f)

# Example 2: handle variable renaming after reading
d2 <- read.ctd(f, rename = FALSE) |> oceRename("sbe")

}
\references{
\enumerate{
\item The Sea-Bird SBE 19plus profiler is described at
\verb{http://www.seabird.com/products/spec_sheets/19plusdata.htm}.  Some more
information is given in the Sea-Bird data-processing manual
(next item).
\item A SBE data processing manual was once at
\verb{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
\code{SBEDataProcessing_7.26.4.pdf} and had release date 12/08/2017,
and this was the reference version used in coding \code{oce}.
}
}
\seealso{
Other things related to ctd data: 
\code{\link{CTD_BCD2014666_008_1_DN.ODF.gz}},
\code{\link{[[,ctd-method}},
\code{\link{[[<-,ctd-method}},
\code{\link{argo2ctd}()},
\code{\link{as.ctd}()},
\code{\link{cnvName2oceName}()},
\code{\link{ctd}},
\code{\link{ctd-class}},
\code{\link{ctd.cnv.gz}},
\code{\link{ctdDecimate}()},
\code{\link{ctdFindProfiles}()},
\code{\link{ctdFindProfilesRBR}()},
\code{\link{ctdRaw}},
\code{\link{ctdRepair}()},
\code{\link{ctdTrim}()},
\code{\link{ctd_aml_type1.csv.gz}},
\code{\link{ctd_aml_type3.csv.gz}},
\code{\link{d200321-001.ctd.gz}},
\code{\link{d201211_0011.cnv.gz}},
\code{\link{handleFlags,ctd-method}},
\code{\link{initialize,ctd-method}},
\code{\link{initializeFlagScheme,ctd-method}},
\code{\link{oceNames2whpNames}()},
\code{\link{oceUnits2whpUnits}()},
\code{\link{plot,ctd-method}},
\code{\link{plotProfile}()},
\code{\link{plotScan}()},
\code{\link{plotTS}()},
\code{\link{read.ctd}()},
\code{\link{read.ctd.aml}()},
\code{\link{read.ctd.itp}()},
\code{\link{read.ctd.odf}()},
\code{\link{read.ctd.odv}()},
\code{\link{read.ctd.saiv}()},
\code{\link{read.ctd.ssda}()},
\code{\link{read.ctd.woce}()},
\code{\link{read.ctd.woce.other}()},
\code{\link{setFlags,ctd-method}},
\code{\link{subset,ctd-method}},
\code{\link{summary,ctd-method}},
\code{\link{woceNames2oceNames}()},
\code{\link{woceUnit2oceUnit}()},
\code{\link{write.ctd}()}

Other functions that read ctd data: 
\code{\link{read.ctd}()},
\code{\link{read.ctd.aml}()},
\code{\link{read.ctd.itp}()},
\code{\link{read.ctd.odf}()},
\code{\link{read.ctd.saiv}()},
\code{\link{read.ctd.ssda}()},
\code{\link{read.ctd.woce}()},
\code{\link{read.ctd.woce.other}()}
}
\author{
Dan Kelley and Clark Richards, along with William Kumler.
}
\concept{functions that read ctd data}
\concept{things related to ctd data}
