Skip to contents

Conformance with the CF Metadata Conventions

Source: vignettes/articles/conformance.Rmd
conformance.Rmd

CFtime is based on version 1.13 of the CF Metadata Conventions. The text for the time coordinate in the conventions may be consulted here.

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 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.

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.

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.

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.

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 Variables

Fully conformant

4.4.2. Time Coordinate Units

The CFtime package fully supports the units "second", "minute", "hour" and "day", including abbreviated and/or plural forms. Prefixes for decimal multiples and submultiples (section 3.1.3 of the conventions) may be used. 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.

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".

The “reference datetime string” should be formatted using the UDUNITS broken timestamp format or following ISO8601 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.

Time zone offsets are supported on all calendars, with limitations. The tai and utc calendars may not use a time zone offset other than 0. Time zone offsets are ignored for all of the model calendars.

Time zone offsets 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" or "GMT" is accepted, as an extension to the conventions.

4.4.3. 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. 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.
  • julian: Fully conformant.
  • 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 other than 0.
  • tai: Fully conformant. Units "year" and "month" are not allowed, and neither is any time zone indication other than 0.
  • no_leap / 365_day: Fully conformant.
  • all_leap / 366_day: Fully conformant.
  • 360_day: Fully conformant.
  • none: Fully conformant.

4.4.4. Time Coordinates with no Annual Cycle

Fully conformant.

4.4.5. Explicitly Defined Calendar

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).

This package is agnostic to the underlying statistical operation that produced the climatological time so the cell_methods attribute is not inspected nor interpreted.