Attach the CF flag_values
or flag_masks
attributes along with the CF flag_meanings
attribute to each flag variable in an Earth Science data product. The choice of which to use depends on the use case.
Recommendation Details:
A common practice in Earth Science data products is to associate a flag variable with a science data variable to describe the quality of each successful retrieval and to explain each occurrence of the fill value - we recommend that the CF flag_values
and flag_meanings
attributes be attached to the flag variable in cases where the coded values are mutually exclusive. In the case of a range of conditions (more than two) for each retrieval is expected flag_masks
should be used instead of flag_values
. In practice, there are often two flag variables for a physical retrieval; one that contains the scalar flag_values
(i.e., the overall quality of each pixel), and another with the flag_masks
that contains more specific flags for algorithm performance and outlier detection.
In rare (and complex) flagging cases they can be used together.
For an example of such usage consult the CF documentation (Example 3.5 , or Here).
flag_values/flag_meanings example:
Use flag_values
where a single status condition is appropriate to flag every retrieval.
For example, a science data variable named
total_column_ozone
with fill value
_FillValue
= -999.9
could be accompanied by an associated flag variable (type byte) named
total_column_ozone_flags
to describe the quality of each successful retrieval as an enumerated list of status flags and to explain each occurrence of the fill value. The total_column_ozone_flags
variable should have the CF flag_values
and flag_meanings
attributes attached to specify the flag values and meanings. For example,
flag_values
= 0b, 1b, 2b, 3b, 4b, 5b;
and
flag_meanings
= "good_sample glint_contamination high_sza non_convergence row_anomaly_error missing_input_data";
Note that there is a simple one-to-one mapping between the values of these two attributes. Also note that the values of flag_values
are comma-separated, while the values of flag_meanings
are space-separated, with an underscore being used as the word separator within each value of flag_meanings
.
flag_masks/flag_meanings example:
Use flag_masks
where a number of independent Boolean (binary) conditions using bit field notation are appropriate to describe a possible range of conditions for each retrievals.
For example, a science data variable named
sea_surface_temperature
could be accompanied by an associated flag variable (type byte) named
condition_flags
to describe the conditions of each retrieval as a set of boolean status flags . The condition_flags
variable should have the CF flag_masks
and flag_meanings
attributes attached to specify the flag values and their meanings. For example,
flag_masks
= 1b, 2b, 4b, 8b, 16b;
and
flag_meanings
= "ocean land ice lake river";
As an example of implementation, a retrieval could have both ocean and detected ice in it, a condition that would be flagged with the value 1b + 4b = 5 (i.e., 2^0 + 2^2).
Awaiting ESCO Approval
This recommendation has been finalized by DIWG but has not yet received final ESCO approval.