document new time scheme in read.ctd.sbe()

R/ctd.sbe.R

@@ -628,8 +628,29 @@ cnvName2oceName <- function(h, columns=NULL, debug=getOption("oceDebug"))
 #' numerical summary. See the Appendix VI of [2] for the meanings of these
 #' names (in the "Short Name" column of the table spanning pages 161 through 172).
 #'
+#' @section A note on sampling times:
+#' SBE files can be somewhat confusing as regards the time of measurement. If
+#' the data file contains metadata item called \code{start_time}, then
+#' it is converted to a POSIX time object by \code{read.ctd.sbe} and stored
+#' within the \code{metadata} slot as \code{"startTime"}. Until 2018-07-05, that
+#' value was also stored in a \code{metadata} item named \code{"time"}, but this
+#' caused confusion for data files that also have an elapsed-time column, and so
+#' \code{metadata@time} is no longer stored, if an elapsed-time column exists
+#' in the data file. There is also a possibility for confusion in the storage
+#' of the elapsed-time entry within the \code{data} slot, because \code{read.ctd.sbe}
+#' renames all of the ten variants of elapsed time (see [2] for a list)
+#' as, simply, \code{"time"} in the \code{data} slot of the returned value.
+#' (Numerical suffices will be used if the file contains multiple elapsed-time
+#' columns.) This imposes upon the user the burden of using \code{summary()} on
+#' the return value, to discover the original name of the elapsed time column,
+#' because \code{read.ctd.sbe} does not convert the 10 possible units to
+#' a standard, but rather simply records the numerical values that are in
+#' the data file. The most common column name is likely \code{timeS}, for
+#' elapsed time in seconds; see [2] for the meanings of the other 9
+#' schemes.
+#'
 #' @section A note on scales:
-#' The user may encounter data files with a variety of scales for temperature and
+#' 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.
@@ -644,10 +665,8 @@ cnvName2oceName <- function(h, columns=NULL, debug=getOption("oceDebug"))
 #' 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
 #' f <- system.file("extdata", "ctd.cnv", package="oce")
 #' ## Read the file in the normal way
@@ -662,7 +681,9 @@ cnvName2oceName <- function(h, columns=NULL, debug=getOption("oceDebug"))
 #' information is given in the Sea-Bird data-processing manual
 #' \url{http://www.seabird.com/document/sbe-data-processing-manual}.
 #'
-#' 2. A SBE data processing manual is at \url{http://www.seabird.com/document/sbe-data-processing-manual}.
+#' 2. A SBE data processing manual is at \url{http://www.seabird.com/document/sbe-data-processing-manual};
+#' as of 2018-07-05, the latest version was named
+#' \code{SBEDataProcessing_7.26.4.pdf} and had release date 12/08/2017.
 read.ctd.sbe <- function(file, columns=NULL, station=NULL, missingValue,
                          monitor=FALSE, debug=getOption("oceDebug"), processingLog, ...)
 {