diff --git a/ch03.adoc b/ch03.adoc index 8ba1a0f1..5b1dbc34 100644 --- a/ch03.adoc +++ b/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 <> and <>. +See <> 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 <>). -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 <>. -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 <>. - [[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 <> prefixes shown in <> 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 <>.) -This UDUNITS syntax for arbitrary transformation of **`units`** is not supported by the CF conventions, except for the case of specifying reference time (<>). -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 <>. + +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 <>.) +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 (<>. + +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 <>. [[table-supported-units]] .Prefixes for decimal multiples and submultiples of units diff --git a/conformance.adoc b/conformance.adoc index 90c12fb1..c5423933 100644 --- a/conformance.adoc +++ b/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. +In terms of the link:$$https://docs.unidata.ucar.edu/udunits/current/udunits2lib.html#Grammar$$[UDUNITS Unit Grammar], CF does not allow **`INT`** or **`REAL`** in a string containing **`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. diff --git a/history.adoc b/history.adoc index 8f0cd44c..a7de24ca 100644 --- a/history.adoc +++ b/history.adoc @@ -7,7 +7,8 @@ === Version 1.14-draft -* {issues}623[Issue #623]: Consistently refer to "CF conventions" and use of impersonal from. +* {issues}610[Issue #610]: Clarify the CF prohibition of the UDUNITS syntax for scale factors and additive offsets to units +* {issues}623[Issue #623]: Consistently refer to "CF conventions" and use of impersonal form === Version 1.13 (17 December 2025)