#140: Clarifying the role of attributes on boundary variables.
-----------------------------+------------------------------------------
Reporter: davidhassell | Owner: cf-conventions@…
Type: enhancement | Status: new
Priority: medium | Milestone:
Component: cf-conventions | Version:
Resolution: | Keywords: boundary variable, attribute
-----------------------------+------------------------------------------
Comment (by davidhassell):
Here are the proposed changes in full:
After the first paragraph of section 7.1 Cell Boundaries, add the
following three paragraphs and two examples:
Boundary variable attributes which determine the coordinate
type (`units`, `standard_name`, `axis` and `positive`) or
those which affect the interpretation of the array values
(`units`, `calendar`, `leap_month`, `leap_year` and
`month_lengths`) must always agree exactly with the same
attributes of its associated coordinate, scalar coordinate or
auxiliary coordinate variable. To avoid duplication, however,
it is recommended that these are not provided to a boundary
variable.
If a parametric coordinate variable with a `formula_terms`
attribute (section 4.3.2) also has a bounds attribute, its
boundary variable must have a `formula_terms` attribute
too. In this case the same terms would appear in both (as
specified in Appendix D), since the transformation from the
parametric coordinate values to physical space is realized
through the same formula. For any term that depends on the
vertical dimension, however, the variable names appearing in
the formula terms would differ from those found in the
`formula_terms` attribute of the coordinate variable itself
because the 2-dimensional bound locations do not generally
coincide with the 1-dimensional coordinate locations.
Whenever a `formula_terms` attribute is attached to a
boundary variable, the formula terms may additionally be
identified using a second method: variables appearing in the
vertical coordinate's `formula_terms` may be declared to be
coordinate, scalar coordinate or auxiliary coordinate
variables, and those coordinates may have `bounds` attributes
that identify their boundary variables. In that case, the
`bounds` attribute of a formula terms variable must be
consistent with the `formula_terms` attribute of the boundary
variable. Software digesting legacy datasets (constructed
prior to version 1.7 of this standard) may have to rely in
some cases on the first method of identifying the formula
term variables and in other cases, on the second. Starting
from version 1.7, however, the first method will be
sufficient.
'''Example:''' Specifying `formula_terms` on a boundary variable when
the named variables that depend on the vertical dimension are not
associated with coordinate, scalar coordinate or auxiliary coordinate
variables.
{{{
float eta(eta) ;
eta:long_name = "eta at half levels" ;
eta:positive = "down" ;
eta:standard_name = "atmosphere_hybrid_sigma_pressure_coordinate" ;
eta:formula_terms = "a: A b: B ps: PS p0: P0" ;
eta:bounds="eta_bnds" ;
float eta_bnds(eta, 2) ;
eta_bnds:formula_terms = "a: A_full b: B_full ps: PS p0: P0" ;
float A(eta) ;
A:long_name = "'a' coefficient for vertical coordinate at half levels"
;
A:units = "Pa" ;
float B(eta) ;
B:long_name = "'b' coefficient for vertical coordinate at half levels"
;
B:units = "1" ;
float A_full(eta, 2) ;
A_full:long_name = "'a' coefficient for vertical coordinate at full
levels" ;
A_full:units = "Pa" ;
float B_full(eta, 2) ;
B_full:long_name = "'a' coefficient for vertical coordinate at full
levels" ;
B_full:units = "1" ;
float PS(lat, lon) ;
PS.units = 'Pa' ;
float P0 ;
P0.units = 'Pa' ;
float temp(eta, lat, lon) ;
temp:standard_name = "air_temperature" ;
temp:units = "K" ;
}}}
'''Example:''' Specifying `formula_terms` on a boundary variable when
the named variables that depend on the vertical dimension contain boundary
values to auxiliary coordinate variables.
{{{
float eta(eta) ;
eta:long_name = "eta at half levels" ;
eta:positive = "down" ;
eta:standard_name = " atmosphere_hybrid_sigma_pressure_coordinate" ;
eta:formula_terms = "a: A b: B ps: PS p0: P0" ;
eta:bounds="eta_bnds" ;
float eta_bnds(eta, 2) ;
eta_bnds:formula_terms = "a: A_bnds b: B_bnds ps: PS p0: P0" ;
float A(eta) ;
A:long_name = "'a' coefficient for vertical coordinate at full levels"
;
A:units = "Pa" ;
A:bounds = "A_bnds" ;
float B(eta) ;
B:long_name = "'b' coefficient for vertical coordinate at full levels"
;
B:units = "1" ;
B:bounds = "B_bnds" ;
float A_bnds(eta, 2) ;
float B_bnds(eta, 2) ;
float PS(lat, lon) ;
PS.units = 'Pa' ;
float P0 ;
P0.units = 'Pa' ;
float temp(eta, lat, lon) ;
temp:standard_name = "air_temperature" ;
temp:units = "K";
temp:coordinates = "A B" ;
}}}
The conformance document is to be changed as follows:
In section 7.1 Cell Boundaries:
Replace requirement "If a boundary variable has `units` or `standard_name`
attributes, they must agree with those of its associated variable." with
If a boundary variable has `units`, `standard_name`, `axis`,
`positive`, `calendar`, `leap_month`, `leap_year` or
`month_lengths` attributes, they must agree with those of its
associated variable.
Add a new requirement (''This requirement is backwards incompatible''):
Starting with version 1.7, a boundary variable must have a
`formula_terms` attribute when
it contains bounds for a parametric vertical coordinate
variable that has a `formula_terms` attribute. In this case the
same terms and named variables must appear in both except for
any term that depends on the vertical dimension, for which the
variable name appearing in the boundary variable's
`formula_terms` must differ from that found in the
`formula_terms` of the coordinate variable itself. In this case,
if the named variable in the `formula_terms` attribute of the
vertical coordinate variable is a coordinate, scalar coordinate
or auxiliary coordinate variable then its `bounds` attribute
must be consistent with the equivalent term in `formula_terms`
attribute of the boundary variable.
Replace recommendation "Boundary variables should not have the
`_FillValue` or `missing_value` attributes." with
Boundary variables should not have the `_FillValue`,
`missing_value`, `units`, `standard_name`, `axis`, `positive`,
`calendar`, `leap_month`, `leap_year` or `month_lengths`
attributes.
--
Ticket URL: <https://cf-pcmdi.llnl.gov/trac/ticket/140#comment:22>
CF Metadata <http://cf-convention.github.io/>
CF Metadata
