Ticket #26: reTrac

File reTrac, 6.5 KB (added by gregr, 11 years ago)

Four suggested changes to the existing CF Conventions document regarding the proposed bit field flags attribute.

Line 
1The following document describes suggested changes to the CF
2Conventions document to describe the proposed enhancement of
3the Flags definition to support bit field notation using a
4flag_masks attribute.
5
6There are four sections to be modified:
7  (1) Table of Contents
8  (2) Section 3.5, Flags
9  (3) Appendix A, Attributes
10  (4) Appendix C, Standard name Modifiers
11
12These changes are described in the following sections:
13
14================================================================
15
16(1) Table of Contents
17
18FROM:
19
20  List of Examples
21    3.3 A flag variable
22
23TO:
24
25  List of Examples
26    3.3 A flag variable, using flag_values
27    3.4 A flag variable, using flag_masks
28    3.5 A flag variable, using flag_values and flag_masks
29
30================================================================
31
32(2) Section 3.5, Flags
33
34FROM:
35
363.5. Flags
37
38The attributes flag_values and flag_meanings are intended to make variables that contain flag values self describing. The flag_values attribute is the same type as the variable to which it is attached, and contains a list of the possible flag values. The flag_meanings attribute is a string whose value is a blank separated list of descriptive words or phrases, one for each flag value. If multi-word phrases are used to describe the flag values, then the words within a phrase should be connected with underscores.
39
40Example 3.3. A flag variable
41
42  byte current_speed_qc(time, depth, lat, lon) ;
43    current_speed_qc:long_name = "Current Speed Quality" ;
44    current_speed_qc:_FillValue = -128b ;
45    current_speed_qc:valid_range = -127b, 127b ;
46    current_speed_qc:flag_values = 0b, 1b, 2b ;
47    current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional
48                                                     outside_valid_range" ;
49
50TO:
51
523.5. Flags
53
54The attributes flag_values, flag_masks and flag_meanings are intended to make variables that contain flag values self describing. Status codes and Boolean (binary) condition flags may be expressed with different combinations of flag_values and flag_masks attribute definitions.
55
56The flag_values and flag_meanings attributes describe a status flag consisting of mutually exclusive coded values.  The flag_values attribute is the same type as the variable to which it is attached, and contains a list of the possible flag values.  The flag_meanings attribute is a string whose value is a blank separated list of descriptive words or phrases, one for each flag value.  If multi-word phrases are used to describe the flag values, then the words within a phrase should be connected with underscores.  Example 3.3 illustrates the use of flag values to express a speed quality with an enumerated status code.
57
58Example 3.3.  A flag variable, using flag_values
59
60byte current_speed_qc(time, depth, lat, lon) ;
61     current_speed_qc:long_name = "Current Speed Quality" ;
62     current_speed_qc:_FillValue = -128b ;
63     current_speed_qc:valid_range = -127b, 127b ;
64     current_speed_qc:flag_values = 0b, 1b, 2b ;
65     current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional
66                                       outside_valid_range" ;
67
68The flag_masks and flag_meanings attributes describe a number of independent Boolean conditions using bit field notation by setting unique bits in each flag_masks value.  The flag_masks attribute is the same type as the variable to which it is attached, and contains a list of values matching unique bit fields.  The flag_meanings attribute is defined as above, one for each flag_masks value.  A flagged condition is identified by performing a bitwise AND of the variable value and each flag_masks value; a non-zero result indicates a true condition.  Thus, any or all of the flagged conditions may be true, depending on the variable bit settings. Example 3.4 illustrates the use of flag_masks to express six sensor status conditions:
69
70Example 3.4.  A flag variable, using flag_masks
71
72byte sensor_status_qc(time, depth, lat, lon) ;
73     sensor_status_qc:long_name = "Sensor Status" ;
74     sensor_status_qc:_FillValue = 0b ;
75     sensor_status_qc:valid_range = 1b, 127b ;
76     sensor_status_qc:flag_masks = 1b, 2b, 4b, 8b, 16b, 32b ;
77     sensor_status_qc:flag_meanings = "low_battery processor_fault
78                                       memory_fault disk_fault
79                                       software_fault
80                                       maintenance_required" ;
81
82The flag_masks, flag_values and flag_meanings attributes, used together, describe a blend of independent Boolean conditions and enumerated status codes.  The flag_masks and flag_values attributes are both the same type as the variable to which they are attached.  A flagged condition is identified by a bitwise AND of the variable value and each flag_masks value; a result that matches the flag_values value indicates a true condition.  Repeated flag_masks define a bit field mask that identifies a number of status conditions with different flag_values.  The flag_meanings attribute is defined as above, one for each flag_masks bit field and flag_values definition.  Each flag_values and flag_masks value must coincide with a flag_meanings value.  Example 3.5 illustrates the use of flag_masks and flag_values to express two sensor status conditions and and one enumerated status code.
83
84Example 3.5.  A flag variable, using flag_masks and flag_values
85
86byte sensor_status_qc(time, depth, lat, lon) ;
87     sensor_status_qc:long_name = "Sensor Status" ;
88     sensor_status_qc:_FillValue = 0b ;
89     sensor_status_qc:valid_range = 1b, 127b ;
90     sensor_status_qc:flag_masks = 1b, 2b, 12b, 12b, 12b ;
91     sensor_status_qc:flag_values = 1b, 2b, 4b, 8b, 12b ;
92     sensor_status_qc:flag_meanings = "low_battery hardware_fault
93                                       offline_mode calibration_mode
94                                       maintenance_mode";
95
96================================================================
97
98(3) Appendix A, Attributes
99
100ADD:
101
102[flag_masks] [D] [D] [Section 3.5, "Flags"] [Provides a list of bit fields expressing Boolean or enumerated flags.]
103
104================================================================
105
106(4) Appendix C, Standard Name Modifiers
107
108FROM:
109
110[status_flag] [ ] [Flag values indicating the quality or other status of the data values. The variable should have flag_values and flag_meanings attributes to show how it should be interpreted (Section 3.5, “Flags”).]
111
112TO:
113
114[status_flag] [ ] [Flag values indicating the quality or other status of the data values.  The variable should have flag_values or flag_masks (or both) and flag_meanings attributes to show how it should be interpreted (Section 3.5, “Flags”).]
115