Functions | |
| int | beatl2_append (beatl2_Record *record_1, const beatl2_Record *record_2) |
| int | beatl2_find_colocated_data (beatl2_Record *record_1, beatl2_Record *record_2, double time_distance, double radial_distance, double altitude_distance) |
| int | beatl2_slice (beatl2_Record *record, const char *dimension, long num_ids, const long *id) |
| int | beatl2_slice_range (beatl2_Record *record, const char *dimension, long from_id, long to_id) |
This module extends the BEAT-II Record module. It provides functionality that affects multiple fields of a BEAT-II record at once. All these functions require that the BEAT-II record adhers to the conventions for e.g. existence of fields, naming of fields, dimension of fields, etc. as described below and in the BEAT-II Data Description documentation.
The most important relation within a BEAT-II record is that of dimensions and associated field names. A field can be either a scalar or a multi-dimensional array. If a field has one or more dimensions the first dimension should always be the 'appendable' dimension (i.e. the dimension in which data from multiple records can be appended). For this reason spectral data is nearly always represented as two dimensional data (even if we just have a single spectrum); data from a second record should result in an array of two spectra, instead of a single concatenated spectrum. The first dimension of a field that represents measurement data is the 'main' dimension. For all other record fields the first dimension will either have the same size or a shorter size.
If, for instance, wavelength values for a series of spectral readouts within a product is constant, we could suffice with just a single wavelength value array per product. In such cases where the first dimension of a field is a subset of the 'main' dimension, the fieldname will end with _per_'dimension' (in this case _per_file) and there will be a special elements_per_'dimension' field that gives the relationship between the given dimension and the 'main' dimension. For instance, each array element of the elements_per_file field will give the amount of 'main' elements per file. If we would have two files, with 1401 measurements in the first file and 1295 measurements in the second file, the main dimension would have 2696 elements, the 'file' dimension would have 2 elements and the elements_per_file array would have the values (1401, 1295). A similar subdimension of the main dimension exists for profiles (the 'profile' dimension) wich allows data to be provided per profile instead of per profile element.
The functions in this module all know about these dimensions and sub-dimensions. For instance, when you perform a slice or colocation operation, BEAT will modify the data in both the 'main' and all its sub-dimensions (e.g. 'file' and/or 'profile' dimension) and will also update the values in the elements_per_'dimension' field.
The functions in this module will even work with your own records with your own sub-dimensions. Just make sure that fields that contain data in the specific sub-dimension end with _per_'dimension' and there exists a elements_per_'dimension' field.
| int beatl2_append | ( | beatl2_Record * | record_1, |
| const beatl2_Record * | record_2 | ||
| ) |
Append the data of a BEAT-II record to another BEAT-II record. Both records (record_1 and record_2) need to have the same structure (i.e. same fields and field definitions).
| record_1 | Pointer to a valid BEAT-II record. This record will get the data from record2 added to it. |
| record_2 | Pointer to a valid BEAT-II record. This record will be appended to record1. |
0, Success. -1, Error occurred (check beatl2_errno). | int beatl2_find_colocated_data | ( | beatl2_Record * | record_1, |
| beatl2_Record * | record_2, | ||
| double | time_distance, | ||
| double | radial_distance, | ||
| double | altitude_distance | ||
| ) |
Find co-located data for two BEAT-II records matching time, geolocation, and/or altitude. This function will find the measurements in record_1 and record_2 that are close together (i.e. co-located). In order for the co-location to work both records need to have similar fields to match on (time, latitude and longitude, and/or altitude). Each of these fields in a record needs to be one dimensional and its dimension must be the "main" dimension (or a sub dimension of that; e.g. a 'time_per_profile' field is also allowed (but requires that an 'elements_per_profile' field also exists)). If the time_distance parameter is not negative then the time values are matched and both records need to have a valid time field. If the radial_distance parameter (which represents an earth surface distance in km) is not negative then the geolocation values are matched and both records need to have valid latitude and longitude fields. If the altitude_distance parameter is not negative then the altitude values are matched and both records need to have a valid altitude field. If a distance parameter is negative then no comparison will be performed for the associated property. This co-location function will remove all measurements from record_1 and record_2 for which no measurement in the other record can be found that is within the required distance(s). A measurement is only within the required distance if it is within the required distance for all of the properties (e.g. if the co-location is both on time and geolocation then the other measurement must be both within the time distance and the geolocation distance if the measurement is to stay). The colocation function will use the beatl2_slice function to remove measurements that are not colocated, so the records you provide to this function should also meet the requirements for passing it to the beatl2_slice function. If no co-located data was found both record_1 and record_2 will be left unmodified, the function will return -1 and beatl2_errno will be set to BEATL2_ERROR_NO_DATA. If the function is unable to perform any comparisons (because e.g. distance parameters are all negative) the function will treat this similar to the situation where it could not find co-located data.
| record_1 | Pointer to a valid BEAT-II record. |
| record_2 | Pointer to a valid BEAT-II record. |
| time_distance | Distance in seconds used to match time values of both records. |
| radial_distance | Distance in km used to match latitude and longitude values of both records. |
| altitude_distance | Distance in km used to match altitude values of both records. |
0, Success. -1, Error occurred (check beatl2_errno). | int beatl2_slice | ( | beatl2_Record * | record, |
| const char * | dimension, | ||
| long | num_ids, | ||
| const long * | id | ||
| ) |
Shrink a BEAT-II record to a subset of its data. The subset is given as an array of elements that should be sliced out. This function will shrink the first dimension of all fields in the BEAT-II record. The first dimension of all non-scalar fields should have the 'main' dimension or a sub of that (except for special fields such as 'grid_latitude' and 'grid_longitude' which will remain unmodified). If a field uses a subdimension of the main dimension (e.g. profile) its name should end in _per_'dimension' (e.g. time_per_profile) and there should be an elements_per_'dimension' field (e.g. elements_per_profile) in the record.
| record | Pointer to a valid BEAT-II record. |
| dimension | Name of the dimension to which the id array is applicable. Provide NULL for the main dimension. If the dimension is not the main dimension it should be a subdimension of the main dimension (e.g. 'profile' dimension) |
| num_ids | Number of elements to keep in the main dimension. |
| id | Array of indices (0 based) for the elements that need to be kept. |
0, Success. -1, Error occurred (check beatl2_errno). | int beatl2_slice_range | ( | beatl2_Record * | record, |
| const char * | dimension, | ||
| long | from_id, | ||
| long | to_id | ||
| ) |
Shrink a BEAT-II record to a subrange of its data. The subset is given as an array range of the elements that need to be kept. This function is a convenience wrapper for beatl2_slice.
| record | Pointer to a valid BEAT-II record. |
| dimension | Name of the dimension to which the id array is applicable. Provide NULL for the main dimension. If the dimension is not the main dimension it should be a subdimension of the main dimension (e.g. 'profile' dimension) |
| from_id | The first array index of the sub range (0 based). |
| to_id | The last array index of the sub range (0 based). |
0, Success. -1, Error occurred (check beatl2_errno).