#151: Clarification of use of standard region names in "region" variables.
-----------------------------+------------------------------
Reporter: martin.juckes | Owner: cf-conventions@…
Type: enhancement | Status: new
Priority: medium | Milestone:
Component: cf-conventions | Version:
Resolution: | Keywords:
-----------------------------+------------------------------
Old description:
> The CF standard name `region` has the current description "A variable
> with the standard name of region contains strings which indicate
> geographical regions. These strings must be chosen from the standard
> region list." This description implies that the variable should be of
> character type, but it is often more convenient to have an integer
> variable and make a clear link to the region names using `flag_values`
> and `flag_meanings`. The proposal is to clarify the definition so that
> either usage is acceptable and include an example of the latter usage in
> the convention text. It is also proposed that an appendix be added to the
> CF Convention text to state clearly any constraints on file meta-data
> which are implied by the CF Standard Name definitions, so that it is
> possible to test such constraints in the CF checker.
>
> == New descriptions for CF standard names ==
>
> === region ===
>
> A variable with the `standard_name` of `region` contains strings which
> indicate a geographical region or integers which can be translated to
> strings using `flag_values` and `flag_meanings` attributes. These strings
> are standardised. Values must be taken from the CF standard region list.
>
> === area_type ===
>
> A variable with the `standard_name` of `area_type` contains strings which
> indicate the nature of the surface e.g. land, sea, sea_ice, or integers
> which can be translated to strings using `flag_values` and
> `flag_meanings` attributes. These strings are standardised. Values must
> be taken from the area_type table.
>
> == New usage example in CF Convention text ==
> ''The following should be placed at the end of 6.1.1, after example 6.2''
>
> A variable with standard name of `region`, `area_type` or any other
> standard name which requires string-valued values from a defined list may
> alternatively be of integer type and use `flag_values` and
> `flag_meanings` attributes to record the translation between the integers
> and the string values, for instance:
>
> {{{
> int basin(lat, lon);
> standard_name: region;
> flag_values: '1 2 3';
> flag_meanings:'atlantic_arctic_ocean indo_pacific_ocean
> global_ocean';
> ......
> values::
> basin: 1, 1, 1, 1, 2, .....
> }}}
>
> == New Appendix Section ==
> ''Change "Appendix B: Standard Name Table Format" to:''
>
> == Appendix B: Standard Names ==
> === B.1: Standard Name Table Format ===
> .....
>
> ''and''
>
> === B.2 Constraints for specific standard names ===
>
> B.2.1: region
>
> Variables with standard name `region` must be one of:
> * type character, with values taken from the CF standard region list;
> * type integer, with `flag_values` and `flag_meanings` attributes. The
> flag_meanings attributes must be a space separatd list of values from the
> CF standard region list (see example 6.2).
>
> Variables with standard name `area_type` must be one of:
> * type character, with values taken from the area type table;
> * type integer, with `flag_values` and `flag_meanings` attributes. The
> flag_meanings attributes must be a space separatd list of values from the
> area type table (analogous to example 6.2).
New description:
The CF standard name `region` has the current description "A variable with
the standard name of region contains strings which indicate geographical
regions. These strings must be chosen from the standard region list." This
description implies that the variable should be of character type, but it
is often more convenient to have an integer variable and make a clear link
to the region names using `flag_values` and `flag_meanings`. The proposal
is to clarify the definition so that either usage is acceptable and
include an example of the latter usage in the convention text. It is also
proposed that an appendix be added to the CF Convention text to state
clearly any constraints on file meta-data which are implied by the CF
Standard Name definitions, so that it is possible to test such constraints
in the CF checker.
== New descriptions for CF standard names ==
=== region ===
A variable with the `standard_name` of `region` contains strings which
indicate a geographical region or integers which can be translated to
strings using `flag_values` and `flag_meanings` attributes. These strings
are standardised. Values must be taken from the CF standard region list.
=== area_type ===
A variable with the `standard_name` of `area_type` contains strings which
indicate the nature of the surface e.g. land, sea, sea_ice, or integers
which can be translated to strings using `flag_values` and `flag_meanings`
attributes. These strings are standardised. Values must be taken from the
area_type table.
== New usage example in CF Convention text ==
''The following should be placed at the end of 6.1.1, after example 6.2''
A variable with standard name of `region`, `area_type` or any other
standard name which requires string-valued values from a defined list may
alternatively be of integer type and use `flag_values` and `flag_meanings`
attributes to record the translation between the integers and the string
values, for instance:
{{{
int basin(lat, lon);
standard_name: region;
flag_values: 1, 2, 3;
flag_meanings:'atlantic_arctic_ocean indo_pacific_ocean
global_ocean';
......
values::
basin: 1, 1, 1, 1, 2, .....
}}}
== New Appendix Section ==
''Change "Appendix B: Standard Name Table Format" to:''
== Appendix B: Standard Names ==
=== B.1: Standard Name Table Format ===
.....
''and''
=== B.2 Constraints for specific standard names ===
B.2.1: region
Variables with standard name `region` must be one of:
* type character, with values taken from the CF standard region list;
* type integer, with `flag_values` and `flag_meanings` attributes. The
flag_meanings attributes must be a space separatd list of values from the
CF standard region list (see example 6.2).
Variables with standard name `area_type` must be one of:
* type character, with values taken from the area type table;
* type integer, with `flag_values` and `flag_meanings` attributes. The
flag_meanings attributes must be a space separatd list of values from the
area type table (analogous to example 6.2).
--
Comment (by martin.juckes):
Dear Jonathan,
In the draft of CF-1.7 section 6 is "Labels and Alternative Coordinates"
and 6.1 is "Labels", which looks suitable to me. Example 6.2 has a region
variable as a coordinate, but the text is about how to encode geographical
regions in a variable. I can't see how this fits into section 5
("Coordinates"). Am I missing something here?
On the cf-checker: a NetCDF file with a variable:
{{{
float basin(index):
standard_name: region
}}}
is passed by the checker as valid, with a warning for the absence of a
`units` attribute on the variable. If the variable is defined as in the
example above and invalid region names are used, this is also passed (I've
updated the example to change `flag_values` from a string, which the
checker does not allow, to a list of integers). So these details are not
currently checked.
regards.
Martin
--
Ticket URL: <http://cf-trac.llnl.gov/trac/ticket/151#comment:5>
CF Metadata <http://cf-convention.github.io/>
CF Metadata
