revision of 4.3 to improve clarity

[JonathanGregory]

In Discussion 462 @ilaflott asked about a possible inconsistency in 4.3. @taylor13 explained how the text is to be understood, and that it's not self-contradictory, but commented that it is poorly organised. I agree that it's not well-organised and therefore could be confusing; also, it's rather repetitive. I therefore propose to reword it as follows, where strikethrough means deletion and bold means new text, although some of the new text is existing text rearranged.

Is this version clear?

4.3 Vertical (Height or Depth) Coordinate

Variables representing dimensional height or depth axes must always explicitly include the units attribute; there is no default value. A vertical coordinate will be identifiable by: vertical coordinates must have either

• the presence of a positive attribute with a value of up or down (case insensitive), which respectively mean that increasingly positive coordinate values indicate higher locations i.e. further from the centre of the Earth (positive="up") or lower locations (positive="down"); or
• a units attribute containing units of pressure (as determined by UDUNITS). If the units attribute value is a valid pressure unit the default value of the positive attribute is down.

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 conventions is required if the vertical axis units are not a valid unit of pressure (as determined by the UDUNITS package <>) -- otherwise its inclusion is optional.
The positive attribute may have the value up or down (case insensitive).

The positive attribute may be applied both to either coordinate variables or and to auxiliary coordinate variables that contain vertical coordinate data.

For example, if an oceanographic netCDF file encodes the depth of the surface as 0 and the depth of 1000 meters as 1000 then the axis would use attributes as follows:

axis_name:units = "meters" ; 
axis_name:positive = "down" ; 	

If, on the other hand, the depth of 1000 meters were represented as -1000 then the value of the positive attribute would have been up.

Optionally, the vertical type may be indicated additionally by providing the standard_name attribute with an appropriate value, and/or the axis attribute with the value Z.
If both positive and standard_name are provided, it is recommended that they should be consistent.
For instance, if a depth of 1000 metres is represented by -1000 and positive is up, it would be inconsistent to give the standard_name as depth, whose definition (vertical distance below the surface) implies positive down.
If an application detects such an inconsistency, the user should be warned, and the positive attribute should be used to determine the sign convention.

4.3.1 Dimensional Vertical Coordinate

Variables representing dimensional vertical coordinates (i.e. not dimensionless numbers, but having a unit of measure) for depth or height must always explicitly include the units attribute; there is no default value.
The acceptable units for a vertical (depth or height) coordinate variable must be valid according to UDUNITS representation of one of; acceptable possibilities include 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;
  For vertical axes the most commonly used of these include meter (metre, m), and kilometer (km).
• other units that may under certain circumstances reference vertical position such as units of density or temperature.

Plural forms are also acceptable. @JonathanGregory: True, but it's always true, since UDUNITS allows it, so it seems odd to say it here.

4.3.2 Dimensionless Vertical Coordinate

The units attribute is not required for dimensionless coordinates.
For backwards compatibility with COARDS the units attribute for dimensionless vertical coordinates may 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 conventions.

[davidhassell]

Dear Jonathan,

I think your new version is a good improvement! One minor question ... it says "The units for a vertical coordinate variable must be valid according to UDUNITS; acceptable possibilities include the following:" ... you mention later that plurals are a given, so can it also be a given that units has to be valid UDUNITS? What do you think?

Cheers,
David

[JonathanGregory]

Good point, thanks. It's not strictly necessary, I agree. Yet maybe it's useful, especially as we allow some non-UDUNITS for dimensionless coordinates. We could make it less prominent, though. How about this shorter version:

Variables representing dimensional vertical coordinates (i.e. not dimensionless numbers, but having a unit of measure) must always explicitly include units consistent with UDUNITS; there is no default value. Acceptable units include the following:

[davidhassell]

OK - I see that the following paragraph on non-UDUNITS for some dimensionless coordinates makes it meaningful to mention UDUNITS here. Your new version is good.

[JonathanGregory]

I have made a PR #637 to implement these revisions, updated following the above remark from @davidhassell. See here for the rendered modified document. Unless anyone raises concerns, the change will be accepted in three weeks, on 30th March.

[pvanlaake]

The changes in the PR are fine by me but I think that we should revisit the use of the term "dimension" in the context of units of measure. Where the text speaks of "dimensional coordinates", what is meant is a coordinate whose values represent a physical quantity having a unit of measure. "Dimensionless" ought to be "unitless". This issue obviously transcends the current PR, as changing this would also involve changing section 3.1 but I thought I would flag it here.

This use of "dimensional" in the context of UOM is also a potential source of confusion given the other uses of the term "dimension" in the conventions.

[larsbarring]

With respect to units of measure the term "dimension" is well established, see SI Brochure, section "2.3.3
Dimensions of quantities". And units that have zero exponent on the seven base dimensions (i.e. not related to any of the SI base units) are referred to as "dimensionless". A well known pain point is that units (and quantities / quantity kinds) that are dimensionless make up a disparate group (e.g. counts, angles, proportions, ....), something that is frequently discussed in the literature. But this another matter ...

[larsbarring]

@JonathanGregory I have just added a minor nitpick suggestion to the PR (but maybe my Swenglish is playing games). Irrespective of whether it is accepted or not, it must not interfere with the countdown period.

[pvanlaake]

With respect to units of measure the term "dimension" is well established

My point is not the accuracy of what is written but the multiple contexts in which "dimension" is used in the conventions. If that is of no concern, then this is fine (first parts slightly adapted from the terminology section, final phrase my addition):

"A time coordinate variable is a one-dimensional variable with the same name as its dimension e.g., time(time), and whose dimension is time".

Is it desirable to leave it all to context and the correct interpretation thereof, or can we find a better way to express it?

[JonathanGregory]

@JonathanGregory I have just added a minor nitpick suggestion to the PR (but maybe my Swenglish is playing games). Irrespective of whether it is accepted or not, it must not interfere with the countdown period.

Thanks, Lars. I accepted your suggestion and then changed it again. It currently reads, "the positive attribute, which must take one of the values up or down (case insensitive), meaning respectively that increasingly positive coordinate values indicate higher locations (i.e. further from the centre of the Earth, positive="up"), or lower locations (positive="down")". Is that clear?

[larsbarring]

As I wrote, my Swenglish is probably tripping me up here, but what I was aiming at was the construction "... positive attribute ..... positive coordinates ....". Obviously, the style carries weight, and in particular here. But I easily accept what you suggest.

[larsbarring]

Patrick, I agree with

... multiple contexts in which "dimension" is used in the conventions.

And I think that "dimension" is not the only term having this problem in CF. It has indeed come up a couple of time, and I do not know what to do about it (but I am not happy replacing "dimensionless" with "unitless").

[JonathanGregory]

I don't know what to do about the ambiguity of "dimension" either. Both uses are well-established. I think we have to spell out which one we mean wherever it could be ambiguous. In the sentence, "A coordinate variable is a one-dimensional variable with the same name as its dimension e.g., time(time)," isn't it obvious from the example at the end that "dimension" here has its mathematical/computational meaning? If it would help at all, we could add "dimension" to the terminology section and point out it has two meanings - but that's not our fault!