Page History

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). 

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).