BEAT-II Conventions
Structure of field names
All fields use the following structure for their names:
<quantity>[<height_indication>][_grid][_per_dimension][_error][<postfix>]
<postfix> can be any of _unit, _description, or _validity.
Fields with special meaning
| field name | description |
|---|---|
grid_latitude | This field gives the latitude values for the latitude axis of a grid (a 3D field with dimensions [main,latitude,longitude]) |
grid_longitude | This field gives the latitude values for the latitude axis of a grid (a 3D field with dimensions [main,latitude,longitude]) |
elements_per_dim | This fields gives the relation between dim and the main dimension. See also below |
foo_error | Provides the error statistics for the field foo (see also below) |
foo_unit | Should be a single string giving the unit (see also below) |
foo_description | Can be available (and only in that case) if there was a foo_variant ingestion filter option available that allowed a choice between different sources for the field value (e.g. retrieved values vs. values from a model). The description field will then contain a textual description of the source of the data for the field foo |
No other fields than grid_latitude and grid_longitude should start their name with grid_.
The _error, _unit, and _description fields are the default derivatives for a 'normal' field. BEAT-II will treat these fields in a special way. For instance, if you use the include or exclude filter to include or exclude a certain field foo for a BEAT-II ingestion, BEAT-II will automatically also include/exclude the derivative fields foo_unit, foo_description, foo_error, foo_error_unit and foo_error_description (if they exist).
The _validity field does not have this special status (this field contains flag information and is often very measurement/retrieval specific). In most cases the field is not included by default for an ingestion (but can be used for filtering purposes at ingestion time or explicitly ingested using the include ingestion filter option).
Species
Names of species are written using plain ASCII and small caps. For example H2O is written as h2o. If the isotopologue matters then the AFGL (Air Force Geophysics Laboratory) shorthand notation for the isotopologue is appended to the species identifier. For example o3_686 refers to 16O18O16O and h2o_162 refers to 1H16O2H (= 1H16OD). However, if we are dealing with the most abundant version, the isotopologue number is omitted (e.g. co2_626 is just written as co2).
Quantities
| field name part | unit | description |
|---|---|---|
| species | ppmv | volume mixing ratio (vmr) in particles per million |
| ppmm | mass mixing ratio (mmr) in particles per million | |
| cm^-3 | number density | |
| g/cm^-3 | mass density |
If a quantity can occur both in a wavelength dependent and a spectrally integrated form (such as radiances) the wavelength dependend variant (i.e. the two-dimensional version) of the field will have a name that starts with spectral_.
Height indications
We distinguish quantities at a specific point and quantities integrated over a distance.
If no explicit height indication is given, then the intrinsic height of the measurement is assumed. For total column data this is the height level of the instrument and for profile data the tangent location of the measurement. This convention is used for e.g. solar angles.
| field name part | description |
|---|---|
| toa | top of atmosphere |
| cloud_top | cloud top height |
| surface | earth surface |
| geoid | earth geoid |
| wgs84 | WGS84 ellipsoid |
Error quantifications
| unit | description |
|---|---|
| unit of quanity | absolute error on the measured quantity |
| % | percentage of quantity |
| (unit of quanity)^2 | variance |
| unit of quanity | standard deviation |
Units
Unit information is provided in plain ASCII. There should be at most one division "/" in a unit description. Multiplication is done using a dot ".". Exponents are provided using a caret "^". The use of braces "(" ")" should be avoided.
Radiance can, for instance, have the unit "photons/s.cm^2.sr.nm" and line intensity, as another example, "cm^-1/molecules.cm^-2".
Current conventions for units are:
| quantity | currently supported units |
|---|---|
| time | seconds since 01-JAN-2000 00:00:00 |
| temperature | K |
| pressure | hPa |
| latitude | -90 - 90 (degrees north) |
| longitude | -180 - 180 (degrees west) |
| altitude | km |
| volume mixing ratio | ppmv (parts per million volume) |
| mass mixing ratio | ppmm (parts per million mass) |
| number density | molec/cm^3, mol/cm^3 |
| mass density | g/m^3 |
| column number density | molec/cm^2, mol/cm^2, DU |
| column mass density | kg/m^2 |
| cross section | cm^2/molec |
| wavelength | nm |
| wavenumber | cm^-1 |
| line intensity | cm^-1/molec.cm^-2 |
| radiance | W/cm^2.sr ('W' may also be 'photons/s') |
| irradiance | W/cm^2 ('W' may also be 'photons/s') |
| spectral readout | BU (Binary Units) |
| spectral radiance | W/cm^2.sr.cm^-1 ('W' may also be 'photons/s' and 'cm^-1' may also be 'nm') |
| spectral irradiance | W/cm^2.cm^-1 ('W' may also be 'photons/s' and 'cm^-1' may also be 'nm') |
Dimensions
If data is provided only 'per so many measurements' we append the special per_dimension to the fieldname. If such fields are present there will also be a elements_per_dimension field present that indicates to how many measurements each array element of a per_dimension field is associated. The sum of the contents of the elements_per_dimension array should thus always equal the total number of measurements (i.e. the size of the main dimension).
Note that these dimension relations only work on the first dimension of BEAT-II record data (i.e. there will never be relations between the spectral dimension and the main dimension).
Current available sub-dimensions of the main dimension are provided below:
| dimension | postfix | dimension size information field |
|---|---|---|
| profile | _per_profile | elements_per_profile |
| file | _per_file | elements_per_file |
For instance, suppose we have a BEAT-II record containing data for 4 profiles and the profiles contain (in order) 10, 8, 16, and 24 elements. The main dimension will contain a concatenation of all profile data and thus be 58 elements in size. The elements_per_profile field will be an array of 4 elements: { 10, 8, 16, 24 }.
Open Issues
The conventions currently used in BEAT-II are a first step and may be improved in the future (with possible renaming of fields!). For instance, it is currently difficult to immediately distinguish (using field names) between:
- number densities and mass densities (both for 'point' densities and column densities)
- vertical column density, slant column density, and tangent line density
- mol vs. molecules (should we standardize on either?)
- columns (i.e. per cm^2) and profiles (per cm^3) on one hand and profiles of partial columns on the other (i.e. the OMI O3 profile values are actually partial column densities in DU)