recommendation of standard_name or long_name

[JonathanGregory]

In commenting on #501 (now closed as completed), @martinjuckes drew attention to an apparent inconsistency. Section 3.2 says, "it is highly recommended that either [the long_name attribute] or the standard_name attribute defined in the next section be provided for all data variables and variables containing coordinate data." Both attributes are optional, and CF isn't recommending the standard_name more than the long_name in this sentence. That is consistent with Section 1.4 (the Overview), where it says

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.

This lack of preference between long_name and standard_name seems to be contradicted by two other sentences. In the preamble of Section 4, we have

Four types of coordinates receive special treatment by these conventions: latitude, longitude, vertical, and time. We continue to support the special role that the units and positive attributes play in the COARDS convention to identify coordinate type. We extend COARDS by providing explicit definitions of dimensionless vertical coordinates. 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.

and Section 1.4 says

To achieve the goal of being able to spatially locate all data values, this convention includes the definitions of common dimensionless vertical coordinates in Appendix D, Parametric Vertical Coordinates. These definitions provide a mapping between the dimensionless coordinate values and dimensional values that can be uniquely located with respect to a point on the earth's surface. 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.

The final sentence in each of those pieces of text apparently says that the standard_name is highly recommended, implying it's preferred to the long_name. My reading of those sentences, in context, is that "highly recommended" actually refers to the use of the convention of Section 4.3.3, "Parametric Vertical Coordinate", which involves standard_name and formula_terms, for those kinds of vertical coordinate where it's relevant. It is not saying that standard_name is "highly recommended" (disregarding long_name) in all cases, so it's not inconsistent with Section 3.

What do you think, @martinjuckes and anyone else? Is my reading correct?

In any case, I think we ought to clarify this. If my understanding is correct, this is a defect in the wording (a lack of clarity), which we can repair. If there is truly an inconsistency, sorting it out might be a change to the convention. Therefore I've labelled this as an enhancement for the moment, but we could change it to a defect, depending on what you think.

[JonathanGregory]

On second thoughts, I realise that since it's not clear what to do, it would make sense to discuss it first in our new forum. Therefore I've opened a discussion of this question. Please comment there, rather than here.

[JonathanGregory]

In the discussion, @davidhassell, @martinjuckes and I have agreed that this is a defect. I am therefore changing the label of this issue from enhancement to defect.

I propose the changes described below to remedy the defect. Note also that I am proposing to update the text to replace "dimensionless" with "parametric (usually dimensionless)". That reflects the revision we made quite a long time ago in Section 4.3.3.

In Section 1.4, replace this text

To achieve the goal of being able to spatially locate all data values, this convention includes the definitions of common dimensionless vertical coordinates in Appendix D, Parametric Vertical Coordinates. These definitions provide a mapping between the dimensionless coordinate values and dimensional values that can be uniquely located with respect to a point on the earth’s surface. 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.

with

In particular a model may output data on the parametric (usually dimensionless) vertical coordinate used in its mathematical formulation. To achieve the goal of being able to spatially locate all data values, this convention provides a mapping, via the standard_name and formula_terms attributes of a parametric vertical coordinate variable, between its values and dimensional vertical coordinate values that can be uniquely located with respect to a point on the earth's surface (Section 4.3.3, Parametric Vertical Coordinate; Appendix D, Parametric Vertical Coordinates).

This removes the "recommendation" which causes the confusion. That recommendation is not necessary here, because it's included in Section 1.5 on "Relationship to the COARDS Conventions". The relevant sentence currently reads

But we recommend that the standard_name and formula_terms attributes be used to identify the appropriate definition of the dimensionless vertical coordinate (see Section 4.3.2, "Dimensionless Vertical Coordinate").

which should be updated to read

But we recommend that the standard_name and formula_terms attributes be used to identify the appropriate definition of the dimensionless vertical coordinate (see Section 4.3.3, "Parametric Vertical Coordinate").

In the preamble to Section 4, replace this text:

We extend COARDS by providing explicit definitions of dimensionless vertical coordinates. 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.

with

As an extension to COARDS, we strongly recommend that a parametric (usually dimensionless) vertical coordinate variable should be associated via standard_name and formula_terms attributes with its explicit definition, which provides a mapping between its values and dimensional vertical coordinate values that can be uniquely located with respect to a point on the earth's surface.

Here, I have retained the recommendation, but it's rephrased to make clear that it refers to the use of the convention for parametric vertical coordinates, rather than to the standard_name attribute specifically.

I have prepared pull request 520 to implement the above. In the PR, I have also corrected a couple of minor punctuation faults in Sect 1.

Since this is a defect issue, the change will be accepted in the absence of any objection in three weeks, on 20th May.

[davidhassell]

Thanks, @JonathanGregory. PR #520 looks fine to me (I've made one minor suggestion)

[JonathanGregory]

Thanks, @davidhassell; I've committed your change to the PR.