From 1c61ee64c214c6147d9a830e85dff747c6c4bbbb Mon Sep 17 00:00:00 2001 From: dankelley Date: Thu, 5 Jul 2018 17:17:26 -0300 Subject: [PATCH] document new time scheme in read.ctd.sbe() --- R/ctd.sbe.R | 29 +++++++++++++++++++++++++---- man/read.ctd.sbe.Rd | 30 +++++++++++++++++++++++++++--- 2 files changed, 52 insertions(+), 7 deletions(-) diff --git a/R/ctd.sbe.R b/R/ctd.sbe.R index 3c306a720a..8370b045df 100644 --- a/R/ctd.sbe.R +++ b/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, ...) { diff --git a/man/read.ctd.sbe.Rd b/man/read.ctd.sbe.Rd index 234886541c..bb2056dcb5 100644 --- a/man/read.ctd.sbe.Rd +++ b/man/read.ctd.sbe.Rd @@ -79,9 +79,32 @@ slot as \code{dataNamesOriginal}, and are displayed with \code{summary} alongsid 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. @@ -96,7 +119,6 @@ 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. } @@ -115,7 +137,9 @@ d <- read.ctd(f, columns=list( 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. } \seealso{ Other things related to \code{ctd} data: \code{\link{[[,ctd-method}},