Jonathon,
I like your idea about simply modifying the existing flag notation,
since adding an alternative to "flag" did seem a bit over the top to
me. However, taking your suggestion one step further, we could
combine the use of flag_masks and flag_values to support
multiple-bit notation. While formulating my original bitmap_values
proposal, I was pondering the multi-bit issue but didn't want to
overly-complicate the proposal. However, if the CF group is willing
to explore the option, let's got for it! This way, we would solve
two issues with the simple addition of the flag_masks attribute.
Here's what I'd propose:
For single bit status flags, the flag_masks and flag_meanings lists
would define the necessary Boolean conditions as you suggest:
byte precip_qc(time, z0, y0, x0) ;
precip_qc:long_name = "Precipitation status bit field" ;
precip_qc:grid_mapping = "grid_mapping0" ;
precip_qc:_FillValue = 0b ;
precip_qc:valid_range = 1b, 15b ;
precip_qc:flag_masks = 1b, 2b, 4b, 8b ;
precip_qc:flag_meanings = "no_coverage impaired phase_mixed
phase_snow";
Without a flag_values attribute, a NetCDF reader would simply AND
the flag_masks codes with the data variable and check for non-zero
results in order to detect a status condition.
However, for multiple-bit status flags, the flag_values and
flag_masks lists would, together, define the bitwise mask and the
expected result that would express a status condition. For example:
byte precip_qc(time, z0, y0, x0) ;
precip_qc:long_name = "Precipitation status bit field" ;
precip_qc:grid_mapping = "grid_mapping0" ;
precip_qc:_FillValue = 0b ;
precip_qc:valid_range = 1b, 15b ;
precip_qc:flag_masks = 1b, 2b, 12b, 12b, 12b ;
precip_qc:flag_values = 1b, 2b, 4b, 8b, 12b ;
precip_qc:flag_meanings = "no_coverage impaired rain mixed snow";
In this case, the least significant bit indicates no coverage, the
next bit indicates sensor impairment, and the following two bits
describe the precipitation phase observed at the corresponding grid
location (an implied zero value indicates no precipitation at all).
Thus, for multiple-bit status, a repeated flag_masks code would be
required for every matching flag_values code. A NetCDF reader
application would perform a bitwise AND operation of the variable
value and each flag_mask before comparing the results with the
corresponding flag_values code. It would probably be a good thing
for the CF compliance checker to verify that the number of
flag_masks and flag_values match and that all flag_values codes for
a flag_masks code are unique.
In a sense, the current flag_values definition implies a default
flag_masks of repeated instances of the data type with all bits
set to one, specifically, 255b for byte, 65535s for short, etc.
Example 3.3 in the CF document:
byte current_speed_qc(time, depth, lat, lon) ;
current_speed_qc:long_name = "Current Speed Quality" ;
current_speed_qc:_FillValue = -128b ;
current_speed_qc:valid_range = -127b, 127b ;
current_speed_qc:flag_values = 0b, 1b, 2b ;
current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional
outside_valid_range" ;
... could equivalently, though not necessarily, be expressed as:
byte current_speed_qc(time, depth, lat, lon) ;
current_speed_qc:long_name = "Current Speed Quality" ;
current_speed_qc:_FillValue = -128b ;
current_speed_qc:valid_range = -127b, 127b ;
current_speed_qc:flag_masks = -1b, -1b, -1b ;
current_speed_qc:flag_values = 0b, 1b, 2b ;
current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional
outside_valid_range" ;
If this seems like a reasonable proposal you to (and others), I'd
be happy submit the proposal to the CF trac Website as you suggested.
Greg.
cf-metadata-request at cgd.ucar.edu wrote:
>
> ------------------------------
>
> Message: 4
> Date: Thu, 20 Mar 2008 19:59:13 -0400
> From: Greg Rappa <gregr at ll.mit.edu>
> Subject: [CF-metadata] CF Addition Proposal: bitmap values
> To: cf-metadata at cgd.ucar.edu
> Message-ID: <47E2FA51.8030101 at ll.mit.edu>
> Content-Type: text/plain; charset="us-ascii"
>
> An HTML attachment was scrubbed...
> URL: http://mailman.cgd.ucar.edu/pipermail/cf-metadata/attachments/20080320/b72a9d0a/attachment-0001.html
>
> ------------------------------
>
> Message: 5
> Date: Fri, 21 Mar 2008 08:08:14 +0000
> From: Jonathan Gregory <j.m.gregory at reading.ac.uk>
> Subject: [CF-metadata] CF Addition Proposal: bitmap values
> To: cf-metadata at cgd.ucar.edu
> Message-ID: <20080321080814.GB8184 at met.reading.ac.uk>
> Content-Type: text/plain; charset=us-ascii
>
> Dear Greg
>
> I agree that flag values are quite often generated in the way you describe,
> by logical OR of bit values. While this could be described using the current
> convention, by enumerating the translation for all the possible distinct ORed
> combinations, that would obviously be very inefficient! I would suggest that
> rather than introduce an alternative to "flag", we could modify it, thus:
>
> byte precip_qc(time, z0, y0, x0) ;
> precip_qc:long_name = "Precipitation status bit field" ;
> precip_qc:grid_mapping = "grid_mapping0" ;
> precip_qc:_FillValue = 0b ;
> precip_qc:valid_range = 1b, 15b ;
> precip_qc:flag_masks = 1b, 2b, 4b, 8b ;
> precip_qc:flag_meanings = "no_coverage impaired phase_mixed phase_snow";
>
> where the use of flag_masks instead of flag_values implies that the values
> can be ORed, rather than being mutually exclusive. What do you think?
>
> I also wonder whether a more general treatment would be helpful, because a flag
> value could be a logical OR of codes which may occupy more than one bit e.g.
> a flag might be defined as an OR of bits 0-1 (with four possible values),
> bit 2 (with two) and bit 3-5 (with eight). Is that likely to be useful? It is
> a combination of the two approaches.
>
> To propose a change to the convention, you start a new ticket on the CF trac
> website under http://cf-pcmdi.llnl.gov/, using the template provided. The
> proposal should say exactly what text should be changed (as you did) and also
> what changes are needed to the conformance document.
>
> Best wishes
>
> Jonathan
>
>
> End of CF-metadata Digest, Vol 60, Issue 9
> ******************************************
>
Received on Fri Mar 21 2008 - 10:25:57 GMT
