Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 10 additions & 9 deletions ch03.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions conformance.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 2 additions & 1 deletion history.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
Loading