BEAT-II MATLAB

The BEAT-II MATLAB interface consists of handful of functions that allow the user to easily ingest, analyze, compare, and manipulate data from product files.

This page describes how to use the functions that are provided by the BEAT-II MATLAB interface.

Contents

• BEAT-II Record
  • Array dimensions
  • Strings
• Functions
  • BEATL2_APPEND
  • BEATL2_CLEARALL
  • BEATL2_EXPORT
  • BEATL2_FIND_COLOCATED_DATA
  • BEATL2_IMPORT
  • BEATL2_INGEST
  • BEATL2_SLICE
  • BEATL2_VERSION

BEAT-II Record

MATLAB has some peculiarities in the way it deals with arrays and string data that require some special attention when dealing with BEAT-II record data.

Array dimensions

MATLAB can't distinguish between zero-dimensional (i.e. scalar), one-dimensional, and two-dimensional data, because it sees all data (except for higher dimensional data) as matrix data, which is two dimensional. Furthermore, MATLAB automatically reduces the number of dimensions when the highest dimension(s) equals 1. For instance, a [10,10,10,1] array will automatically be reduced to a [10,10,10] array.

This behaviour of MATLAB can make it hard to provide an array with a fixed number of dimensions to the BEAT-II interface. For this reason the BEAT-II MATLAB interface supports the addition of a special '..._num_dims' field in a BEAT-II record that can be used to specify the dimensionality of a field. The '...' part of the num_dims field will be the fieldname for which the number of dimensions is provided.

Record data that is the result of one of the BEAT-II functions (such as an ingestion or import) will have this field added automatically if the number of dimensions will be changed by MATLAB (this happens only for zero-dimensional data and data for which the highest dimension has a size of 1). If you want to provide your own records to the BEAT-II MATLAB functions, make sure that all arrays either have the proper dimension or that you provide an appropriate '..._num_fields' field.

Strings

BEAT-II considers strings as basic types when using BEAT-II records, but MATLAB supports only a single character as base type for string data. Because of this difference, a mapping had to be made for moving string data from BEAT-II to MATLAB or vice-versa. If a BEAT-II record field contains a single string then this is represented as a one-dimensional character array in MATLAB. If a BEAT-II record field contains a one- or higher-dimensional array of strings, this will be represented in MATLAB as a cell array with each cell containing a one-dimensional array of characters to represent the string array element data.

Functions

The descriptions for each BEAT-II MATLAB function are formatted in the same way that MATLAB documents its functions. This means that although functions might be written in capitals here, you should use the small-caps version in MATLAB to call them.

BEATL2_APPEND

BEATL2_APPEND Append two BEAT-II records.

RECORD = BEATL2_APPEND(RECORD_1, RECORD_2) will append record_2 to record_1 by using using the main (i.e. first) dimension.

Both records need to contain the same set of fields.

More information about BEAT-II records can be found in the BEAT-II Data Description documentation.

BEATL2_CLEARALL

BEATL2_CLEARALL Free all allocated resources that are claimed by the BEAT-II MATLAB interface.

BEATL2_CLEARALL will clean up any BEAT-II resources. At the first call to a BEAT-II MATLAB function the BEAT-II C Library will be initialized which will create a full representation of the BEAT-I data dictionary in memory (which can be a few megabytes in size). A call to beatl2_clearall will clean up any BEAT-II resources and thus also remove the data dictionary. After a clean up, the first call to a BEAT-II MATLAB function will initialize the BEAT-II C Library again.

This function may be (slightly) useful on systems with little memory. You could ingest a product file and then unload the data dictionary to free an extra megabyte of memory before starting data-processing. Other than that, this function is of little practical use.

BEATL2_EXPORT

BEATL2_EXPORT Export a BEAT-II record to a file.

BEATL2_EXPORT(FORMAT, FILEPATH, RECORD) will export the given record to the file that is specified by filepath. The export formats that are supported are:

• ASCII
• BINARY
• NETCDF
• HDF4
• HDF5

You should provide the format as a string to beatl2_export. If the export file already exists it will be overwritten.

See also BEATL2_IMPORT.

BEATL2_FIND_COLOCATED_DATA

BEATL2_FIND_COLOCATED_DATA Find co-located data for two BEAT-II records matching time, geolocation, and/or altitude.

[RECORD_1, RECORD_2] = BEATL2_FIND_COLOCATED_DATA(RECORD_1, RECORD_2, TIME_DISTANCE, RADIAL_DISTANCE, ALTITUDE_DISTANCE) 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 at least two similar fields to match on (time, latitude, longitude, and altitude). Each of these fields that are in a record need to be one dimensional.
If both records have a valid time field then the time_distance parameter (distance is seconds) is used to match the time values.
If both records have valid geolocation fields (latitude and longitude) then the radial_distance parameter (which represents an earth surface distance in km) is used to match the geolocation values.
If both records have a valid altitude field then the altitude_distance parameter (in km) is used to match the altitude values.
The final result is the intersection of the results for each of the fields. This means that the records that are returned only contain the measurements that lie within the given distances.

If a distance parameter is negative then no comparison will be performed for the associated property. If the function is unable to perform any comparisons (because all distance parameters are negative) the function will return an error.

More information about BEAT-II records can be found in the BEAT-II Data Description documentation.

BEATL2_IMPORT

BEATL2_IMPORT Import a BEAT-II record from a file.

RECORD = BEATL2_IMPORT(FORMAT, FILEPATH) will import the record stored in the file that is specified by filepath. You should specify the format of the file with the format parameter. Possible values for format are:

• ASCII
• BINARY
• NETCDF
• HDF4
• HDF5

You should provide the format as a string to beatl2_import.

See also BEATL2_EXPORT.

BEATL2_INGEST

BEATL2_INGEST Ingest data from a product file.

RECORD = BEATL2_INGEST(FILEPATH) reads data from the product file(s) specified by filepath.

RECORD = BEATL2_INGEST(FILEPATH, FILTER) reads data matching the filter from the product file(s) specified by filepath.

The filepath parameter must, in case you want to ingest just a single product file, be a string containing the full path (or relative path with respect to the current working directory) of the product file.

If you want to ingest multiple files at once, just provide a two dimensional character array or a one dimensional cell array with the full paths to the product files. All product files should be of the same product type for the ingestion to succeed.

The filter should be a single string containing a ',' or ';' separated list of filter options.

More information about BEAT-II records can be found in the BEAT-II Data Description documentation.

BEATL2_SLICE

BEATL2_SLICE Shrink a BEAT-II record to a subrange of its data.

RECORD = BEATL2_SLICE(RECORD, RANGE) will shrink the record in the main dimension.

RECORD = BEATL2_SLICE(RECORD, DIMENSION, RANGE) will shrink the record in the given dimension (which should be a sub-dimension of the main dimension).

More information about BEAT-II records can be found in the BEAT-II Data Description documentation.

BEATL2_VERSION

BEATL2_VERSION Get version number of BEAT.

VERSION = BEATL2_VERSION returns the version number of BEAT.