Supplement the definitions of dimensionless vertical coordinates

[jonathan]

1 Title

Supplement the definitions of dimensionless vertical coordinates

2 Moderator

Rich Signell

3 Purposes

1. Rename dimensionless coordinates as parameterized coordinates because one of them (hybrid height) is not dimensionless, and dimensionlessness is not their defining characteristic.

2. Define a new attribute to supply the standard_name of the dimensional coordinates computed by the formula. This may depend on the standard_name of one or more of the terms. Spell out the possibilities for each case in Appendix D and correct some errors.

3. Point out that some vertical coordinates refer to a vertical datum surface which is described by grid_mapping information.

4 Status quo and benefits

At the moment it is difficult for a data user to know exactly what the computed vertical coordinate is. For example, does the ocean sigma coordinate give you a height with respect to a geopotential surface or a reference ellipsoid, and precisely what is that datum e.g. NAVD88? These changes are intended to make it easier.

5 Detailed proposal

Insert a new section heading "4.3.3 Parameterized Vertical Coordinate" after the sentence "The units attribute is not required ..." in section 4.3.2. Thus, the remainder of that section, about formula terms etc., will become a new section under the new heading.

Amend the existing first paragraph of this new section from the existing text:

For dimensionless vertical coordinates we extend the COARDS standard by making use of the standard_name attribute to associate a coordinate with its definition from Appendix D, Dimensionless Vertical Coordinates. The definition provides a mapping between the dimensionless coordinate values and dimensional values that can positively and uniquely indicate the location of the data. A new attribute, formula_terms, is used to associate terms in the definitions with variables in a netCDF file. To maintain backwards compatibility with COARDS the use of these attributes is not required, but is strongly recommended.

to read as follows:

In some cases dimensional vertical coordinates are parameterized as a function of horizontal as well as vertical location and therefore cannot be stored in the one-dimensional vertical coordinate variable, which in most of these cases is dimensionless. The standard_name of the vertical coordinate variable can be used to find the definition of the associated dimensional vertical coordinate in Appendix D, Parameterized Vertical Coordinates. The definition provides a mapping between the parameterized coordinate values and dimensional values that can positively and uniquely indicate the location of the data. The formula_terms attribute can be used to associate terms in the definitions with variables in a netCDF file, and the computed_standard_name attribute can be used to supply the standard_name of the dimensional vertical coordinate values computed according to the definition. To maintain backwards compatibility with COARDS the use of these attributes is not required, but is strongly recommended. Some of the definitions may be supplemented with information stored in the grid_mapping variable about the datum used as a vertical reference (e.g. geoid, other geopotential datum or reference ellipsoid; see Section 5.6, Horizontal Coordinate Reference Systems, Grid Mappings, and Projections and Appendix F, Grid Mappings).

In this section, in the sentence after Example 4.3, change "Appendix D, Dimensionless Vertical Coordinates" to "Appendix D, Parameterized Vertical Coordinates".

In section 5.6, replace the existing paragraph

When the coordinate variables for a horizontal grid are longitude and latitude, a grid mapping variable with grid_mapping_name of latitude_longitude may be used to specify the ellipsoid and prime meridian.

with

The grid_mapping variable may identify datums (such as the reference ellipsoid, the geoid or the prime meridian) for horizontal or vertical coordinates. Therefore a grid mapping variable may be needed when the coordinate variables for a horizontal grid are longitude and latitude. The grid_mapping_name of latitude_longitude should be used in this case.

In Appendix A, between the entries for compress and Conventions, insert an entry for computed_standard_name, Type S, Use C, Link "Section 4.3.3, Parameterized Vertical Coordinate", Description "Indicates the standard name, from the standard name table, of the parameterized dimensional vertical coordinate values computed according to the formula in the definition."

In Appendix A, change the Link for formula_terms to "Section 4.3.3, Parameterized Vertical Coordinate".

Rename Appendix D as "Parameterized vertical coordinates".

Change the first sentence of Appendix D from "The definitions given here allow an application to compute dimensional coordinate values from the dimensionless ones and associated variables." to "The definitions given here allow an application to compute dimensional coordinate values from the parameterized (usually dimensionless) ones and associated variables."

In the first paragraph of Appendix D, change "where term is a keyword" to "where term is a case-insensitive keyword".

Append the following as a third paragraph in the preamble of Appendix D:

The variables containing the terms may optionally have standard_name attributes, with values as indicated in this Appendix. The standard_name of the dimensional coordinate values which are computed by the formula may optionally be specified by the computed_standard_name attribute of the vertical coordinate variable, as indicated in this Appendix. A computed_standard_name is uniquely implied by the formula in some cases, while in others it depends on the standard_name of one or more of the terms, with which it must be consistent.

In the following, it will be noticed that some formula terms do not have defined standard names at the moment. Of course, names could be defined, but it is not essential because their purpose is identifiable from the formula_terms attribute. However, standard_names have been proposed below for constants in the formula which don't depend on level e.g. reference air pressure.

Append the following paragraph to the definition of "Atmosphere natural log pressure coordinate":

The standard_name of p0 is reference_air_pressure_for_atmosphere_vertical_coordinate. The computed_standard_name is air_pressure.

Append the following paragraph to the definition of "Atmosphere sigma coordinate":

The standard_name of ptop is air_pressure_at_top_of_atmosphere_model, and of ps is surface_air_pressure. The computed_standard_name is air_pressure.

Append the following paragraph to the definition of "Atmosphere hybrid sigma pressure coordinate":

The standard_name of p0 is reference_air_pressure_for_atmosphere_vertical_coordinate, and of ps is surface_air_pressure. The computed_standard_name is air_pressure. No standard_name has been defined for a, b or ap.

In the definition of "Atmosphere hybrid height coordinate", change "z(n,k,j,i) is the height above the geoid (approximately mean sea level) at gridpoint (k,j,i) and time (n) , orog(n,j,i) is the height of the surface above the geoid" to "z(n,k,j,i) is the height above the datum (e.g. the geoid, which is approximately mean sea level) at gridpoint (k,j,i) and time (n) , orog(n,j,i) is the height of the surface above the datum", and replace the final paragraph "There is no dimensionless ..." with the following.

The standard_name of orog may be surface_altitude (i.e. above the geoid) or surface_height_above_geopotential_datum. The computed_standard_name is altitude or height_above_geopotential_datum in these cases respectively. No standard_name has been defined for b. There is no dimensionless coordinate because a, which has the standard_name of atmosphere_hybrid_height_coordinate, is the best choice for a level-dependent but geographically constant coordinate.

In the definition of "Atmosphere smooth level vertical (SLEVE) coordinate", change "z(n,k,j,i) is the height above the geoid (approximately mean sea level) at gridpoint (k,j,i) and time (n), ztop is the height of the top of the model" to "z(n,k,j,i) is the height above the datum (e.g. the geoid, which is approximately mean sea level) at gridpoint (k,j,i) and time (n), ztop is the height of the top of the model above the datum", change "the large and small parts of the topography" to "the large-scale and small-scale components of the topography, and a, b1 and b2 are all functions of the dimensionless SLEVE coordinate" (for the sake of clarification), delete the sentence "The hybrid height coordinate for level k is defined as a(k)*ztop" (which appears to be in the wrong section) and append the following paragraph:

The standard_name of ztop may be altitude_at_top_of_atmosphere_model (i.e. above the geoid) or height_above_geopotential_datum_at_top_of_atmosphere_model. The computed_standard_name is altitude or height_above_geopotential_datum in these cases respectively. No standard_name has been defined for b1, zsurf1, b2 or zsurf2.

In the definition of "Ocean sigma coordinate", replace "z(n,k,j,i) is height, positive upwards, relative to ocean datum (e.g. mean sea level) at gridpoint (n,k,j,i), eta(n,j,i) is the height of the ocean surface, positive upwards, relative to ocean datum at gridpoint (n,j,i)" with "z(n,k,j,i) is height (positive upwards) relative to the datum (e.g. mean sea level) at gridpoint (n,k,j,i), eta(n,j,i) is the height of the sea surface (positive upwards) relative to the datum at gridpoint (n,j,i)", replace "depth(j,i) is the distance from ocean datum to sea floor (positive value) at horizontal gridpoint (j,i)" with "depth(j,i) is the distance (a positive value) from the datum to the sea floor at horizontal gridpoint (j,i)", and append the following paragraph:

The standard_names for eta and depth and the computed_standard_name must be one of the consistent sets shown in Table D.1.

In the definition of "Ocean s-coordinate", make the same replacements as for "Ocean sigma coordinate", and append the following paragraph:

The standard_names for eta and depth and the computed_standard_name must be one of the consistent sets shown in Table D.1. No standard_name has been defined for a, b or depth_c.

In the definition of "Ocean sigma over z coordinate", make the same replacements as for "Ocean sigma coordinate", after "Above depth depth_c there are nsigma layers" insert "and below this depth the levels are surfaces of constant height zlev (positive upwards) relative to the datum" (this definition is omitted in the current text), and append the following paragraph:

The standard_names for eta, depth, zlev and the computed_standard_name must be one of the consistent sets shown in Table D.1. No standard_name has been defined for depth_c or nsigma.

In the definition of "Ocean double sigma coordinate", make the same replacements as for "Ocean sigma coordinate" regarding z and depth (there is no eta in this case), and append the following paragraph:

The standard_name for depth and the computed_standard_name must be one of the consistent sets shown in Table D.1. No standard_name has been defined for z1, z2, a, href or k_c.

At the end of Appendix D, insert the following table:

Table D.1. Consistent sets of values for standard_name and computed_standard_name for the formula terms indicated.

computed_standard_name of altitude with standard_name of altitude for zlev, sea_surface_height_above_geoid for eta and sea_floor_depth_below_geoid for depth.

computed_standard_name of height_above_geopotential_datum with standard_name of height_above_geopotential_datum for zlev, sea_surface_height_above_geopotential_datum for eta and sea_floor_depth_below_geopotential_datum for depth.

computed_standard_name of height_above_reference_ellipsoid with standard_name of height_above_reference_ellipsoid for zlev, sea_surface_height_above_reference_ellipsoid for eta and sea_floor_depth_below_reference_ellipsoid for depth.

computed_standard_name of height_above_sea_level with standard_name of height_above_sea_level for zlev, sea_surface_height_above_sea_level for eta and sea_floor_depth_below_sea_level for depth.

In the conformance document, rename "4.3.2 Dimensionless Vertical Coordinates" to "4.3.3 Parameterized Vertical Coordinate", and append these new requirements:

• Where indicated by the appropriate definition in Appendix D, the standard_name attributes of variables named by the formula_terms attribute must be consistent with the standard_name of the coordinate variable it is attached to, according to the appropriate definition in Appendix D.
• The computed_standard_name attribute is only allowed on a coordinate variable which has a formula_terms attribute.
• The computed_standard_name attribute is a string whose value must be consistent with the standard_name of the coordinate variable it is attached to, and in some cases also with the standard_name attributes of variables named by the formula_terms attribute, according to the appropriate definition in Appendix D.

If this ticket is agreed, the following standard_names will be proposed:

air_pressure_at_top_of_atmosphere_model
altitude_at_top_of_atmosphere_model
reference_air_pressure_for_atmosphere_vertical_coordinate
height_above_geopotential_datum_at_top_of_atmosphere_model
height_above_geopotential_datum
surface_height_above_geopotential_datum
sea_surface_height_above_geopotential_datum
sea_floor_depth_below_geopotential_datum
sea_floor_depth_below_reference_ellipsoid
height_above_sea_level

Jonathan

[jonathan]

This is an addition to the detailed proposal above.

In the CDL of Example 4.3, insert this new attribute:

  lev:computed_standard_name = "air_pressure" ;

Modify the reference to "Appendix D, Dimensionless Vertical Coordinates" to read "Appendix D, Parameterized Vertical Coordinates". Append to the text about the example: "The computed_standard_name attribute indicates that the values in variable p would have a standard_name of air_pressure.

We could add examples of other kinds of parameterized vertical coordinate from Appendix D, perhaps illustrating the use of grid_mapping as well for the precise description of the datum. Which ones would be useful?

Jonathan

[rsignell]

Jonathan, Thanks for proposing this needed functionality for CF.

Do you think we could say "derived vertical coordinate", "computed vertical coordinate" or "calculated vertical coordinate" rather than "parameterized coordinate"?

Maybe it's just my modeling background, but "parameterized" sounds like we are estimating something that we don't fully know how to calculate.

[jonathan]

Dear Rich

Thanks for commenting on this ticket and 118.

Yes, I agree that "parameterized" has that drawback. By that word I meant "parametric" in the mathematical sense of "parametric formulae". Would "parametric" be any good? Your alternatives are good; of them, I think "computed" would be best, because it's consistent with my suggestion of computed_standard_name. I chose "computed" there because it was the best word I could think of for the output of the formula.

Cheers

Jonathan

[rsignell]

I prefer computed_vertical_coordinate over parametric_vertical_coordinate but both are better than parameterized_vertical_coordinate

[jonathan]

OK. Let's say Computed vertical coordinate rather than Parameterized vertical coordinate throughout the proposal, which is otherwise unaltered.

Following David's comment on ticket 118, I note here that, if this proposal is agreed, I will include in the related proposal to be made on the email list for standard names the suggestion that the definitions of the relevant height/depth coordinates should point out that grid_mapping can be used to specify the geoid, geopotential datum or reference ellipsoid which is used as the reference surface.

Jonathan

[davidhassell]

Replying to jonathan:

Dear Jonathan and Rich,

OK. Let's say Computed vertical coordinate rather than Parameterized vertical coordinate throughout the proposal, which is otherwise unaltered.

I'm confused now! The original proposal talks about parametric vertical coordinates (e.g. sigma) and computed vertical coordinates (e.g. air_pressure, which are non-parametric). I don't understand the most recent suggestion to call (e.g.) sigma a computed vertical coordinate. Apologies if I have misunderstood.

I like "parametric vertical coordinate" in place of "dimensionless vertical coordinate", but am less keen on the attribute computed_standard_name. I would prefer derived_standard_name or nonparametric_standard_name, but I wouldn't object to computed_standard_name if that was the general view point.

All the best,

David

[rsignell]

It's not sigma that is the computed vertical coordinate, but the z coordinate values computed from the formula terms. Since you use a formula to compute the vertical coordinate for all these dimensionless coordinates, it seemed natural to call them all "computed" although "derived" would be okay by me as well.

[jonathan]

Dear David and Rich

I didn't mean that "dimensionless vertical coordinates" are being renamed "computed vertical coordinates". I agree, that wouldn't be right. If we say "computed" or "derived" in renaming the section and appendix which deals with them, we shift the emphasis from the input (the usually dimensionless coordinate, like sigma) to the output (the computed dimensional coordinate, like air pressure). However, I didn't consider the text carefully enough. Sorry about that. We still do need a name for the input. It's not right to call it "dimensionless "(since they aren't all dimensionless), and Rich didn't like "parameterized". However, "parametric" seems acceptable. In that case, the section should read

In some cases dimensional vertical coordinates are a function of horizontal location as well as parameters which depend on vertical location, and therefore cannot be stored in the one-dimensional vertical coordinate variable, which is in most of these cases is dimensionless. The standard_name of the parametric (usually dimensionless) vertical coordinate variable can be used to find the definition of the associated dimensional vertical coordinate in Appendix D, Computed Vertical Coordinates. The definition provides a mapping between the parametric vertical coordinate values and dimensional values that can positively and uniquely indicate the location of the data. The formula_terms attribute can be used to associate terms in the definitions with variables in a netCDF file, and the computed_standard_name attribute can be used to supply the standard_name of the dimensional vertical coordinate values computed according to the definition. To maintain backwards compatibility with COARDS the use of these attributes is not required, but is strongly recommended. Some of the definitions may be supplemented with information stored in the grid_mapping variable about the datum used as a vertical reference (e.g. geoid, other geopotential datum or reference ellipsoid; see Section 5.6, Horizontal Coordinate Reference Systems, Grid Mappings, and Projections and Appendix F, Grid Mappings).

and the first sentence of Appendix D should change from "The definitions given here allow an application to compute dimensional coordinate values from the dimensionless ones and associated variables." to "The definitions given here allow an application to compute dimensional coordinate values from the parametric vertical coordinate values (usually dimensionless) and associated variables."

Does that help? Have I missed any other places where we should say "parametric"?

I don't mind whether we say "computed" or "derived", though I think "computed" is more obvious. If we say "derived", for consistency the attribute should be derived_standard_name, which would also be OK, I think.

What do you think?

Cheers

Jonathan

[davidhassell]

Dear Jonathan and Rich,

I'm all on board with this, except for the repeated use of the phrase "dimensional vertical coordinate values" to mean "computed vertical coordinate values". My objection is that, as you rightly point out, the parametric coordinate values may also be dimensional and so "dimensional" as a label for "computed" could be confusing.

Could they simply be called "computed coordinate values" (suggested changes in bold):

In some cases dimensional vertical coordinates are a function of horizontal location as well as parameters which depend on vertical location, and therefore cannot be stored in the one-dimensional vertical coordinate variable, which is in most of these cases is dimensionless. The standard_name of the parametric (usually dimensionless) vertical coordinate variable can be used to find the definition of the associated computed (always dimensional) vertical coordinate in Appendix D, Computed Vertical Coordinates. The definition provides a mapping between the parametric vertical coordinate values and computed values that can positively and uniquely indicate the location of the data. The formula_terms attribute can be used to associate terms in the definitions with variables in a netCDF file, and the computed_standard_name attribute can be used to supply the standard_name of the computed vertical coordinate values computed according to the definition. To maintain backwards compatibility with COARDS the use of these attributes is not required, but is strongly recommended. Some of the definitions may be supplemented with information stored in the grid_mapping variable about the datum used as a vertical reference (e.g. geoid, other geopotential datum or reference ellipsoid; see Section 5.6, Horizontal Coordinate Reference Systems, Grid Mappings, and Projections and Appendix F, Grid Mappings).

On reflection, I might prefer computed_standard_name to derived_standard_name, afterall.

All the best,

David

[jonathan]

Dear David

Thank you for thinking about it. I am happy with your proposed text.

Is it OK for you, Rich?

Cheers

Jonathan

[rsignell]

Yes, I'm okay with this slight modification.

[rsignell]

Since Jonathan, David and I support this and no-one has commented for more than three weeks, this proposal should be marked as accepted for the next version of CF.

Rich (Moderator)

[rhattersley]

Applied via ​https://github.com/cf-convention/cf-conventions/pull/69

[painter1]

All necessary changes have been made in the CF Conventions document. This ticket cannot yet be closed because it also requires changes in the conformance document and new standard names.

[jonathan]

I think that the changes in the conventions document for this ticket may not be quite right yet. Please see ​https://github.com/cf-convention/cf-conventions/pull/69#issuecomment-287085962.

[painter1]

It is fixed now.