UDUNITS clarifications from workshop housekeeping 2022

ch01.adoc

@@ -148,7 +148,7 @@ Each variable in a netCDF file has an associated description which is provided b
 The **`units`**, and **`long_name`** attributes are defined in the NUG and the **`standard_name`** attribute is defined in this document.
 
 The **`units`** attribute is required for all variables that represent dimensional quantities (except for boundary variables defined in <<cell-boundaries>>.
-The values of the **`units`** attributes are character strings that are recognized by UNIDATA's Udunits package <<UDUNITS>>, (with exceptions allowed as discussed in <<units>>).
+The values of the **`units`** attributes are character strings that are recognized by UNIDATA's UDUNITS package <<UDUNITS>>, (with exceptions allowed as discussed in <<units>>).
 
 The **`long_name`** and **`standard_name`** attributes are used to describe the content of each variable.
 For backwards compatibility with COARDS neither is required, but use of at least one of them is strongly recommended.
@@ -168,7 +168,7 @@ Once the variables containing coordinate data are identified, further convention
 Latitude, longitude, and time coordinates are identified solely by the value of their **`units`** attribute.
 Vertical coordinates with units of pressure may also be identified by the **`units`** attribute.
 Other vertical coordinates must use the attribute **`positive`** which determines whether the direction of increasing coordinate value is up or down.
-Because identification of a coordinate type by its units involves the use of an external software package <<UDUNITS>>, we provide the optional attribute **`axis`** for a direct identification of coordinates that correspond to latitude, longitude, vertical, or time axes.
+Because identification of a coordinate type by its units involves the use of an external package <<UDUNITS>>, we provide the optional attribute **`axis`** for a direct identification of coordinates that correspond to latitude, longitude, vertical, or time axes.
 
 Latitude, longitude, and time are defined by internationally recognized standards, and hence, identifying the coordinates of these types is sufficient to locate data values uniquely with respect to time and a point on the earth's surface.
 On the other hand identifying the vertical coordinate is not necessarily sufficient to locate a data value vertically with respect to the earth's surface.

ch03.adoc

@@ -14,8 +14,7 @@ But since it is an optional attribute, applications that implement these standar
 === 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 value of the **`units`** attribute is a string that can be recognized by UNIDATA's Udunits package <<UDUNITS>>, with a few exceptions that are given below.
-The link:$$http://www.unidata.ucar.edu/software/udunits/$$[Udunits package] includes a file `udunits.dat`, which lists its supported unit names.
+The value of the **`units`** attribute is a string that can be recognized by the UDUNITS package <<UDUNITS>>, with a few exceptions that are given below.
 Note that case is significant in the **`units`** strings.
 
 The COARDS convention prohibits the unit `degrees` altogether, but this unit is not forbidden by the CF convention because it may in fact be appropriate for a variable containing, say, solar zenith angle.
@@ -25,20 +24,20 @@ In this case the coordinate values are not true latitudes and longitudes which m
 Units are not required for dimensionless quantities.
 A variable with no units attribute is assumed to be dimensionless.
 However, a units attribute specifying a dimensionless unit may optionally be included.
-The Udunits package defines a few dimensionless units, such as `percent`, but is lacking commonly used units such as ppm (parts per million).
-This convention does not support the addition of new dimensionless units that are not udunits compatible.
+The UDUNITS package defines a few dimensionless units, such as `percent`, `ppm` (parts per million), and others.
+This convention does not support the addition of new dimensionless units that are not UDUNITS compatible.
 The conforming unit for quantities that represent fractions, or parts of a whole, is "1".
 The conforming unit for parts per million is "1e-6".
 Descriptive information about dimensionless quantities, such as sea-ice concentration, cloud fraction, probability, etc., should be given in the **`long_name`** or **`standard_name`** attributes (see below) rather than the **`units`**.
 
 The units `level`, `layer`, and `sigma_level` are allowed for dimensionless vertical coordinates to maintain backwards compatibility with COARDS.
-These units are not compatible with Udunits and are deprecated by this standard because conventions for more precisely identifying dimensionless vertical coordinates are introduced (see <<dimensionless-vertical-coordinate>>).
+These units are not compatible with UDUNITS and are deprecated by this standard because conventions for more precisely identifying dimensionless vertical coordinates are introduced (see <<dimensionless-vertical-coordinate>>).
 
-The Udunits syntax that allows scale factors and offsets to be applied to a unit is not supported by this standard.
+The UDUNITS syntax that allows scale factors and offsets to be applied to a unit is not supported by this standard, except for case of specifying reference time, see section <<time-coordinate>>.
 The application of any scale factors or offsets to data should be indicated by the **`scale_factor`** and **`add_offset`** attributes.
 Use of these attributes for data packing, which is their most important application, is discussed in detail in <<packed-data>>.
 
-Udunits recognizes the following prefixes and their abbreviations.
+UDUNITS recognizes the following prefixes and their abbreviations.
 [[table-supported-units]]
 .Supported Units
 [options="header",caption="Table 3.1. "]

ch04.adoc

@@ -11,7 +11,7 @@ We extend COARDS by providing explicit definitions of dimensionless vertical coo
 The definitions are associated with a coordinate variable via the **`standard_name`** and **`formula_terms`** attributes.
 For backwards compatibility with COARDS use of these attributes is not required, but is strongly recommended.
 
-Because identification of a coordinate type by its units is complicated by requiring the use of an external software package <<UDUNITS>>, we provide two optional methods that yield a direct identification.
+Because identification of a coordinate type by its units is complicated by requiring the use of an external package <<UDUNITS>>, we provide two optional methods that yield a direct identification.
 The attribute **`axis`** may be attached to a coordinate variable and given one of the values **`X`**, **`Y`**, **`Z`** or **`T`** which stand for a longitude, latitude, vertical, or time axis respectively.
 Alternatively the **`standard_name`** attribute may be used for direct identification.
 But note that these optional attributes are in addition to the required COARDS metadata.
@@ -28,15 +28,11 @@ The locations of the boundaries between cells are indicated by bounds variables
 If bounds are not provided, an application might reasonably assume the gridpoints to be at the centers of the cells, but we do not require that in this standard.
 
 
-
-
 [[latitude-coordinate, Section 4.1, "Latitude Coordinate"]]
 === Latitude Coordinate
 
 Variables representing latitude must always explicitly include the **`units`** attribute; there is no default value.
-The **`units`** attribute will be a string formatted as per the link:$$http://www.unidata.ucar.edu/software/udunits/$$[`udunits.dat`] file.
-The recommended unit of latitude is **`degrees_north`**.
-Also acceptable are **`degree_north`**, **`degree_N`**, **`degrees_N`**, **`degreeN`**, and **`degreesN`**.
+The recommended value of the **`units`** attribute is the string **`degrees_north`**. Also accepted are **`degree_north`**, **`degree_N`**, **`degrees_N`**, **`degreeN`**, and **`degreesN`**.
 
 [[latitude-axis-ex]]
 [caption="Example 4.1. "]
@@ -55,10 +51,11 @@ float lat(lat) ;
 
 ====
 
-Application writers should note that the Udunits package does not recognize the directionality implied by the "north" part of the unit specification.
+Application writers should note that the UDUNITS package does not recognize the directionality implied by the "north" part of the unit specification.
 It only recognizes its size, i.e., 1 degree is defined to be pi/180 radians.
 Hence, determination that a coordinate is a latitude type should be done via a string match between the given unit and one of the acceptable forms of **`degrees_north`**.
 
+
 Optionally, the latitude type may be indicated additionally by providing the **`standard_name`** attribute with the value **`latitude`**, and/or the **`axis`** attribute with the value **`Y`**.
 
 Coordinates of latitude with respect to a rotated pole should be given units of **`degrees`**, not **`degrees_north`** or equivalents, because applications which use the units to identify axes would have no means of distinguishing such an axis from real latitude, and might draw incorrect coastlines, for instance.
@@ -70,9 +67,9 @@ Coordinates of latitude with respect to a rotated pole should be given units of
 === Longitude Coordinate
 
 Variables representing longitude must always explicitly include the **`units`** attribute; there is no default value.
-The units **`attribute`** will be a string formatted as per the link:$$http://www.unidata.ucar.edu/software/udunits/$$[`udunits.dat`] file.
-The recommended unit of longitude is **`degrees_east`**.
-Also acceptable are **`degree_east`**, **`degree_E`**, **`degrees_E`**, **`degreeE`**, and **`degreesE`**.
+The recommended value of the **`units`** attribute is the string **`degrees_east`**. Also accepted are **`degree_east`**, **`degree_E`**, **`degrees_E`**, **`degreeE`**, and **`degreesE`**.
+
+
 
 [[longitude-axis-ex]]
 [caption="Example 4.2. "]
@@ -91,7 +88,7 @@ float lon(lon) ;
 
 ====
 
-Application writers should note that the Udunits package has limited recognition of the directionality implied by the "east" part of the unit specification.
+Application writers should note that the UDUNITS package has limited recognition of the directionality implied by the "east" part of the unit specification.
 It defines **`degrees_east`** to be pi/180 radians, and hence equivalent to **`degrees_north`**.
 We recommend the determination that a coordinate is a longitude type should be done via a string match between the given unit and one of the acceptable forms of **`degrees_east`**.
 
@@ -109,7 +106,7 @@ Variables representing dimensional height or depth axes must always explicitly i
 
 The direction of positive (i.e., the direction in which the coordinate values are increasing), whether up or down, cannot in all cases be inferred from the units.
 The direction of positive is useful for applications displaying the data.
-For this reason the attribute **`positive`** as defined in the COARDS standard is required if the vertical axis units are not a valid unit of pressure (a determination which can be made using the udunits routine, utScan) -- otherwise its inclusion is optional.
+For this reason the attribute **`positive`** as defined in the COARDS standard is required if the vertical axis units are not a valid unit of pressure (as determined by the UDUNITS package <<UDUNITS>>) -- otherwise its inclusion is optional.
 The **`positive`** attribute may have the value **`up`** or **`down`** (case insensitive).
 This attribute may be applied to either coordinate variables or auxiliary coordinate variables that contain vertical coordinate data.
 
@@ -143,14 +140,15 @@ Recommendations:  The **`positive`** attribute should be consistent with the sig
 
 ==== Dimensional Vertical Coordinate
 
-The **`units`** attribute for dimensional coordinates will be a string formatted as per the link:$$http://www.unidata.ucar.edu/software/udunits/$$[`udunits.dat`] file.
-The acceptable units for vertical (depth or height) coordinate variables are:
 
-* units of pressure as listed in the file `udunits.dat`.
+Variables representing dimensional vertical coordinates for or height must always explicitly include the  **`units`** attribute.
+The acceptable units for a vertical (depth or height) coordinate variable must a UDUNITS <<UDUNITS>> representation of one of the following:
+
+* units of pressure.
 For vertical axes the most commonly used of these include **`bar`**, **`millibar`**, **`decibar`**, **`atmosphere (atm)`**, **`pascal (Pa)`**, and **`hPa`**.
-* units of length as listed in the file udunits.dat.
+* units of length.
 For vertical axes the most commonly used of these include **`meter (metre, m)`**, and **`kilometer (km)`**.
-* other units listed in the file udunits.dat that may under certain circumstances reference vertical position such as units of density or temperature.
+* other units that may under certain circumstances reference vertical position such as units of density or temperature.
 
 Plural forms are also acceptable.
 
@@ -162,7 +160,7 @@ Plural forms are also acceptable.
 
 The **`units`** attribute is not required for dimensionless coordinates.
 For backwards compatibility with COARDS we continue to allow the **`units`** attribute to take one of the values: **`level`**, **`layer`**, or **`sigma_level`**.
-These values are not recognized by the Udunits package, and are considered a deprecated feature in the CF standard.
+These values are not recognized by the UDUNITS package, and are considered a deprecated feature in the CF standard.
 
 
 [[parametric-vertical-coordinate, Section 4.3.3, "Parametric Vertical Coordinate"]]
@@ -221,14 +219,14 @@ 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.
+Variables representing reference 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` 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 (indicating hours) or three or four digits (indicating hours and minutes)."
 
-The acceptable units for time are listed in the UDUNITS database.
+The acceptable units for time are given by the UDUNITS package <<UDUNITS>>.
 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.
 
@@ -256,8 +254,7 @@ double time(time) ;
 
 ====
 
-A time coordinate is identifiable from its units string alone.
-The Udunits routines **`utScan()`** and **`utIsTime()`** can be used to make this determination.
+A reference time coordinate is identifiable from its units string alone.
 
 Optionally, the time coordinate may be indicated additionally by providing the **`standard_name`** attribute with an appropriate value, and/or the **`axis`** attribute with the value **`T`**.
 

ch07.adoc

@@ -341,7 +341,7 @@ The horizontal coordinate variables to which "**`area`**" refers are in this cas
 To indicate more precisely how the cell method was applied, extra information may be included in parentheses () after the identification of the method.
 This information includes standardized and non-standardized parts.
 Currently the only standardized information is to provide the typical interval between the original data values to which the method was applied, in the situation where the present data values are statistically representative of original data values which had a finer spacing.
-The syntax is (**`interval`**: __value unit__), where __value__ is a numerical value and __unit__ is a string that can be recognized by UNIDATA's Udunits package <<UDUNITS>>.
+The syntax is (**`interval`**: __value unit__), where __value__ is a numerical value and __unit__ is a string that can be recognized by UNIDATA's UDUNITS package <<UDUNITS>>.
 The __unit__ will usually be dimensionally equivalent to the unit of the corresponding dimension, but this is not required (which allows, for example, the interval for a standard deviation calculated from points evenly spaced in distance along a parallel to be reported in units of length even if the zonal coordinate of the cells is given in degrees).
 Recording the original interval is particularly important for standard deviations.
 For example, the standard deviation of daily values could be indicated by **`cell_methods="time: standard_deviation (interval: 1 day)"`** and of annual values by **`cell_methods="time: standard_deviation (interval: 1 year)"`**.

conformance.adoc

@@ -140,7 +140,7 @@ Exceptions are boundary and climatology variables.
 *Requirements:*
 
 * The **`units`** attribute is required for all variables that represent dimensional quantities (except for boundary variables defined in http://cfconventions.org/cf-conventions/cf-conventions.html#cell-boundaries[section 7.1] and climatology variables defined in http://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.
+* 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`**.
 * The **`units`** of a variable that specifies a **`standard_name`** must be physically equivalent to the canonical units given in the standard name table, as modified by the **`standard_name`** modifier, if there is one, according to Appendix C, and then modified by all the methods listed in order by the **`cell_methods`** attribute, if one is present, according to Appendix E.
 
@@ -422,7 +422,7 @@ An exception is a climatological time dimension.
 The _remainder_ text is not standardized.
 If no **`interval`** clauses are present, the entire comment is therefore not standardized.
 There may be zero **`interval`** clauses, one **`interval`** clause, or exactly as many **`interval`** clauses as there are **`dims`** to which the method applies.
-The _value_ must be a valid number and the _unit_ a string that is recognizable by the udunits package.
+The _value_ must be a valid number and the _unit_ a string that is recognizable by the UDUNITS package.
 
 *Recommendations:*
 

history.adoc

@@ -72,7 +72,7 @@
 === Version 1.7 (7 August 2017)
 
 * Updated use of WKT-CRS syntax.
-* Trivial updates to links for COARDS and Udunits in the bibliography.
+* Trivial updates to links for COARDS and UDUNITS in the bibliography.
 * Updated the links and references to NUG (The NetCDF User Guide), to refer to the current version.
 * A few formatting tweaks.
 * {tickets}140.html[Ticket #140]: Added 3 paragraphs and an example to Chapter 7, Section 7.1.