read.ctd.sbe() improvements (issues 1457 and 1458)

R/ctd.sbe.R

@@ -51,8 +51,11 @@
 #'   \code{C2-C1mS/cm}  \tab \code{conductivityDifference}       \tab mS/cm               \tab    \cr
 #'   \code{C2-C1uS/cm}  \tab \code{conductivityDifference}       \tab uS/cm               \tab    \cr
 #'   \code{c~mS/cm}     \tab \code{conductivity}                 \tab mS/cm               \tab    \cr
+#'   \code{cond~mS/cm}  \tab \code{conductivity}                 \tab mS/cm               \tab    \cr
 #'   \code{c~S/m}       \tab \code{conductivity}                 \tab S/m                 \tab    \cr
+#'   \code{cond~S/m}    \tab \code{conductivity}                 \tab S/m                 \tab    \cr
 #'   \code{c~uS/cm}     \tab \code{conductivity}                 \tab uS/cm               \tab    \cr
+#'   \code{cond~uS/cm}  \tab \code{conductivity}                 \tab uS/cm               \tab    \cr
 #'   \code{CStarAt~}    \tab \code{beamAttenuation}              \tab 1/m                 \tab    \cr
 #'   \code{CStarTr~}    \tab \code{beamTransmission}             \tab percent             \tab    \cr
 #'   \code{density~~}   \tab \code{density}                      \tab kg/m^3              \tab    \cr
@@ -151,14 +154,14 @@
 #'   \code{t38~90C}     \tab \code{temperature}                  \tab degC; ITS-90         \tab   \cr
 #'   \code{t3868C~}     \tab \code{temperature}                  \tab degC; IPTS-68        \tab   \cr
 #'   \code{t38~38C}     \tab \code{temperature}                  \tab degC; IPTS-68        \tab   \cr
-#'   \code{timeH}       \tab \code{time}                         \tab hour; elapsed        \tab   \cr
-#'   \code{timeJ}       \tab \code{time}                         \tab day; elapsed         \tab   \cr
-#'   \code{timeJV2}     \tab \code{time}                         \tab day; elapsed         \tab   \cr
-#'   \code{timeK}       \tab \code{time}                         \tab s; since Jan 1, 2000 \tab\cr
-#'   \code{timeM}       \tab \code{time}                         \tab minute; elapsed      \tab   \cr
-#'   \code{timeN}       \tab \code{time}                         \tab s; NMEA since Jan 1, 1970\tab\cr
-#'   \code{timeQ}       \tab \code{time}                         \tab s; NMEA since Jan 1, 2000\tab\cr
-#'   \code{timeS}       \tab \code{time}                         \tab s; elapsed           \tab   \cr
+#'   \code{timeH}       \tab \code{timeH}                        \tab hour; elapsed        \tab   \cr
+#'   \code{timeJ}       \tab \code{timeJ}                        \tab julian day           \tab   \cr
+#'   \code{timeJV2}     \tab \code{timeJV2}                      \tab julian day           \tab   \cr
+#'   \code{timeK}       \tab \code{timeK}                        \tab s; since Jan 1, 2000 \tab   \cr
+#'   \code{timeM}       \tab \code{timeM}                        \tab minute; elapsed      \tab   \cr
+#'   \code{timeN}       \tab \code{timeN}                        \tab s; NMEA since Jan 1, 1970\tab\cr
+#'   \code{timeQ}       \tab \code{timeQ}                        \tab s; NMEA since Jan 1, 2000\tab\cr
+#'   \code{timeS}       \tab \code{timeS}                        \tab s; elapsed           \tab   \cr
 #'   \code{turbflTC~}   \tab \code{turbidity}                    \tab NTU; Turner Cyclops  \tab   \cr
 #'   \code{turbflTCdiff}\tab \code{turbidityDifference}          \tab NTU; Turner Cyclops  \tab   \cr
 #'   \code{turbWETbb~}  \tab \code{turbidity}                    \tab 1/(m*sr); WET Labs ECO\tab   \cr
@@ -224,8 +227,6 @@ cnvName2oceName <- function(h, columns=NULL, debug=getOption("oceDebug"))
     ## If 'name' is mentioned in columns, then use columns and ignore the lookup table.
     if (!is.null(columns)) {
         oceDebug(debug, "columns given. Look for name='", name, "' in it\n", sep="")
-        message("next is columns:")
-        print(columns)
         cnames <- names(columns)
         for (i in seq_along(cnames)) {
             if (name == columns[[i]]$name) {
@@ -255,13 +256,13 @@ cnvName2oceName <- function(h, columns=NULL, debug=getOption("oceDebug"))
     } else if (1 == length(grep("^C2-C1uS/cm$", name, useBytes=TRUE))) {
         name <- "conductivityDifference"
         unit <- list(unit=expression(mu*S/cm), scale="")
-    } else if (1 == length(grep("^c((_)|([0-2]))mS/cm$", name, useBytes=TRUE))) {
+    } else if (1 == length(grep("^c(ond)?((_)|([0-2]))mS/cm$", name, useBytes=TRUE))) {
         name <- "conductivity"
         unit <- list(unit=expression(mS/cm), scale="")
-    } else if (1 == length(grep("^c((_)|([0-2]))S/m$", name, useBytes=TRUE))) {
+    } else if (1 == length(grep("^c(ond)?((_)|([0-2]))S/m$", name, useBytes=TRUE))) {
         name <- "conductivity"
         unit <- list(unit=expression(S/m), scale="")
-    } else if (1 == length(grep("^c((_)|([0-2]))uS/cm$", name, useBytes=TRUE))) {
+    } else if (1 == length(grep("^c(ond)?((_)|([0-2]))uS/cm$", name, useBytes=TRUE))) {
         name <- "conductivity"
         unit <- list(unit=expression(mu*S/cm), scale="")
     } else if (1 == length(grep("^CStarTr[0-9]$", name, useBytes=TRUE))) {
@@ -552,29 +553,29 @@ cnvName2oceName <- function(h, columns=NULL, debug=getOption("oceDebug"))
         name <- "temperature"
         unit <- list(unit=expression(degree*C), scale="ITS-90")
     } else if (1 == length(grep("^timeH$", name, useBytes=TRUE))) {
-        name <- "time"
-        unit <- list(unit=expression(hour), scale="elapsed")
+        name <- "timeH"
+        unit <- list(unit=expression(hour), scale="")
     } else if (1 == length(grep("^timeJ$", name, useBytes=TRUE))) {
-        name <- "time"
-        unit <- list(unit=expression(day), scale="elapsed")
+        name <- "timeJ"
+        unit <- list(unit=expression(day), scale="")
     } else if (1 == length(grep("^timeJV2$", name, useBytes=TRUE))) {
-        name <- "time"
-        unit <- list(unit=expression(day), scale="elapsed")
+        name <- "timeJV2"
+        unit <- list(unit=expression(day), scale="")
     } else if (1 == length(grep("^timeK$", name, useBytes=TRUE))) {
-        name <- "time"
+        name <- "timeK"
         unit <- list(unit=expression(s), scale="since Jan 1, 2000")
     } else if (1 == length(grep("^timeM$", name, useBytes=TRUE))) {
-        name <- "time"
-        unit <- list(unit=expression(minute), scale="elapsed")
+        name <- "timeM"
+        unit <- list(unit=expression(minute), scale="")
     } else if (1 == length(grep("^timeN$", name, useBytes=TRUE))) {
-        name <- "time"
+        name <- "timeN"
         unit <- list(unit=expression(s), scale="NMEA since Jan 1, 1970")
     } else if (1 == length(grep("^timeQ$", name, useBytes=TRUE))) {
-        name <- "time"
+        name <- "timeQ"
         unit <- list(unit=expression(s), scale="NMEA since Jan 1, 2000")
     } else if (1 == length(grep("^timeS$", name, useBytes=TRUE))) {
-        name <- "time"
-        unit <- list(unit=expression(s), scale="elapsed")
+        name <- "timeS"
+        unit <- list(unit=expression(s), scale="")
     } else if (1 == length(grep("^tsa$", name, useBytes=TRUE))) {
         name <- "thermostericAnomaly"
         unit <- list(unit=expression(10^-8*m^3/kg), scale="")
@@ -666,15 +667,19 @@ cnvName2oceName <- function(h, columns=NULL, debug=getOption("oceDebug"))
 #' 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
+#' caused confusion for data files that also have a time column, and so
 #' an entry named \code{"time"} is no longer stored in the \code{metadata} slot,
-#' for those cases in which an elapsed-time column exists in the data file.
-#' Importantly, there is a possibility for confusion in the storage
+#' for those cases in which an time column exists in the data file.
+#'
+#' @section A note on time columns:
+#' Until Nov 9, 2018,
+#' there was a possibility for confusion in the storage
 #' of that 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
+#' Howver, on that date, a change was made, so that \code{read.ctd.sbe} simply
+#' used the column names as Seabird intends.
+#' 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
@@ -706,7 +711,7 @@ cnvName2oceName <- function(h, columns=NULL, debug=getOption("oceDebug"))
 #' 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(expression(), scale="PSS-78"))))
+#'   salinity=list(name="salt", unit=list(unit=expression(), scale="PSS-78"))))
 #'
 #' @references
 #' 1. The Sea-Bird SBE 19plus profiler is described at

man-roxygen/readCtdTemplate.R

@@ -9,22 +9,30 @@
 #' value is a vector containing CTD objects created by reading the files from
 #' \code{\link{list.files}} with \code{pattern} set to the specified wildcard
 #' pattern.
-#' 
+#'
 #' @param 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.
-#' 
+#'
 #' @param columns An optional \code{\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}} and \code{\link{read.ctd.odf}}; see
-#' \dQuote{Examples}.
-#' 
+#' \code{\link{read.ctd.sbe}} and \code{\link{read.ctd.odf}}. For example,
+#' if a data file named salinity as \code{"SAL"}, then using
+#' \preformatted{
+#' d <- read.ctd(f, columns=list(
+#'     salinity=list(name="SAL",
+#'                   unit=list(unit=expression(),
+#'                   scale="PSS-78"))))
+#'}
+#' would assign the \code{"SAL"} column to the \code{salinity} entry in the data
+#' slot of the CTD object returned by the \code{read.*} function.
+#'
 #' @param 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.
-#' 
+#'
 #' @param 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