diff --git a/cf-conventions.adoc b/cf-conventions.adoc index 3d30dabe..437a678c 100644 --- a/cf-conventions.adoc +++ b/cf-conventions.adoc @@ -39,6 +39,7 @@ include::toc-extra.adoc[] * David Hassell, NCAS and University of Reading * Alan D. Snow, Corteva Agriscience * Tobias Kölling, MPIM +* Dave Allured, NOAA Many others have contributed to the development of CF through their participation in discussions about proposed changes. diff --git a/ch04.adoc b/ch04.adoc index 14e39964..a8bfb561 100644 --- a/ch04.adoc +++ b/ch04.adoc @@ -197,28 +197,20 @@ The `computed_standard_name` attribute indicates that the values in variable [[time-coordinate]] === Time Coordinate -Variables representing time must always explicitly include the **`units`** attribute; there is no default value. The **`units`** attribute takes a string value formatted as per the recommendations in the Udunits package <> . The following excerpt from the Udunits documentation explains the time unit encoding by example: ----- - -The specification: - - seconds since 1992-10-8 15:15:42.5 -6:00 +Variables representing time must always explicitly include the **`units`** attribute; there is no default value. The **`units`** attribute takes a string value formatted as per the recommendations in the <> package. The following excerpt from the UDUNITS documentation explains the time unit encoding by example: +"The specification `seconds since 1992-10-8 15:15:42.5 -6:00` indicates seconds since October 8th, 1992 at 3 hours, 15 minutes and 42.5 seconds in the afternoon in the time zone which is six hours to the west of Coordinated Universal Time (i.e. Mountain Daylight Time). The time zone specification -can also be written without a colon using one or two-digits +can also be written without a colon using one or two digits (indicating hours) or three or four digits (indicating hours -and minutes). - ----- - - +and minutes)." -The acceptable units for time are listed in the link:$$http://www.unidata.ucar.edu/software/udunits/$$[`udunits.dat`] file. The most commonly used of these strings (and their abbreviations) includes **`day (d)`**, **`hour (hr, h)`**, **`minute (min)`** and **`second (sec, s)`**. Plural forms are also acceptable. The reference time string (appearing after the identifier **`since`**) may include date alone; date and time; or date, time, and time zone. The reference time is required. A reference time in year 0 has a special meaning (see <>). +The acceptable units for time are listed in the UDUNITS database. The most commonly used of these strings (and their abbreviations) includes **`day`** (**`d`**), **`hour`** (**`hr`**, **`h`**), **`minute`** (**`min`**) and **`second`** (**`sec`**, **`s`**). Plural forms are also acceptable. -__Note: if the time zone is omitted the default is UTC, and if both time and time zone are omitted the default is 00:00:00 UTC.__ +The reference date/time string (appearing after the identifier **`since`**) may include date alone, or date and time, or date, time and time zone. The reference date/time string is required. If the time zone is omitted the default is UTC, and if both time and time zone are omitted the default is 00:00:00 UTC. We recommend that the unit **`year`** be used with caution. The Udunits package defines a **`year`** to be exactly 365.242198781 days (the interval between 2 successive passages of the sun through vernal equinox). __It is not a calendar year.__ Udunits includes the following definitions for years: a **`common_year`** is 365 days, a **`leap_year`** is 366 days, a **`Julian_year`** is 365.25 days, and a **`Gregorian_year`** is 365.2425 days. @@ -253,6 +245,7 @@ A date/time is the set of numbers which together identify an instant of time, na A time coordinate value represents a date/time. In order to calculate a time coordinate value from a date/time, or the reverse, one must know the **`units`** attribute of the time coordinate variable (containing the time unit of the coordinate values and the reference date/time) and the calendar. The choice of calendar defines the set of dates (year-month-day combinations) which are permitted, and therefore it specifies the number of days between the times of **`0:0:0`** (midnight) on any two dates. +Date/times which are not permitted in a given calendar are prohibited in both the encoded time coordinate values, and in the reference date/time string. It is recommended that the calendar be specified by the **`calendar`** attribute of the time coordinate variable. When a time coordinate value is calculated from a date/time, or the reverse, it is assumed that the coordinate value increases by exactly 60 seconds from the start of any minute (identified by year, month, day, hour, minute, all being integers) to the start of the next minute, with no leap seconds, in all CF calendars. This assumption has various consequences when real-world date/times from calendars which do contain leap seconds (such as UTC) are stored in time coordinate variables: @@ -263,26 +256,25 @@ This assumption has various consequences when real-world date/times from calenda * A date/time in the excluded range must not be used as a reference date/time e.g. **`seconds since 2016-12-31 23:59:60`** is not a permitted value for **`units`**. * It is important to realise that a time coordinate value does not necessarily exactly equal the actual length of the interval of time between the reference date/time and the date/time it represents. -It is recommended that the calendar be specified by the **`calendar`** attribute of the time coordinate variable. -The values currently defined for **`calendar`** are: +The values currently defined for **`calendar`** are listed below. In all calendars except **`360_day`** and **`none`**, the lengths of the months are the same as in the Gregorian calendar for leap years and non-leap years. In the **`julian`** and the default **`standard`** mixed Gregorian/Julian calendar, dates in years before year 0 (i.e. before 0-1-1 0:0:0) are not allowed, and the year in the reference date/time of the units must not be negative. In these calendars, year zero has a special use to indicate a climatology (see <>), but this use of year zero is deprecated. In other calendars, years before year 1 are allowed. -**`gregorian`** or **`standard`**:: Mixed Gregorian/Julian calendar as defined by Udunits. __This is the default.__ +**`standard`**:: Mixed Gregorian/Julian calendar as defined by UDUNITS. This is the default. A deprecated alternative name for this calendar is **`gregorian`**. In this calendar, date/times after (and including) 1582-10-15 0:0:0 are in the Gregorian calendar, in which a year is a leap year if either (i) it is divisible by 4 but not by 100 or (ii) it is divisible by 400. Date/times before (and excluding) 1582-10-5 0:0:0 are in the Julian calendar. Year 1 AD or CE in the **`standard`** calendar is also year 1 of the **`julian`** calendar. In the **`standard`** calendar, 1582-10-15 0:0:0 is exactly 1 day later than 1582-10-4 0:0:0 and the intervening dates are undefined. Therefore it is recommended that date/times in the range from (and including) 1582-10-5 0:0:0 until (but excluding) 1582-10-15 0:0:0 should not be used as reference in **`units`**, and that a time coordinate variable should not include any date/times in this range, because their interpretation is unclear. It is also recommended that a reference date/time before the discontinuity should not be used for date/times after the discontinuity, and vice-versa. -**`proleptic_gregorian`**:: A Gregorian calendar extended to dates before 1582-10-15. That is, a year is a leap year if either (i) it is divisible by 4 but not by 100 or (ii) it is divisible by 400. +**`proleptic_gregorian`**:: A calendar with the Gregorian rules for leap-years extended to dates before 1582-10-15. All dates consistent with these rules are allowed, both before and after 1582-10-15 0:0:0. -**`noleap`** or **`365_day`**:: Gregorian calendar without leap years, i.e., all years are 365 days long. +**`julian`**:: Julian calendar, in which a year is a leap year if it is divisible by 4, even if it is also divisible by 100. -**`all_leap`** or **`366_day`**:: Gregorian calendar with every year being a leap year, i.e., all years are 366 days long. +**`noleap`** or **`365_day`**:: A calendar with no leap years, i.e., all years are 365 days long. -**`360_day`**:: All years are 360 days divided into 30 day months. +**`all_leap`** or **`366_day`**:: A calendar in which every year is a leap year, i.e., all years are 366 days long. -**`julian`**:: Julian calendar. +**`360_day`**:: A calendar in which all years are 360 days, and divided into 30 day months. **`none`**:: No calendar. -The **`calendar`** attribute may be set to **`none`** in climate experiments that simulate a fixed time of year. The time of year is indicated by the date in the reference time of the **`units`** attribute. The time coordinate that might apply in a perpetual July experiment are given in the following example. +The **`calendar`** attribute may be set to **`none`** in climate experiments that simulate a fixed time of year. The time of year is indicated by the date in the reference time of the **`units`** attribute. The time coordinates that might apply in a perpetual July experiment are given in the following example. [[perpetual-time-axis-ex]] [caption="Example 4.5. "] diff --git a/ch07.adoc b/ch07.adoc index 9b7c76dd..d39986a9 100644 --- a/ch07.adoc +++ b/ch07.adoc @@ -418,7 +418,7 @@ Climatological statistics may be derived from corresponding portions of the annu Climatological variables have a climatological time axis. Like an ordinary time axis, a climatological time axis may have a dimension of unity (for example, a variable containing the January average temperatures for 1961-1990), but often it will have several elements (for example, a climatological time axis with a dimension of 12 for the climatological average temperatures in each month for 1961-1990, a dimension of 3 for the January mean temperatures for the three decades 1961-1970, 1971-1980, 1981-1990, or a dimension of 24 for the hours of an average day). Intervals of climatological time are conceptually different from ordinary time intervals; a given interval of climatological time represents a set of subintervals which are not necessarily contiguous. To indicate this difference, a climatological time coordinate variable does not have a **`bounds`** attribute. Instead, it has a **`climatology`** attribute, which names a variable with dimensions (n,2), n being the dimension of the climatological time axis. Using the units and calendar of the time coordinate variable, element (i,0) of the climatology variable specifies the beginning of the first subinterval and element (i,1) the end of the last subinterval used to evaluate the climatological statistics with index i in the time dimension. The time coordinates should be values that are representative of the climatological time intervals, such that an application which does not recognise climatological time will nonetheless be able to make a reasonable interpretation. -The COARDS standard offers limited support for climatological time. For compatibility with COARDS, time coordinates should also be recognised as climatological if they have a **`units`** attribute of time-units relative to midnight on 1 January in year 0 i.e. **`since 0-1-1`** in udunits syntax, and provided they refer to the real-world calendar. We do not recommend this convention because (a) it does not provide any information about the intervals used to compute the climatology, and (b) there is no standard for how dates since year 1 will be encoded with units having a reference time in year 0, since this year does not exist; consequently there may be inconsistencies among software packages in the interpretation of the time coordinates. Year 0 may be a valid year in non-real-world calendars, and therefore cannot be used to signal climatological time in such cases. +For compatibility with the COARDS standard, a climatological time coordinate in the default **`standard`** and **`julian`** calendars may be indicated by setting the date/time reference string in the time coordinate's **`units`** attribute to midnight on 1 January in year 0 (i.e., **`since 0-1-1`**). This convention is deprecated because it does not provide any information about the intervals used to compute the climatology, and there may be inconsistencies among software packages in the interpretation of the time coordinates with a reference time of year 0. Use of year 0 for this purpose is impossible in all other calendars, because year 0 is a valid year. A climatological axis may use different statistical methods to represent variation among years, within years and within days. For example, the average January temperature in a climatology is obtained by averaging both within years and over years. This is different from the average January-maximum temperature and the maximum January-average temperature. For the former, we first calculate the maximum temperature in each January, then average these maxima; for the latter, we first calculate the average temperature in each January, then find the largest one. As usual, the statistical operations are recorded in the **`cell_methods`** attribute, which may have two or three entries for the climatological time dimension. diff --git a/conformance.adoc b/conformance.adoc index c2abe04e..966cdfe5 100644 --- a/conformance.adoc +++ b/conformance.adoc @@ -316,11 +316,8 @@ equal to or greater than 60. *Recommendations:* -* The use of a reference time in the year 0 to indicate climatological -time is deprecated. This restriction only applies to the real-world -calendar as used by the udunits package. -* Units of **`year`** and **`month`** and any equivalent units should be used with -caution. +* The use of time coordinates in year 0 and reference date/times in year 0 to indicate climatological time is deprecated. +* Units of **`year`** and **`month`** and any equivalent units should be used with caution. [[section-14]] @@ -329,11 +326,9 @@ caution. *Requirements:* -* The attributes **`calendar`**, **`month_lengths`**, **`leap_year`**, and **`leap_month`** may -only be attached to time coordinate variables. -* The standardized values of the calendar attribute are **`gregorian`**, -**`standard`**, **`proleptic_gregorian`**, **`noleap`**, **`365_day`**, **`all_leap`**, **`366_day`**, -**`360_day`**, **`julian`**, and **`none`** (case insensitive). If the **`calendar`** attribute +* The attributes **`calendar`**, **`month_lengths`**, **`leap_year`**, and **`leap_month`** may only be attached to time coordinate variables. +* The standardized values (case insensitive) of the **`calendar`** attribute are **`standard`**, **`gregorian`** (deprecated), **`proleptic_gregorian`**, **`noleap`**, **`365_day`**, **`all_leap`**, **`366_day`**, +**`360_day`**, **`julian`**, and **`none`**. If the **`calendar`** attribute is given a non-standard value, then the attribute **`month_lengths`** is required, along with **`leap_year`** and **`leap_month`** as appropriate. * The type of the **`month_lengths`** attribute must be an integer array of @@ -344,6 +339,8 @@ scalars. *Recommendations:* +* A time coordinate variable should have a **`calendar`** attribute. +* The value **`standard`** should be used instead of **`gregorian`** in the **`calendar`** attribute. * The attribute **`leap_month`** should not appear unless the attribute **`leap_year`** is present. * The time coordinate should not cross the date 1582-10-15 when the diff --git a/history.adoc b/history.adoc index ea377238..42ff32d3 100644 --- a/history.adoc +++ b/history.adoc @@ -281,3 +281,7 @@ node coordinate variables to be one of the dimensions of the data variable. .24 May 2021 . link:$$https://github.com/cf-convention/cf-conventions/issues/314$$[Issue #314]: Correction to the definition of "ocean sigma over z coordinate" in Appendix D + +.2 July 2021 +. link:$$https://github.com/cf-convention/cf-conventions/issues/298$$[Issue #298]: Interpretation of negative years in the units attribute +. link:$$https://github.com/cf-convention/cf-conventions/issues/319$$[Issue #319]: Restrict "gregorian" label to only dates in the Gregorian calendar