Merge branch 'main' into aggregation3

Author: davidhassell

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,8 +1,6 @@
 See issue #XXX for discussion of these changes.
 
 # Release checklist
-- [ ] Authors updated in `cf-conventions.adoc`? Add in two places: on line 3 and under `.Additional Authors` in `About the authors`.
-- [ ] Next version in `cf-conventions.adoc` up to date? Versioning inspired by [SemVer](https://semver.org).
 - [ ] `history.adoc` up to date?
 - [ ] Conformance document up to date?
 

appa.adoc

@@ -114,7 +114,7 @@ Identifies the roles of mesh topology and location index set variables (see <<ap
 | S
 | C
 | <<climatological-statistics>>
-| Identifies a climatology variable.
+| Identifies a climatology boundary variable.
 
 | **`comment`**
 | S

cf-conventions.adoc

@@ -1,6 +1,6 @@
 include::version.adoc[]
 = NetCDF Climate and Forecast (CF) Metadata Conventions
-Brian{nbsp}Eaton; Jonathan{nbsp}Gregory; Bob{nbsp}Drach; Karl{nbsp}Taylor; Steve{nbsp}Hankin; John{nbsp}Caron; Rich{nbsp}Signell; Phil{nbsp}Bentley; Greg{nbsp}Rappa; Heinke{nbsp}Höck; Alison{nbsp}Pamment; Martin{nbsp}Juckes; Martin{nbsp}Raspaud; Randy{nbsp}Horne; Jon{nbsp}Blower; Timothy{nbsp}Whiteaker; David{nbsp}Blodgett; Charlie{nbsp}Zender; Daniel{nbsp}Lee; David{nbsp}Hassell; Alan{nbsp}D.{nbsp}Snow; Tobias{nbsp}Kölling; Dave{nbsp}Allured; Aleksandar{nbsp}Jelenak; Anders{nbsp}Meier{nbsp}Soerensen; Lucile{nbsp}Gaultier; Sylvain{nbsp}Herlédan; Fernando{nbsp}Manzano; Lars{nbsp}Bärring; Christopher{nbsp}Barker; Sadie{nbsp}Bartholomew; Bryan{nbsp}Lawrence; Neil{nbsp}Massey
+Brian{nbsp}Eaton; Jonathan{nbsp}Gregory; Bob{nbsp}Drach; Karl{nbsp}Taylor; Steve{nbsp}Hankin; John{nbsp}Caron; Rich{nbsp}Signell; Phil{nbsp}Bentley; Greg{nbsp}Rappa; Heinke{nbsp}Höck; Alison{nbsp}Pamment; Martin{nbsp}Juckes; Martin{nbsp}Raspaud; Randy{nbsp}Horne; Jon{nbsp}Blower; Timothy{nbsp}Whiteaker; David{nbsp}Blodgett; Charlie{nbsp}Zender; Daniel{nbsp}Lee; David{nbsp}Hassell; Alan{nbsp}D.{nbsp}Snow; Tobias{nbsp}Kölling; Dave{nbsp}Allured; Aleksandar{nbsp}Jelenak; Anders{nbsp}Meier{nbsp}Soerensen; Lucile{nbsp}Gaultier; Sylvain{nbsp}Herlédan; Fernando{nbsp}Manzano; Lars{nbsp}Bärring; Christopher{nbsp}Barker; Sadie{nbsp}Bartholomew; Thomas Lavergne; Bryan{nbsp}Lawrence; Neil{nbsp}Massey
 :revnumber: {current-version}
 :revdate: {docprodtime}
 :doctype: book
@@ -72,6 +72,7 @@ include::toc-extra.adoc[]
 * Lars Bärring, SMHI
 * Christopher Barker, NOAA
 * Sadie Bartholomew, NCAS and University of Reading
+* Thomas Lavergne, MET Norway
 * Bryan Lawrence, NCAS and University of Reading
 * Neil Massey, NCAS and STFC
 

ch01.adoc

@@ -109,7 +109,9 @@ The word "apex" refers to position of this group at the vertex of the tree of gr
 
 longitude dimension:: A dimension of a netCDF variable that has an associated longitude coordinate variable.
 
-most rapidly varying dimension:: The dimension of a multidimensional variable for which elements are adjacent in storage. When netCDF is represented in CDL, the most rapidly varying dimension is the last one e.g. **`x`** in **`float data(z,y,x)`**. C and Python NumPy use the same order as C, also called "column-major order", but Fortran uses the opposite convention, also called "row-major order", so that when netCDF variables are accessed in Fortran the most rapidly varying dimension is the first one.
+most rapidly varying dimension:: The dimension of a multidimensional variable for which elements are adjacent in storage.
+When a netCDF dataset is represented in CDL, the most rapidly varying dimension is the last one e.g. **`x`** in **`float data(z,y,x)`**.
+C and Python NumPy use the same order as CDL, also called "row-major order", while Fortran and R use the alternative order, also called "column-major order", so that when netCDF variables are accessed in Fortran or R the most rapidly varying dimension is the first one.
 
 multidimensional coordinate variable:: An auxiliary coordinate variable that is multidimensional.
 

ch03.adoc

@@ -11,7 +11,7 @@ But since it is an optional attribute, applications that implement these standar
 [[units, Section 3.1, "Units"]]
 === Units
 
-The **`units`** attribute is required for all variables that represent dimensional quantities (except for boundary variables defined in <<cell-boundaries>> and climatology variables defined in <<climatological-statistics>>).
+The **`units`** attribute is required for all variables that represent dimensional quantities (except for boundary variables defined in <<cell-boundaries>> and climatology boundary variables defined in <<climatological-statistics>>).
 The **`units`** attribute is permitted but not required for dimensionless quantities (see <<dimensionless-units>>).
 
 The value of the **`units`** attribute is a string that can be recognized by the UDUNITS package <<UDUNITS>>, with the exceptions that are given in <<dimensionless-units>> and <<units-multiples>>.

ch04.adoc

@@ -237,24 +237,25 @@ All the alternatives have exactly the same meaning in UDUNITS.
 For compatibility with other software, CF strongly recommends that `since` should be used.
 
 The reference datetime string (appearing after the identifier **`since`**) is required.
-It may include date alone, or date and time, or date, time and time zone offset.
-Its format is __y__-__m__-__d__ [__H__:__M__:__S__ [__Z__]], where [...] indicates an optional element,
+It must include the date, which may optionally be followed by time or time zone offset or both. Its format is __y__-__m__-__d__ [__H__:__M__:__S__] [__Z__], where [...] indicates an optional element:
 
 * _y_ is year, _m_ month, _d_ day, _H_ hour and _M_ minute, which are all integers of one or more digits, and _y_ may be prefixed with a sign (but note that some CF calendars do not permit negative years; see <<calendar>>),
 
 * _S_ is second, which may be integer or floating point (see <<leap-seconds>> regarding __S__>59),
 
-* _Z_ is the time zone offset with respect to UTC.
+* _Z_ is the time zone offset.
 This is an interval of time, specified in one of the formats described below.
-Only numbers (digits, `+`, `-` and `:`) are allowed in _Z_, not time zone names or acronyms.
+Only numbers (digits, `+`, `-` and `:`) or the letter "Z" are allowed in _Z_, not time zone names or acronyms.
 
 The default time zone offset is zero.
 In a time zone with zero offset, time (approximately) equals mean solar time for 0 `degrees_east` of longitude.
 (Although this may be exact in a model, in reality the time with zero time zone offset differs by some seconds from mean solar time; see the discussion of UTC and leap seconds in <<calendar>>.)
 If both time and time zone offset are omitted the time is 00:00:00 (the beginning of the day i.e. midnight at 0 `degrees_east`).
-Thus, **`units = "days since 1990-1-1"`** means the same as **`units = "days since 1990-1-1 0:0:0"`**.
+Thus, **`units = "days since 1990-1-1"`** means the same as **`units = "days since 1990-1-1 00:00:00"`**.
 
-The time zone offset _Z_ must be in one of the following four formats, any of which may be prefixed with a sign:
+The time zone offset _Z_ must be in one of the following five formats, where numeric hours may optionally be prefixed with a `+` or `-` sign:
+
+** The letter `Z` indicating zero offset, sometimes referred to as "Zulu Time".
 
 ** _H_, the hour alone, of one or two digits e.g. **`-6`**, **`2`**, **`+11`**, which is sufficient for many time zones.
 
@@ -264,6 +265,10 @@ The time zone offset _Z_ must be in one of the following four formats, any of wh
 
 ** three digits, of which the first is the hour (0--9) e.g. **`530`**.
 
+If the time zone offset is the letter `Z` or begins with a sign, the space before it may be omitted.
+
+While the default (of omitting the _Z_ component) is an offset of zero, we suggest that a zero offset be specified to avoid any confusion where omitting it might be misunderstood as indicating local time.
+
 For example, **`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 a time zone where the datetime is six hours behind the default.
 Subtracting the time zone offset from a given datetime converts it to the equivalent datetime with zero time zone offset e.g. **`1989-12-31 18:00:00 -6`** identifies the same instant as **`1990-1-1 0:0:0`**.
 
@@ -400,7 +405,7 @@ When these calendars are being be used for timelines _with_ leap seconds (i.e. c
 * A datetime in the excluded range must not be used as a reference datetime e.g. **`seconds since 2016-12-31 23:59:60`** is not a permitted value for **`units`**.
 
 * The coordinate value does not count any leap seconds which occurred between the reference datetime and the datetime represented by the coordinate.
-  For instance, 60 **`seconds after 23:59:00`** always means 00:00:00 on the next day, even if there is a leap second at 23:59:60, which makes the actual interval 61 seconds between 23:59:00 and 00:00:00 on the next day.
+  For instance, 60 **`seconds after 23:59:00`** always means 0:0:0 on the next day, even if there is a leap second at 23:59:60, which makes the actual interval 61 seconds between 23:59:00 and 0:0:0 on the next day.
 
 Because of the last point, the difference between two coordinate values with the same **`units`** string does not exactly equal the length of the interval between instants they represent if there were any leap seconds between them.
 This discrepancy can happen in cases 2, 3 and 4 of the **`standard`**, **`proleptic_gregorian`**, and **`julian`** calendars.

ch05.adoc

@@ -192,6 +192,10 @@ A __grid mapping variable__ provides this information.
 If no __grid mapping variable__ is provided and the coordinate variables for a horizontal grid are not longitude and latitude, then it is required that the latitude and longitude coordinates are supplied via the `coordinates` attribute. 
 Such coordinates may be provided in addition to the provision of a __grid mapping variable__, but that is not required.
 
+When a data variable is representative of cells of non-zero size, and the coordinate variables are not longitude and latitude, __bounds__ variables should be provided for vertices of the cell boundaries in the horizontal coordinates of the grid (see  <<cell-boundaries>>).
+The __grid mapping variable__ provides then the information to convert bounds in latitude and longitude coordinates, and it is optional for the dataset to provide these.
+If no __grid mapping variable__ is provided, then the cell extents in latitude and longitude coordinate system should be provided (see <<cell-boundaries>> and especially Example 7.2 for the common case of four-sided cells).
+
 A grid mapping variable provides the description of the mapping via a collection of attached attributes.
 It is of arbitrary type since it contains no data.
 Its purpose is to act as a container for the attributes that define the mapping.

ch07.adoc

@@ -70,7 +70,7 @@ dimensions:
 variables:
   float time(time);
     time:standard_name = "time";
-    time:units = "days since 2024-11-8 09:00:00";
+    time:units = "days since 2024-11-8 09:00:00Z";
     time:bounds = "time_bnds";
   float time_bnds(time,nv);
 ----
@@ -330,7 +330,7 @@ variables:
     ppn:cell_methods = "time: sum";
   double time(time);
     time:long_name = "time";
-    time:units = "h since 1998-4-19 6:0:0";
+    time:units = "h since 1998-4-19 6:0:0 Z";
     time:bounds = "time_bnds";
   double time_bnds(time,nv);
 data:
@@ -400,7 +400,7 @@ variables:
     TS_var:units="K2";
     TS_var:cell_methods="time: variance (interval: 1 hr comment: sampled instantaneously)";
   float time(time);
-    time:units="days since 1990-01-01 00:00:00";
+    time:units="days since 1990-01-01 00:00:00 Z";
     time:bounds="time_bnds";
   float time_bnds(time,nv);
 data:
@@ -520,9 +520,10 @@ In addition the two concepts may be used at once, for instance to indicate not A
 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.
+To indicate this difference, a climatological time coordinate variable does not have a **`bounds`** attribute, instead it has a **`climatology`** attribute which names the climatological boundary variable.
+The climatological boundary variable must have dimensions (n,2), n being the dimension of the climatological time axis.
+The rules and recommendations for attributes of the climatological boundary variable are the same as those for boundary variables in general, as described in <<cell-boundaries>>.
+Using the units and calendar of the time coordinate variable, element (i,0) of the climatology boundary 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.
 
 For compatibility with the COARDS standard, a climatological time coordinate in the default **`standard`** and **`julian`** calendars may be indicated by setting the datetime reference string in the time coordinate's **`units`** attribute to midnight at 0 `degrees_east` on 1 January in year 0 (i.e., **`since 0-1-1`**).
@@ -679,8 +680,7 @@ It now applies to April from a 1961-1990 climatology.
 variables:
   float temperature(time,lat,lon);
     temperature:long_name="surface air temperature";
-    temperature:cell_methods="time: mean within days ",
-      "time: mean over days time: mean over years";
+    temperature:cell_methods="time: mean within days time: mean over days time: mean over years";
     temperature:units="K";
   double time(time);
     time:climatology="climatology_bounds";

conformance.adoc

@@ -180,7 +180,7 @@ References can be absolute, relative or with no path, in which case, the variabl
 
 *Requirements:*
 
-* The **`units`** attribute is required for all variables that represent dimensional quantities (except for boundary variables defined in https://cfconventions.org/cf-conventions/cf-conventions.html#cell-boundaries[section 7.1] and climatology variables defined in https://cfconventions.org/cf-conventions/cf-conventions.html#climatological-statistics[section 7.4]).
+* The **`units`** attribute is required for all variables that represent dimensional quantities (except for boundary variables defined in https://cfconventions.org/cf-conventions/cf-conventions.html#cell-boundaries[section 7.1] and climatology boundary variables defined in https://cfconventions.org/cf-conventions/cf-conventions.html#climatological-statistics[section 7.4]).
 * The type of the **`units`** attribute is a string that must be recognizable by the UDUNITS package.
 Exceptions are the units **`level`**, **`layer`**, and **`sigma_level`**.
 * Dimensionless units for volume fractions defined by UDUNITS (**`ppv`**, **`ppmv`**, **`ppbv`**, **`pptv`**, **`ppqv`**) are not allowed in the **`units`** attribute of any variable which also has a **`standard_name`** attribute.
@@ -500,10 +500,10 @@ The _value_ must be a valid number and the _unit_ a string that is recognizable
 * The **`climatology`** attribute may only be attached to a time coordinate variable.
 * The type of the **`climatology`** attribute is a string whose value is a single variable name.
 The specified variable must exist in the file.
-* A climatology variable must have the same dimension as its associated time coordinate variable, and have a trailing dimension (CDL order) of size 2.
-* A climatology variable must be a numeric data type.
-* If a climatology variable has **`units`**, **`standard_name`**, or **`calendar`** attributes, they must agree with those of its associated variable.
-* A climatology variable must not have **`_FillValue`** or **`missing_value`** attributes.
+* A climatology boundary variable must have the same dimension as its associated time coordinate variable, and have a trailing dimension (CDL order) of size 2.
+* A climatology boundary variable must be a numeric data type.
+* If a climatology boundary variable has **`units`**, **`standard_name`**, or **`calendar`** attributes, they must agree with those of its associated variable.
+* A climatology boundary variable must not have **`_FillValue`** or **`missing_value`** attributes.
 
 [[geometries]]
 === 7.5 Geometries

history.adoc

@@ -5,6 +5,12 @@
 [[revhistory, Revision History]]
 == Revision History
 
+=== Version 1.13-draft
+
+* {issues}590[Issue #590]: Clarify that grid_mapping can also be used for converting spatial bounds
+* {issues}593[Issue #593]: Clarify that rules for attributes of boundary variables (including BI and BO) also apply for attributes of climatological boundary variables
+* {issues}583[Issue #583]: Correct "most rapidly varying dimension" in terminology section.
+* {issues}584[Issue #584]: Allow `Z` as time-zone offset, with a couple of examples, and allow time-zone offset with date alone, both being consistent with UDUNITS syntax.
 * {issues}508[Issue #508]: Introduce aggregation variables
 
 === Version 1.12 (04 December 2024)