Minor edits and documentation updates

Author: pvanlaake

R/CFCalendar.R

@@ -151,7 +151,7 @@ CFCalendar <- R6::R6Class("CFCalendar",
     #' @return `TRUE` if the instance in argument `cal` is equivalent to
     #'   `self`, `FALSE` otherwise.
     is_equivalent = function(cal) {
-      sum(self$origin[1L,1L:6L] == cal$origin[1L,1L:6L]) == 6L &&  # Offset column is NA
+      all(self$origin[1L,1L:6L] == cal$origin[1L,1L:6L]) &&  # Offset column is NA
       self$is_compatible(cal)
     },
 

R/CFtime.R

@@ -906,6 +906,13 @@ CFTime <- R6::R6Class("CFTime",
     }
   ),
   active = list(
+    #' @field calendar (read-only) The calendar of this `CFTime` instance, a
+    #'   descendant of the [CFCalendar] class.
+    calendar = function(value) {
+      if (missing(value))
+        self$cal
+    },
+
     #' @field unit (read-only) The unit string of the calendar and time series.
     unit = function(value) {
       if (missing(value))

R/api.R

@@ -359,22 +359,6 @@ slice <- function(x, extremes, rightmost.closed = FALSE) {
   x$slice(extremes, rightmost.closed)
 }
 
-#' Which time steps fall within two extreme values
-#'
-#' Avoid using this function, use [slice()] instead. This function will be
-#' deprecated in the near future.
-#'
-#' @param x,extremes,rightmost.closed See `slice()`.
-#' @returns See `slice()`.
-#' @export
-#' @examples
-#' t <- CFtime("hours since 2023-01-01 00:00:00", "standard", 0:23)
-#' slab(t, c("2022-12-01", "2023-01-01 03:00"))
-slab <- function(x, extremes, rightmost.closed = FALSE) {
-  warning("Function `slab()` is deprecated. Use function `slice()` instead", call. = FALSE)
-  x$slice(extremes, rightmost.closed)
-}
-
 #' Equivalence of CFTime objects
 #'
 #' This operator can be used to test if two [CFTime] objects represent the same

R/deprecated.R

@@ -13,10 +13,11 @@
 #' | CFmonth_days()      | [month_days()]       |
 #' | CFparse()           | [parse_timestamps()] |
 #' | CFrange()           | [range()]            |
-#' | CFsubset()          | [slice()]             |
+#' | CFsubset()          | [slice()]            |
+#' | slab()              | [slice()]            |
 #' | CFtimestamp()       | [as_timestamp()]     |
 #'
-#' @param t,x,format,asPOSIX,extremes See replacement functions.
+#' @param t,x,format,asPOSIX,extremes,rightmost.closed See replacement functions.
 #'
 #' @returns See replacement functions.
 
@@ -46,8 +47,15 @@ CFcomplete <- function(x) {
 #' @rdname deprecated_functions
 #' @export
 CFsubset <- function(x, extremes) {
-  warning("Function `CFsubset()` is deprecated. Use `slab()` instead.")
-  slab(x, extremes)
+  warning("Function `CFsubset()` is deprecated. Use `slice()` instead.")
+  slice(x, extremes)
+}
+
+#' @rdname deprecated_functions
+#' @export
+slab <- function(x, extremes, rightmost.closed = FALSE) {
+  warning("Function `slab()` is deprecated. Use function `slice()` instead", call. = FALSE)
+  x$slice(extremes, rightmost.closed)
 }
 
 #' @rdname deprecated_functions

man/CFtime.Rd

@@ -14,95 +14,45 @@ knitr::opts_chunk$set(
 )
 ```
 
-`CFtime` is based on version 1.12 of the CF Metadata Conventions. The text for
-the *time coordinate* in the conventions may be consulted [here](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.12/cf-conventions.html#time-coordinate).
+`CFtime` is based on version 1.12 of the CF Metadata Conventions. The text for the *time coordinate* in the conventions may be consulted [here](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.12/cf-conventions.html#time-coordinate).
 
-> The *time coordinate* is one of four coordinate types that receive "special
-treatment" in the conventions. The other three are longitude, latitude and the
-vertical. If you require convention-compliant support for any of these three
-other coordinate types, please consider using package [`ncdfCF`](https://cran.r-project.org/package=ncdfCF) 
-which supports all three coordinate types and links with `CFtime` for support of 
-the time coordinate.
+> The *time coordinate* is one of four coordinate types that receive "special treatment" in the conventions. The other three are longitude, latitude and the vertical. If you require convention-compliant support for any of these three other coordinate types, please consider using package [`ncdfCF`](https://cran.r-project.org/package=ncdfCF) which supports all three coordinate types and links with `CFtime` for support of the time coordinate.
 
-This document sets out how the `CFtime` package conforms to the CF Metadata
-Conventions, by section of the conventions. This information is mostly useful
-for developers and expert users.
+This document sets out how the `CFtime` package conforms to the CF Metadata Conventions, by section of the conventions. This information is mostly useful for developers and expert users.
 
-If you have issues reading a netCDF file that is due to conformance of package
-`CFtime` with the CF Metadata Conventions, please [open an issue on GitHub](https://github.com/pvanlaake/CFtime/issues).
+If you have issues reading a netCDF file that is due to conformance of package `CFtime` with the CF Metadata Conventions, please [open an issue on GitHub](https://github.com/pvanlaake/CFtime/issues).
 
-Please note that there are many netCDF files out there that are not claiming 
-adherence to the CF Metadata Conventions but whose time coordinate can still be 
-successfully handled by `CFtime`: the `netCDF` library itself provides the basic
-plumbing.
+Please note that there are many netCDF files out there that are not claimingadherence to the CF Metadata Conventions but whose time coordinate can still be successfully handled by `CFtime`: the `netCDF` library itself provides the basic plumbing.
 
 ## 4.4. Time Coordinate
 
-A `CFTime` object is constructed from information that is contained in the 
-`units` and `calendar` attributes for a time coordinate read out of a netCDF 
-file. The package does not actually access the netCDF file, it only uses the
-information that was read out of the file by e.g. `ncdfCF`. Consequently, the
-`CFtime` package can also construct a `CFTime` object from suitable character
-strings.
+A `CFTime` object is constructed from information that is contained in the `units` and `calendar` attributes for a time coordinate read out of a netCDF file. The package does not actually access the netCDF file, it only uses the information that was read out of the file by e.g. `ncdfCF`. Consequently, the `CFtime` package can also construct a `CFTime` object from suitable character strings.
 
-This package is agnostic to the orientation of the axes in any data variable
-that references the time coordinate. Consequently, the `standard_name` and 
-`axis` attributes are not considered by this package (but the `ncdfCF` package
-handles both). Identification of a time coordinate is done by the `units`
-attribute, alone.
+This package is agnostic to the orientation of the axes in any data variable that references the time coordinate. Consequently, the `standard_name` and `axis` attributes are not considered by this package (but the `ncdfCF` package handles both). Identification of a time coordinate is done by the `units` attribute, alone.
 
 ## 4.4.1. Time Coordinate Units
 
-The `CFtime` package fully supports the units `"second"`, `"minute"`, `"hour"` 
-and `"day"`, including abbreviated and/or plural forms. Unit `"second"` is the
-SI second, a `"minute"` equals 60 seconds, an `"hour"` equals 3,600 seconds,
-and a `"day"` equals 86,400 seconds. This is exactly as expected, but refer to
-the `utc` calendar, below, for peculiarities of that calendar.
+The `CFtime` package fully supports the units `"second"`, `"minute"`, `"hour"` and `"day"`, including abbreviated and/or plural forms. Unit `"second"` is (nominally) the SI second, a `"minute"` equals 60 seconds, an `"hour"` equals 3,600 seconds, and a `"day"` equals 86,400 seconds. This is exactly as expected, but refer to the `utc` calendar, below, for peculiarities of that calendar.
 
-The `units` `"month"` and `"year"` are accepted on input but not using their
-definition in UDUNITS. Instead, `"year"` is a calendar year, so either 360, 365 
-or 366 days depending on its value and the calendar. A `"month"` is similarly a
-calendar month. Use of either of these time units is discouraged by the CF
-Metadata Conventions.
+The `units` `"month"` and `"year"` are accepted on input but not using their definition in UDUNITS. Instead, `"year"` is a calendar year, so either 360, 365 or 366 days depending on its value and the calendar. A `"month"` is similarly a calendar month. Use of either of these time units is discouraged by the CF Metadata Conventions.
 
 Other UDUNITS time units are not supported by this package.
 
-All variants of the glue word `"since"` are accepted, being `"after"`, `"from"`,
-`"ref"` and `"per"`.
+All variants of the glue word `"since"` are accepted, being `"after"`, `"from"`, `"ref"` and `"per"`.
 
-The *"reference datetime string"* should be formatted using the UDUNITS broken
-timestamp format or following [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)
-rules, but noting that datetimes valid in specific calendars other than
-Gregorian (such as `2023-02-30` in the `360_day` calendar) are acceptable as
-well. The UDUNITS "packed" format is not supported.
+The *"reference datetime string"* should be formatted using the UDUNITS broken timestamp format or following [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) rules, but noting that datetimes valid in specific calendars other than Gregorian (such as `2023-02-30` in the `360_day` calendar) are acceptable as well. The UDUNITS "packed" format is not supported.
 
-Timezone information can only use `00`, `15`, `30` and `45` to indicate minutes;
-other minute offsets have never been used anywhere. A time zone value of `"UTC"`
-is accepted, as an extension to the conventions. Even though the conventions 
-don't indicate it, the `tai` and `utc` calendars can carry no time zone 
-indication as that does not exist for either of these calendars.
+Timezone information can only use `00`, `15`, `30` and `45` to indicate minutes; other minute offsets have never been used anywhere. A time zone value of `"UTC"` is accepted, as an extension to the conventions. Even though the conventions don't indicate it, the `tai` and `utc` calendars can carry no time zone indication as that does not exist for either of these calendars.
 
 ## 4.4.2. Calendar
 
-If a `calendar` attribute is not given, `"standard"` is assumed, being the
-default calendar as per the conventions.
-
-* `standard` (or the deprecated `gregorian`): Fully conformant, but leap seconds
-are never considered (see below). The combination of a *reference datetime* and
-other *datetimes* spanning the gap between 1582-10-05 and 1582-10-15, in either 
-direction, is supported.
-* `proleptic_gregorian`: Fully conformant, but leap seconds are never considered
-(see below).
-* `julian`: Fully conformant, but, despite the suggestion in the conventions,
-leap seconds do not exist in this calendar and are thus never considered.
-* `utc`: Fully conformant. Leap seconds are always accounted so when a leap 
-second is included, UTC time progresses like 
-`23:59:58 ... 23:59:59 ... 23:59:60 ... 00:00:00 ... 00:00:01`.
-This also extends to minutes `23:59:00 ... 23:59:60 ... 00:00:59 ... 00:01:59`, 
-always adding 60 seconds. Likewise for `hours` and `days`. Units `"year"` and 
-`"month"` are not allowed, and neither is any time zone indication.
-* `tai`: Fully conformant. Units `"year"` and `"month"` are not allowed, and 
-neither is any time zone indication.
+If a `calendar` attribute is not given, `"standard"` is assumed, being the default calendar as per the conventions.
+
+* `standard` (or the deprecated `gregorian`): Fully conformant, but leap seconds are never considered (see below). The combination of a *reference datetime* and other *datetimes* spanning the gap between 1582-10-05 and 1582-10-15, in either direction, is supported.
+* `proleptic_gregorian`: Fully conformant, but leap seconds are never considered (see below).
+* `julian`: Fully conformant, but, despite the suggestion in the conventions, leap seconds do not exist in this calendar and are thus never considered.
+* `utc`: Fully conformant but with an origin of 1972-01-01T00:00:00 (earlier datetimes not allowed). Leap seconds are always accounted so when a leap second is included, UTC time progresses like `23:59:58 ... 23:59:59 ... 23:59:60 ... 00:00:00 ... 00:00:01`. This also extends to minutes `23:59:00 ... 23:59:60 ... 00:00:59 ... 00:01:59`, always adding 60 seconds. Likewise for `hours` and `days`. Units `"year"` and `"month"` are not allowed, and neither is any time zone indication.
+* `tai`: Fully conformant. Units `"year"` and `"month"` are not allowed, and neither is any time zone indication.
 * `no_leap` / `365_day`: Fully conformant.
 * `all_leap` / `366_day`: Fully conformant.
 * `360_day`: Fully conformant.
@@ -112,17 +62,9 @@ neither is any time zone indication.
 
 The `utc` calendar fully supports leap seconds.
 
-The `julian` calendar has no concept of leap seconds so these are never
-possible or considered. Using a leap second in a `julian` calendar is an error.
+The `julian` calendar has no concept of leap seconds so these are never possible or considered. Using a leap second in a `julian` calendar is an error.
 
-In the `standard` and `proleptic_gregorian` calendars only the variant without
-leap seconds is considered. The `units_metadata` attribute is not considered, so
-assumed to be `"leap seconds: unknown"`. The assumption here is that if second
-accuracy for a data producer is essential, then the entire tool chain from
-observation equipment, to processing, to file recording will have to be of
-known characteristics with regards to UTC time and leap seconds and thus the
-`utc` calendar would be used, rather than `standard` or `proleptic_gregorian`
-with a caveat communicated through the `units_metdata` attribute.
+In the `standard` and `proleptic_gregorian` calendars only the variant without leap seconds is considered. The `units_metadata` attribute is not considered, so assumed to be `"leap seconds: unknown"`. The assumption here is that if second accuracy for a data producer is essential, then the entire tool chain from observation equipment, to processing, to file recording will have to be of known characteristics with regards to UTC time and leap seconds and thus the `utc` calendar would be used, rather than `standard` or `proleptic_gregorian` with a caveat communicated through the `units_metdata` attribute.
 
 ## 4.4.4. Time Coordinates with no Annual Cycle
 
@@ -134,11 +76,6 @@ Not implemented.
 
 ## 7.4. Climatological statistics
 
-The time coordinate with climatological bounds is fully supported, with the
-exception of using year 0 in the `standard` and `julian` calendars to flag
-climatological data (which is a deprecated practice as per the CF Metadata
-Conventions).
+The time coordinate with climatological bounds is fully supported, with the exception of using year 0 in the `standard` and `julian` calendars to flag climatological data (which is a deprecated practice as per the CF Metadata Conventions).
 
-This package is agnostic to the underlying statistical operation that produced
-the *climatological time* so the `cell_methods` attribute is not inspected nor
-interpreted.
+This package is agnostic to the underlying statistical operation that produced the *climatological time* so the `cell_methods` attribute is not inspected nor interpreted.