Documentation update

Author: pvanlaake

DESCRIPTION

@@ -11,7 +11,7 @@ Description: Support for all calendars as specified in the Climate and Forecast
     Climate Change (IPCC). This package specifically allows the user to work 
     with any of the CF-compliant calendars (many of which are not compliant with 
     POSIXt). The CF time coordinate is formally defined in the CF Metadata 
-    Conventions document available at <https://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#time-coordinate>.
+    Conventions document available at <https://cfconventions.org/Data/cf-conventions/cf-conventions-1.11/cf-conventions.html#time-coordinate>.
 License: MIT + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -11,7 +11,7 @@ export(CFtimestamp)
 export(calendar)
 export(definition)
 export(indexOf)
-export(is.complete)
+export(is_complete)
 export(offsets)
 export(origin)
 export(resolution)

NEWS.md

@@ -25,7 +25,7 @@ limited to month names and no weekday information can be generated. The `CFrange
 function has a new "format" parameter to support the same functionality.
 * `as.character()` and `length()` methods added that return a vector of timestamps 
 or the number of offsets in a CFtime instance, respectively.
-* Several methods have been renamed (most notably `CFcomplete()` to `is.complete()`
+* Several methods have been renamed (most notably `CFcomplete()` to `is_complete()`
 and `CFsubset()` to `slab()`) to be more consistent with the R universe. Some
 datum methods (deep down where regular mortals do not dwell) have been deleted.
 * Minor code fixes, see GitHub commits.

R/CFdatum.R

@@ -40,22 +40,21 @@ setClass("CFdatum",
 #' instance is read-only. The parameters to the call are typically read from a
 #' CF-compliant data file with climatological observations or predictions.
 #'
-#' @param definition character. An atomic string describing the time coordinate
+#' @param definition character. A character string describing the time coordinate
 #' of a CF-compliant data file.
-#' @param calendar character. An atomic string describing the calendar to use
+#' @param calendar character. A character string describing the calendar to use
 #' with the time dimension definition string.
 #'
 #' @returns An object of the `CFdatum` class.
 #' @noRd
 CFdatum <- function(definition, calendar) {
   stopifnot(length(definition) ==  1L, length(calendar) == 1L)
-  definition <- tolower(definition)
   calendar <- tolower(calendar)
 
   parts <- strsplit(definition, " ")[[1L]]
-  if ((length(parts) < 3L) || !(parts[2L] %in% c("since", "after", "from", "ref", "per")))
+  if ((length(parts) < 3L) || !(tolower(parts[2L]) %in% c("since", "after", "from", "ref", "per")))
     stop("Definition string does not appear to be a CF-compliant time coordinate description")
-  u <- which(CFt$CFunits$unit == parts[1L])
+  u <- which(CFt$CFunits$unit == tolower(parts[1L]))
   if (length(u) == 0L) stop("Unsupported unit: ", parts[1L])
 
   cal <- CFt$calendars$id[which(calendar == CFt$calendars$name)]

R/CFfactor.R

@@ -65,9 +65,9 @@
 #' dimension of the result of, say, `apply(A, 1:2, tapply, Af, FUN)`. The
 #' 'CFtime' attribute is `NULL` for epoch factors.
 #'
-#' @param cf CFtime. An atomic instance of the `CFtime` class whose offsets will
+#' @param cf CFtime. An instance of the `CFtime` class whose offsets will
 #'   be used to construct the factor.
-#' @param period character. An atomic character string with one of the values
+#' @param period character. A character string with one of the values
 #'   "year", "season", "quarter", "month" (the default), "dekad" or "day".
 #' @param epoch numeric or list, optional. Vector of years for which to
 #'   construct the factor, or a list whose elements are each a vector of years.
@@ -104,7 +104,7 @@ CFfactor <- function(cf, period = "month", epoch = NULL) {
 
   period <- tolower(period)
   if (!((length(period) == 1L) && (period %in% CFt$factor_periods)))
-    stop("Period specifier must be an atomic value of a supported period")
+    stop("Period specifier must be a single value of a supported period")
 
   # No fine-grained period factors for coarse source data
   timestep <- CFt$units$seconds[cf@datum@unit] * cf@resolution;
@@ -396,7 +396,7 @@ CFfactor_coverage <- function(cf, f, coverage = "absolute") {
     stop("Argument `f` must be a factor generated by the function `CFfactor()`")
 
   if (!(is.character(coverage) && coverage %in% c("absolute", "relative")))
-    stop("Argument `coverage` must be an atomic string with a value of \"absolute\" or \"relative\"")
+    stop("Argument `coverage` must be a chaarcter string with a value of \"absolute\" or \"relative\"")
 
   if (coverage == "relative") {
     cal <- cf@datum@cal_id

R/CFformat.R

@@ -13,7 +13,7 @@
 #' `asPOSIX = TRUE`.
 #'
 #' @param cf CFtime. The `CFtime` instance that contains the offsets to use.
-#' @param format character. An atomic string with either of the values "date" or
+#' @param format character. A character string with either of the values "date" or
 #'   "timestamp". If the argument is not specified, the format used is
 #'   "timestamp" if there is time information, "date" otherwise.
 #' @param asPOSIX logical. If `TRUE`, for "standard", "gregorian" and
@@ -94,10 +94,10 @@ CFtimestamp <- function(cf, format = NULL, asPOSIX = FALSE) {
 #'
 #' Internal function
 #'
-#' @param ts data.frame of decomposed offsets
-#' @param tz character. Atomic time zone string
-#' @param format character. Atomic character string with the format specifiers
-#' @returns Character vector of formatted timestamps
+#' @param ts data.frame of decomposed offsets.
+#' @param tz character. Time zone character string.
+#' @param format character. A character string with the format specifiers.
+#' @returns Character vector of formatted timestamps.
 #' @noRd
 .format_format <- function(ts, tz, format) {
   # Expand any composite specifiers

R/CFparse.R

@@ -122,7 +122,7 @@ CFparse <- function(cf, x) {
     "(?::([0-5][0-9]))?",
     "(?:\\.([0-9]*))?",
     ")?",
-    "(?:([Z+-])([01][0-9]|2[0-3])?(?::(00|15|30|45))?", ## FIXME: Z, smaller number of captures
+    "(?:([Z+-])([01][0-9]|2[0-3])?(?::(00|15|30|45))?", ## FIXME: Z?, smaller number of captures
     ")?$"
   )
 

R/CFtime-package.R

@@ -8,7 +8,7 @@
 #' Climate Change (IPCC). This package specifically allows the user to work
 #' with any of the CF-compliant calendars (many of which are not compliant with
 #' POSIXt). The CF time coordinate is formally defined in the
-#' [CF Metadata Conventions document](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#time-coordinate).
+#' [CF Metadata Conventions document](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.11/cf-conventions.html#time-coordinate).
 #'
 #' The package can create a `CFtime` instance from scratch or, more commonly, it
 #' can use the dimension attributes and dimension variable values from a NetCDF
@@ -26,7 +26,7 @@
 #' * [`Append`][CFtime-append] additional time steps to a CFtime instance
 #' * [CFtimestamp()] and [format()]: Generate a vector of character or `POSIXct` timestamps from a CFtime instance
 #' * [CFrange()]: Timestamps of the two endpoints in the time series
-#' * [is.complete()]: Does the CFtime instance have a complete time series between endpoints?
+#' * [is_complete()]: Does the CFtime instance have a complete time series between endpoints?
 #' * [CFmonth_days()]: How many days are there in a month using the CFtime calendar?
 #'
 #' **Factors and coverage**
@@ -36,7 +36,7 @@
 #'
 #' **Filtering and selection**
 #' * [slab()]: Logical vector of time steps between two extreme points.
-#' * [indexOf()]: Index values of time steps in the time series, possibly with
+#' * [indexOf()]: Index values in the time series of given timestamps, possibly with
 #' fractional part for interpolation.
 #' @keywords internal
 #' @aliases CFtime-package

R/CFtime.R

@@ -1,6 +1,6 @@
 #' CF Metadata Conventions time representation
 #'
-#' @slot datum CFdatum. The atomic origin upon which the `offsets` are based.
+#' @slot datum CFdatum. The origin upon which the `offsets` are based.
 #' @slot resolution numeric. The average number of time units between offsets.
 #' @slot offsets numeric. A vector of offsets from the datum.
 #' @slot bounds Optional, the bounds for the offsets. If not set, it is the
@@ -27,13 +27,13 @@ setClass("CFtime",
 #' observations or climate projections. Specification of arguments can also be
 #' made manually in a variety of combinations.
 #'
-#' @param definition character. An atomic string describing the time coordinate
+#' @param definition character. A character string describing the time coordinate
 #'   of a CF-compliant data file.
-#' @param calendar character. An atomic string describing the calendar to use
+#' @param calendar character. A character string describing the calendar to use
 #'   with the time dimension definition string. Default value is "standard".
 #' @param offsets numeric or character, optional. When numeric, a vector of
 #'   offsets from the origin in the time series. When a character vector,
-#'   timestamps in ISO8601 or UDUNITS format. When an atomic character string, a
+#'   timestamps in ISO8601 or UDUNITS format. When a character string, a
 #'   timestamp in ISO8601 or UDUNITS format and then a time series will be
 #'   generated with a separation between steps equal to the unit of measure in
 #'   the definition, inclusive of the definition timestamp. The unit of measure
@@ -87,9 +87,9 @@ CFtime <- function(definition, calendar = "standard", offsets = NULL) {
 #'
 #' @param cf CFtime. An instance of `CFtime`.
 #'
-#' @returns `calendar()` and `unit()` return an atomic character string.
+#' @returns `calendar()` and `unit()` return a character string.
 #'   `origin()` returns a data frame of timestamp elements with a single row
-#'   of data. `timezone()` returns the datum time zone as an atomic character
+#'   of data. `timezone()` returns the datum time zone as a character
 #'   string. `offsets()` returns a vector of offsets or `NULL` if no offsets
 #'   have been set.
 #'
@@ -251,7 +251,7 @@ setMethod("show", "CFtime", function(object) {
 #'
 #' @param x CFtime. A CFtime instance whose offsets will be returned as
 #'   timestamps.
-#' @param format character. An atomic character string with strptime format
+#' @param format character. A character string with strptime format
 #'   specifiers.
 #'
 #' @returns A vector of character strings with a properly formatted timestamp.
@@ -270,7 +270,7 @@ setMethod("format", "CFtime", function(x, format) {
     stop("package `stringr` is required - please install it first") # nocov
 
   if (missing(format) || !is.character(format) || length(format) != 1)
-    stop("`format` argument must be an atomic string with formatting specifiers")
+    stop("`format` argument must be a character string with formatting specifiers")
 
   ts <- .offsets2time(x@offsets, x@datum)
   if (nrow(ts) == 0L) return()
@@ -313,6 +313,7 @@ setMethod("format", "CFtime", function(x, format) {
 #'   `breaks` is a character vector of timestamps, attribute 'CFtime' holds an
 #'   instance of CFtime that has the same definition as `x`, but with (ordered)
 #'   offsets generated from the `breaks`. Attribute 'epoch' is always -1.
+#' @aliases cut
 #' @seealso [CFfactor()] produces a factor for several fixed periods, including
 #'   for epochs.
 #' @export
@@ -432,7 +433,7 @@ setMethod("indexOf", c("ANY", "CFtime"), function(x, cf, method = "constant") {
             method %in% c("constant", "linear"))
 
   if (is.numeric(x)) {
-    if (!(all(x < 0) || all(x > 0)))
+    if (!(all(x < 0, na.rm = TRUE) || all(x > 0, na.rm = TRUE)))
       stop("Cannot mix positive and negative index values")
 
     intv <- (1:length(cf))[x]
@@ -462,8 +463,8 @@ setMethod("indexOf", c("ANY", "CFtime"), function(x, cf, method = "constant") {
 #'
 #' @description Character representation of the extreme values in the time series
 #'
-#' @param x An instance of the `CFtime` class
-#' @param format Atomic character string with format specifiers, optional
+#' @param x An instance of the `CFtime` class.
+#' @param format A character string with format specifiers, optional.
 #'
 #' @returns character. Vector of two character representations of the extremes of the time series.
 #' @export
@@ -501,8 +502,8 @@ setMethod("CFrange", "CFtime", function(x, format = "") .ts_extremes(x, format))
 #' @export
 #' @examples
 #' cf <- CFtime("days since 1850-01-01", "julian", 0:364)
-#' is.complete(cf)
-is.complete <- function(x) {
+#' is_complete(cf)
+is_complete <- function(x) {
   if (!methods::is(x, "CFtime")) stop("Argument must be an instance of CFtime")
   if (length(x@offsets) == 0L) NA
   else .ts_equidistant(x)
@@ -685,7 +686,7 @@ setMethod("+", c("CFtime", "numeric"), function(e1, e2) {
 #' package.
 #'
 #' @param x CFtime. The time series to operate on.
-#' @param format character. Optional atomic character string that specifies
+#' @param format character. Optional character string that specifies
 #'   alternate format.
 #'
 #' @returns Vector of two character strings that represent the starting and
@@ -698,7 +699,7 @@ setMethod("+", c("CFtime", "numeric"), function(e1, e2) {
 .ts_extremes <- function(x, format = "") {
   if (length(x@offsets) == 0L) return(c(NA_character_, NA_character_))
   if (!missing(format) && ((!is.character(format)) || length(format) != 1))
-    stop("`format` parameter, when present, must be an atomic string with formatting specifiers")
+    stop("`format` parameter, when present, must be a character string with formatting specifiers")
 
   time <- .offsets2time(range(x@offsets), x@datum)