Merge pull request #636 from JonathanGregory/issue620

Clarify the prohibition of numerical factors and offsets in `units`

Author: JonathanGregory

ch03.adoc

@@ -26,6 +26,8 @@ The COARDS conventions prohibit the unit `degrees` altogether, but this unit is
 The unit `degrees` is also allowed on coordinate variables such as the latitude and longitude coordinates of a transformed grid.
 In this case the coordinate values are not true latitudes and longitudes, which must always be identified using the more specific forms of `degrees` as described in <<latitude-coordinate>> and <<longitude-coordinate>>.
 
+See <<units-multiples>> concerning the use of scale factors and offsets for units and data.
+
 
 [[dimensionless-units, Section 3.1.1, "Dimensionless units"]]
 ==== Dimensionless units
@@ -45,10 +47,6 @@ Information describing a dimensionless physical quantity itself (e.g.
 As an exception, to maintain backwards compatibility with COARDS, the text strings `level`, `layer`, and `sigma_level` are allowed in the **`units`** attribute, in order to indicate dimensionless vertical coordinates.
 This use of **`units`** is not compatible with UDUNITS, and is deprecated by these conventions because conventions for more precisely identifying dimensionless vertical coordinates are available (see <<dimensionless-vertical-coordinate>>).
 
-The UDUNITS syntax that allows scale factors and offsets to be applied to a unit is not supported by these conventions, 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>>.
-
 
 [[temperature-units, Section 3.1.2, "Temperature units"]]
 ==== Temperature units
@@ -113,11 +111,14 @@ For instance, when temperature is on-scale, a value in `kg degree_C m-2` can be
 ==== Scale factors and offsets
 
 UDUNITS recognises the <<SI>> prefixes shown in <<table-supported-units, Table 3.1>> for decimal multiples and submultiples of units, and allows them to be applied to non-SI units as well.
-UDUNITS offers a syntax for indicating arbitrary scale factors and offsets to be applied to a unit.
-(Note that this is different from the scale factors and offsets used for converting between **`units`**, as discussed for temperature in <<temperature-units>>.)
-This UDUNITS syntax for arbitrary transformation of **`units`** is not supported by the CF conventions, except for the case of specifying reference time (<<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 offers a syntax of its own for indicating arbitrary scale factors and offsets to be applied to a unit of measure named in the **`units`** attribute.
+(Note that this facility is not related to the scale factors and offsets used for converting between different units of measure, as discussed for temperature in <<temperature-units>>.)
+The UDUNITS syntax allows dimensionless numbers to appear in **`units`**, as multiplicative factors before the name of the unit and as additive offsets to the named unit (following `@` or various keywords).
+This UDUNITS syntax for arbitrary transformation of **`units`** must not be used with the CF conventions, except for offsets following **`since`** for specifying reference time (<<time-coordinate>>.
+
+The application of any scale factors or offsets to the data values, without altering the **`units`**, should be indicated by the **`scale_factor`** and **`add_offset`** attributes.
+Use of these attributes for data compression, which is their most important application, is discussed in detail in <<packed-data>>.
 
 [[table-supported-units]]
 .Prefixes for decimal multiples and submultiples of units

conformance.adoc

@@ -183,6 +183,8 @@ References can be absolute, relative or with no path, in which case, the variabl
 * 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`**.
+* The **`units`** string must not contain literal numbers (integer or real) as factors or offsets to a named unit of measure.
+An equivalent statement, using the syntax and terms of the link:$$https://docs.unidata.ucar.edu/udunits/current/udunits2lib.html#Grammar$$[UDUNITS Unit Grammar], is that **`INT`** or **`REAL`** are not allowed in a **`units`** string that contains **`ID`**, except for the specification of a reference time in the units of time coordinates.
 * 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.
 * If present, the **`units_metadata`** attribute must have one of these values: `temperature: on_scale`, `temperature: difference`, `temperature: unknown`, `leap_seconds: none`, `leap_seconds: utc`, or `leap_seconds: unknown`.
 * 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.

history.adoc

@@ -7,8 +7,9 @@
 
 === Version 1.14-draft
 
+* {issues}610[Issue #610]: Clarify the CF prohibition of the UDUNITS syntax for scale factors and additive offsets to units
 * {issues}635[Issue #635]: Revision of section 4.3 to improve its clarity
-* {issues}623[Issue #623]: Consistently refer to "CF conventions" and use of impersonal from.
+* {issues}623[Issue #623]: Consistently refer to "CF conventions" and use of impersonal form
 
 === Version 1.13 (17 December 2025)