#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):
OK - I like the two proposed changes - thanks to Jonathan and Karl for
working on the minutea of this.
Here it is again, in full (one thing I've learnt from Jeff's and Tanya's
excellent work on the production of 1.7 is that having ''all'' the changes
in place at the bottom of the ticket is very useful when implementing it -
having to trawl the ticket for odd sentences here and there can be
difficult).
After the first paragraph of section 7.1 Cell Boundaries, add the
following three paragraphs and one example:
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 boundary variables for formula terms are two-
dimensional while the formula terms themselves are one-dimensional.
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 coordinates' `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` when a parametric coordinate
variable has bounds.
{{{
float eta(eta) ;
eta:long_name = "eta at full 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" ; // This
attribute is mandatory
float A(eta) ;
A:long_name = "'a' coefficient for vertical coordinate at full levels"
;
A:units = "Pa" ;
A:bounds = "A_bnds" ; // This attribute is included for the optional
second method
float B(eta) ;
B:long_name = "'b' coefficient for vertical coordinate at full levels"
;
B:units = "1" ;
B:bounds = "B_bnds" ; // This attribute is included for the optional
second method
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" ; // This attribute is included for the
optional second method
}}}
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
terms that depend on the vertical dimension. For such terms the variable
name appearing in the boundary variable's `formula_terms` attribute must
differ from that found in the `formula_terms` attribute of the coordinate
variable itself. The boundary variable of the `formula_terms` variable
must have the same dimensions as the `formula_terms` variable, plus a
trailing dimension (CDL order) for the maximum number of vertices in a
cell, which must be the same as the trailing dimension of the boundary
variable of the parametric vertical coordinate variable. If a named
variable in the `formula_terms` attribute of the vertical coordinate
variable depends on the vertical dimension and 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-trac.llnl.gov/trac/ticket/140#comment:30>
CF Metadata <http://cf-convention.github.io/>
CF Metadata
