scalar auxiliary coordinate clarifications

[taylor13]

This proposal is to clear up some apparent inconsistencies in the description of allowable attributes for auxiliary coordinate variables.

At the beginning of section 6.2 of the conventions, it states:

"In some situations a dimension may have alternative sets of coordinates values. Since there can only be one coordinate variable for the dimension (the variable with the same name as the dimension), any alternative sets of values have to be stored in auxiliary coordinate variables. For such alternative coordinate variables, there are no mandatory attributes, but they may have any of the attributes allowed for coordinate variables."

But in paragraph 4 of Chapter 5 it states:

"The axis attribute is not allowed for auxiliary coordinate variables."

in contradiction to the statement in section 6.2.

Furthermore, according to the definition of a scalar coordinate variable (section 1.2), it is supposed to be "functionally equivalent to either a size one coordinate variable or a size one auxiliary coordinate variable." The only way for this to be possible is for both types of scalar coordinates to include the same attributes. Currently the CF document forbids use of the axis attribute in conjunction with auxiliary coordinate variables, but allows its use for coordinate variables. To make the two consistent, the following change to paragraph 4 of Chapter 5 is proposed:

Replace "The axis attribute is not allowed for auxiliary coordinate variables. Auxiliary coordinate variables ..." by "If an axis attribute is attached to an auxiliary coordinate variable, it can be used by applications in the same way the axis attribute is used in conjunction with coordinate variables. Note that if this attribute is missing, it may still be possible to determine if a particular dimension should be associated with the auxiliary coordinate variable. For example, auxiliary coordinate variables ..."

Note that in Example 5.2, the axis attribute "X" is associated with xc, and if the above change were adopted, the axis attribute could also appear in conjunction with the auxiliary coordinate variable "lon". Would this cause problems?

Also, some folks might misinterpret the paragraph at the end of section 2.4, which states that "The advantage of using a coordinate variable is that all its attributes can be used to describe the single-valued quantity, including boundaries." to mean that this is an "advantage over a a size one auxiliary coordinate variable", when in fact it means an "advantage over *omitting* the scalar variable". I therefore propose rewriting this sentence to read:

"The use of a scalar coordinate variable is encouraged, when appropriate, because the coordinate attributes (including axis attribute and the cell bounds) can be defined to more fully describe the quantity of interest."

[eaton]

Note that in Example 5.2, the axis attribute "X" is associated with xc, and if the above change were adopted, the axis attribute could also appear in conjunction with the auxiliary coordinate variable "lon". Would this cause problems?

It could cause a problem if the information is inconsistent. But the axis attribute is optional, so I would expect an application to give the units attribute precedence (it's the required attribute for identifying longitude coordinates).

Also, some folks might misinterpret the paragraph at the end of section 2.4, which states that "The advantage of using a coordinate variable is that all its attributes can be used to describe the single-valued quantity, including boundaries." to mean that this is an "advantage over a a size one auxiliary coordinate variable", when in fact it means an "advantage over *omitting* the scalar variable". I therefore propose rewriting this sentence to read:

"The use of a scalar coordinate variable is encouraged, when appropriate, because the coordinate attributes (including axis attribute and the cell bounds) can be defined to more fully describe the quantity of interest."

The reason we didn't "encourage" the use of scalar coordinate variables is that they aren't recognized by the COARDS convention.

I think what we need to clarify is that the use of "coordinate variables" is not the only way to obtain the advantage of having associated metadata which conveys the coordinate type and bounds. It is also possible to use auxiliary coordinate variables, which includes scalar coordinate variables. Note that the advantage being referred to is over expressing the coordinate data via an attribute. I would suggest updating the sentence in question with:

The advantage of using either a coordinate variable or an auxiliary coordinate variable is that all its attributes can be used to describe the single-valued quantity, including boundaries.

[jonathan]

I agree with Brian about this:

I think what we need to clarify is that the use of "coordinate variables" is not the only way to obtain the advantage of having associated metadata which conveys the coordinate type and bounds. It is also possible to use auxiliary coordinate variables, which includes scalar coordinate variables. Note that the advantage being referred to is over expressing the coordinate data via an attribute. I would suggest updating the sentence in question with:

The advantage of using either a coordinate variable or an auxiliary coordinate variable is that all its attributes can be used to describe the single-valued quantity, including boundaries.

That is what I meant in my earlier email. The text as it stands is incorrect; it is talking about the advantage of using "coordinates" rather than attributes. I think Brian's proposal (above) for changing 2.4 will avoid the misinterpretation.

I agree with Karl that the axis attribute should be allowed for scalar coordinate variables, which are formally auxiliary coordinate variables. Steve Hankin has also argued that the axis attribute should generally be allowed for auxiliary coordinate variables. Up to now I have opposed that because to me "axis" means a dimension of the data variable, so I expect this attribute only to be attached to a 1D (Unidata-definition) coordinate variable. My interpretation appears to be a minority view. If "axis" is understood as not necessarily referring to the dimensions of the data variable but to the dimensions of physical space, I agree that the axis attribute could be applied to auxiliary coordinate variables.

But we should ask, what is this attribute for? If the idea is that it tells the data analyst or the data-reading program about which are the horizontal and vertical coordinates, I think it would be confusing if it is ambiguous. So my proposal for the paragraph under discussion in section 5 would be

... Note that it is permissible, but optional, to list coordinate variables as well as auxiliary coordinate variables in the coordinates attribute. [THEN PARAGRAPH BREAK]

If an axis attribute is attached to an auxiliary coordinate variable, it can be used by applications in the same way the axis attribute attached to a coordinate variable is used. However, it is not permissible for a data variable to have both a coordinate variable and an auxiliary coordinate variable, or more than one of either type of variable, having an axis attribute with any given value e.g. there must be no more than one axis attribute for "X" for any data variable. Note that if the axis attribute is not specified for an auxiliary coordinate variable, it may still be possible to determine if it is a spatiotemporal dimension from its own units or standard_name, or from the units and standard_name of the coordinate variable corresponding to its dimensions (see Chapter 4, Coordinate Types ). For instance, auxiliary coordinate variables which lie on the horizontal surface can be identified as such by their dimensions being horizontal. Horizontal dimensions are those whose coordinate variables have an axis attribute of X or Y, or a units attribute indicating latitude and longitude.

Note that if we cannot easily agree the required changes we should redesignate this ticket as a change to the convention. Defect tickets are only intended to make uncontroversial corrections.

Happy holidays

Jonathan

[eaton]

I agree with Jonathan's concerns about adding the axis attribute to auxiliary coordinate variables, and think that the explicit restrictions on their use (e.g, there must be no more than one axis attribute for "X" for any data variable) make sense.

The axis attribute was intended as a convenience to allow applications to avoid using the units and/or the positive attributes to identify the lat,lon,lev,time coordinate types, or as a hint to graphics applications for plotting spatial/temporal axes. I personally think that axis should be deprecated in favor of the standard_name which is a much more powerful and extensible method of identifying coordinate types.

[stevehankin]

Two independent comments:

1) General lesson to be learned: The use of scalar coordinate variables (as a simpler syntax than a formal netCDF coordinate variable of dimension 1) is documented in CF and is already in use. As a result I will not argue for deprecating it. But I see a lesson to be learned about standards committee process from this feature. AFAIK the use of scalar coordinate variables has added no expressive power to CF. It has added a small convenience factor for the writers of data, that is offset by a larger inconvenience factor for the code that reads the data and the documentation that makes CF intelligible to humans. The lesson is for standards committee members to feel less inhibited about saying "no" to suggestions for new features. "No" should be the default answer based on the recognition that new features almost always add complexity. (I cannot see any reason to "encourage" the use of scalar coordinate variables.)

2) The "axis" attribute: Jonathan asked: "we should ask, what is this attribute for?" Strongly agree. The above paragraph argues, that if an attribute contributes no expressive power it should be deprecated (what Brian suggests for "axis"). Example 5.2 documents one need for an "axis=x" attribute: where we have two alternative grid mappings for the same data, and the units of local measure ("meters") would leave the orientation of a coordinate ambiguous. Are there others?

There is also a use case of files whose goal is *only* to communicate coordinate systems -- files that contain no dependent variables. (My group creates such files -- e.g. to contain climatological axes.) What does CF provide to ensure that a variable containing independent coordinates self-expresses the semantic meaning, I am a coordinate variable? Proper netCDF coordinate variables (dimname = varname) succeed at this task. But for, say, a 2-dimensional coordinate variable of longitudes the 'axis' attribute seems to be the only tool that CF provides to express these semantics. (Units of "degrees_east" and standard_name of "longitude" do not guarantee that the variable contains independent coordinates; it may on occasion contain a derived result.)

Another possible use case: "climate and forecast" data are not exclusively on geophysical coordinate grids. Consider for example an analysis of ocean chlorophyll as a function of temperature and salinity. Temp(Temp) is a valid CF coordinate variable AFAIK. If the data provider wanted to communicate the convention that "temperature" should be the horizontal axis of a temp-sal plot, would an axis='x' attribute on the Temp variable be appropriate?

[jonathan]

Since there were no further objections and some support, I believe this ticket can be accepted as a correction for a defect, amending a paragraph in sect 5 as follows:

... Note that it is permissible, but optional, to list coordinate variables as well as auxiliary coordinate variables in the coordinates attribute. [THEN PARAGRAPH BREAK]

If an axis attribute is attached to an auxiliary coordinate variable, it can be used by applications in the same way the axis attribute attached to a coordinate variable is used. However, it is not permissible for a data variable to have both a coordinate variable and an auxiliary coordinate variable, or more than one of either type of variable, having an axis attribute with any given value e.g. there must be no more than one axis attribute for "X" for any data variable. Note that if the axis attribute is not specified for an auxiliary coordinate variable, it may still be possible to determine if it is a spatiotemporal dimension from its own units or standard_name, or from the units and standard_name of the coordinate variable corresponding to its dimensions (see Chapter 4, Coordinate Types ). For instance, auxiliary coordinate variables which lie on the horizontal surface can be identified as such by their dimensions being horizontal. Horizontal dimensions are those whose coordinate variables have an axis attribute of X or Y, or a units attribute indicating latitude and longitude.

Jonathan

[painter1]

This was incorporated into CF Conventions version 1.6, but I had neglected to close the ticket. That's done now.