id,summary,reporter,owner,description,type,status,priority,milestone,component,version,resolution,keywords,cc
143,Supplement the definitions of dimensionless vertical coordinates,jonathan,davidhassell,"== 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_name`s 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_name`s 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_name`s 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_name`s 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",task,closed,medium,,cf-conventions,,fixed,,