#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 flags 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 flags
> 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 after example 3.3, renumbering examples
> 3.4 and 3.5 to 3.5 and 3.6 respectively (text checked for cross-
> references to "3.4" and "3.5" and none found)''
>
> A variable with standard name of `region`, `area_type` or any other
> standard name which requires string-valued values from a defined list may
> use flags together with `flag_values` and `flag_meanings` attributes to
> record the translation to the string values. The following example
> illustrates this using integer flag values for a variable with standard
> name `region` and `flag_values` selected from the
> [http://cfconventions.org/Data/cf-standard-names/docs/standardized-
> region-names.html standardized region names] (see section 6.1.1):
>
> Example 3.4. Flag variable with controlled values, using `flag_values`
> {{{
> 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, .....
> }}}
>
> == Hook in section 3.3 to highlight existence of constraints implied by
> standard name ==
>
> ''In section 3.3, append to the paragraph about "description", after
> "The description is meant to clarify the qualifiers of the fundamental
> quantities such as which surface a quantity is defined on or what the
> flux sign conventions are. We don"t attempt to provide precise
> definitions of fundumental physical quantities (e.g., temperature) which
> may be found in the literature." the following:''
>
> The description may define rules on the variable type, attributes and
> coordinates (such as in example 3.4) which must be complied with by any
> variable carrying that standard name.
>
> ''Note that also that there is a typo in the text cited aboove `don"t`
> instead of `don't`''
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 either strings
which indicate a geographical region or flags 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 either strings
which indicate the nature of the surface e.g. land, sea, sea_ice, or flags
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 after example 3.3, renumbering examples
3.4 and 3.5 to 3.5 and 3.6 respectively (text checked for cross-references
to "3.4" and "3.5" and none found)''
A variable with standard name of `region`, `area_type` or any other
standard name which requires string-valued values from a defined list may
use flags together with `flag_values` and `flag_meanings` attributes to
record the translation to the string values. The following example
illustrates this using integer flag values for a variable with standard
name `region` and `flag_values` selected from the
[http://cfconventions.org/Data/cf-standard-names/docs/standardized-region-
names.html standardized region names] (see section 6.1.1):
Example 3.4. Flag variable with controlled values, using `flag_values`
{{{
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, .....
}}}
== Hook in section 3.3 to highlight existence of constraints implied by
standard name ==
''In section 3.3, append to the paragraph about "description", after
"The description is meant to clarify the qualifiers of the fundamental
quantities such as which surface a quantity is defined on or what the flux
sign conventions are. We don"t attempt to provide precise definitions of
fundumental physical quantities (e.g., temperature) which may be found in
the literature." the following:''
The description may define rules on the variable type, attributes and
coordinates which must be complied with by any variable carrying that
standard name (such as in example 3.4).
''Note that also that there is a typo in the text cited aboove `don"t`
instead of `don't`''
--
Comment (by martin.juckes):
Hi David,
The first point is, I think, a misunderstanding of what I was trying to
say. I've moved the bracketted phrase to the end of sentence, which I hope
makes it clearer that it refers to the sentence as a whole, not
specifically to "coordinates".
On the 2nd bullet: I've changed the text of standard name definition to
clarify that the type restricton does not apply to flags.
cheers,
Martin
--
Ticket URL: <http://cf-trac.llnl.gov/trac/ticket/151#comment:14>
CF Metadata <http://cf-convention.github.io/>
CF Metadata
