BEAT-I MATLAB

The BEAT-I MATLAB interface consists of several functions that allow the user to easily access data inside product files.

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

Contents

• Functions
  • BEAT_ATTRIBUTES
  • BEAT_CLASS
  • BEAT_CLEARALL
  • BEAT_CLOSE
  • BEAT_DESCRIPTION
  • BEAT_FETCH
  • BEAT_FIELDAVAILABLE
  • BEAT_FIELDCOUNT
  • BEAT_FIELDNAMES
  • BEAT_GETOPT
  • BEAT_OPEN
  • BEAT_PRODUCT_CLASS
  • BEAT_PRODUCT_TYPE
  • BEAT_PRODUCT_VERSION
  • BEAT_SETOPT
  • BEAT_SIZE
  • BEAT_TIME_TO_STRING
  • BEAT_UNIT
  • BEAT_VERSION
• Data Specification Argument List
• BEAT-I MATLAB Options

Functions

The descriptions for each BEAT-I 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.

BEAT_ATTRIBUTES

BEAT_ATTRIBUTES Return object attributes.

C = BEAT_ATTRIBUTES(BEAT_FILE_ID, <DATA SPEC ARGS>) returns a struct containing all attributes that are associated with the specified data element. If no attributes are available an empty struct will be returned.

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open. The format for the data specification argument list <data spec args> is described in a separate section.

See also BEAT_FETCH, BEAT_OPEN, DATA SPEC ARGS

BEAT_CLASS

BEAT_CLASS Return object class.

C = BEAT_CLASS(BEAT_FILE_ID, <DATA SPEC ARGS>) returns the MATLAB class of the specified data element. With beat_class you can check what the class of a data element will be without the need to retrieve it via beat_fetch. The returned class is identical to what would be returned by class(beat_fetch(...)) if beat_class and beat_fetch had identical parameters.

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open. The format for the data specification argument list <data spec args> is described in a separate section.

See also BEAT_FETCH, BEAT_OPEN, DATA SPEC ARGS

BEAT_CLEARALL

BEAT_CLEARALL Close all open product files and remove data dictionary from memory.

BEAT_CLEARALL will close all currently open product files (similar to calling beat_close for all open product files). This can be especially helpful to close files for which you have lost the file handle (something that can occur if you were running an M file that opened a product file, but terminated halfway and thus left the file open).

This function will also free the data-dictionary from memory. At the first call to beat_open, the BEAT-I MATLAB interface will create a full representation of the data dictionary in memory (which can be a few megabytes in size). A call to beat_clearall will remove this data dictionary. After this, the first call to beat_open will create the data dictionary again.

See also BEAT_OPEN, BEAT_CLOSE

BEAT_CLOSE

BEAT_CLOSE Close an open product file.

BEAT_CLOSE(BEAT_FILE_ID) closes the product file which is associated with the beat_file_id file handle.

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open.

See also BEAT_OPEN, BEAT_CLEARALL

BEAT_DESCRIPTION

BEAT_DESCRIPTION Retrieve field description.

DESC = BEAT_DESCRIPTION(BEAT_FILE_ID, <DATA SPEC ARGS>) returns a string containing the description in the data dictionary of the specified data element. If the last item of the data specifier argument list equals a fieldname then you will get the description from the Data Dictionary for this field.

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open. The format for the data specification argument list <data spec args> is described in a separate section.

See also BEAT_FETCH, BEAT_OPEN, DATA SPEC ARGS

BEAT_FETCH

BEAT_FETCH Retrieve data from a product file.

DATA = BEAT_FETCH(BEAT_FILE_ID, <DATA SPEC ARGS>) reads the specified data element from the product file. Instead of just reading individual values, like strings, integers, doubles, etc. it is also possible to read complete arrays or records of data. For instance if 'pf' is a valid file handle, then you can read the complete MPH of this product (if it has one) with:

mph = beat_fetch(pf,'MPH')

which gives you a MATLAB struct containing all the MPH fields.

It is also possible to read an entire product at once by leaving the data specification argument list empty (product = beat_fetch(pf)).

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open. The format for the data specification argument list <data spec args> is described in a separate section.

See also BEAT_OPEN, DATA SPEC ARGS

BEAT_FIELDAVAILABLE

BEAT_FIELDAVAILABLE Find out whether a dynamically available record field is available or not.

IS_AVAILABLE = BEAT_FIELDAVAILABLE(BEAT_FILE_ID, <DATA SPEC ARGS>) returns 1 if the record field is available and 0 if it is not. The last item of the data specifier argument should point to a record field.

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open. The format for the data specification argument list <data spec args> is described in a separate section.

See also BEAT_FETCH, BEAT_OPEN, DATA SPEC ARGS

BEAT_FIELDCOUNT

BEAT_FIELDCOUNT Retrieve the number of fields for a record in a product file.

N = BEAT_FIELDCOUNT(BEAT_FILE_ID, <DATA SPEC ARGS>) returns the number of fields for the struct that would be returned if beat_fetch would have been called with the same arguments. The last item of the data specifier argument should point to a record.

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open. The format for the data specification argument list <data spec args> is described in a separate section.

See also BEAT_FETCH, BEAT_OPEN, DATA SPEC ARGS

BEAT_FIELDNAMES

BEAT_FIELDNAMES Retrieve a list of fieldnames for a record in a product file.

FIELDNAMES = BEAT_FIELDNAMES(BEAT_FILE_ID, <DATA SPEC ARGS>) returns a cellarray of strings of fieldnames for the struct that would be returned if beat_fetch would have been called with the same arguments. The last item of the data specifier argument should point to a record.

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open. The format for the data specification argument list <data spec args> is described in a separate section.

See also BEAT_FETCH, BEAT_OPEN, DATA SPEC ARGS

BEAT_GETOPT

BEAT_GETOPT Retrieve BEAT-I MATLAB options.

OPTIONS = BEAT_GETOPT returns a record with all available BEAT-I MATLAB options and their current values.

VALUE = BEAT_GETOPT(OPTION_NAME) will return the value of the specified option.

See also BEAT_SETOPT, BEAT-I MATLAB Options

BEAT_OPEN

BEAT_OPEN Open a product file.

BEAT_FILE_ID = BEAT_OPEN(FILEPATH) opens the product file pointed to by filepath. Upon successful opening the function returns a file handle that should be passed to other BEAT-I MATLAB functions that need to read data/information from this product file.

The filepath parameter must be a string containing the full path (or relative path with respect to the current working directory) of the product file.

See also BEAT_CLOSE, BEAT_CLEARALL

BEAT_PRODUCT_CLASS

BEAT_PRODUCT_CLASS Retrieve product class of a product file.

PRODUCT_CLASS = BEAT_PRODUCT_CLASS(BEAT_FILE_ID) returns a string containing the product class of the product.

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open.

See also BEAT_OPEN

BEAT_PRODUCT_TYPE

BEAT_PRODUCT_TYPE Retrieve product type of a product file.

PRODUCT_TYPE = BEAT_PRODUCT_TYPE(BEAT_FILE_ID) returns a string containing the product type of the product.

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open.

See also BEAT_OPEN

BEAT_PRODUCT_VERSION

BEAT_PRODUCT_VERSION Retrieve product version for a product file.

PRODUCT_VERSION = BEAT_PRODUCT_VERSION(BEAT_FILE_ID returns an integer denoting the product version, maintained by BEAT to be able to distinguish between different major versions of product specifications. The first supported version will yield 0, the next version will yield 1, and so on.

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open.

See also BEAT_OPEN

BEAT_SETOPT

BEAT_SETOPT Set BEAT-I MATLAB options.

BEAT_SETOPT(OPTION_NAME, VALUE) assigns VALUE to the option specified by OPTION_NAME.

See also BEAT_GETOPT, BEAT-I MATLAB Options

BEAT_SIZE

BEAT_SIZE Retrieve the dimensions for an array in a product file.

DIMS = BEAT_SIZE(BEAT_FILE_ID, <DATA SPEC ARGS>) returns the dimensions of the specified array. With beat_size you can check what the dimensions of an array will be without the need to retrieve it via beat_fetch. The returned dimension information is identical to what would be returned by size(beat_fetch(...)) if beat_size and beat_fetch had identical parameters. The last item of the data specifier argument should point to an array.

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open. The format for the data specification argument list <data spec args> is described in a separate section.

See also BEAT_FETCH, BEAT_OPEN, DATA SPEC ARGS

BEAT_TIME_TO_STRING

BEAT_TIME_TO_STRING Convert a number of seconds since 1-1-2000 to a human readable string format.

STR = BEAT_TIME_TO_STRING(N_SECONDS_SINCE_2000) turns the double value containing the number of seconds since 1-1-2000 into a string containing the date and time in a human readable string of the form '01-JAN-2000 00:00:00.000000'.

BEAT_UNIT

BEAT_UNIT Retrieve unit information.

UNIT = BEAT_UNIT(BEAT_FILE_ID, <DATA SPEC ARGS>) returns a string containing the unit information which is stored in the data dictionary for the specified data element.

The beat_file_id parameter must be a valid BEAT file handle that was retrieved with beat_open. The format for the data specification argument list <data spec args> is described in a separate section.

See also BEAT_FETCH, BEAT_OPEN, DATA SPEC ARGS

BEAT_VERSION

BEAT_VERSION Get version number of BEAT.

VERSION = BEAT_VERSION returns the version number of BEAT.

Data Specification Argument List

Several functions from the BEAT-I MATLAB interface take a data specification argument list to specify a certain data element in a product file. This argument list is a comma separated list of names and identifiers that allow you to walk to a certain point in a product. The list can be left empty if you want to point to the root of the product. There are two types of arguments you can use in the list of arguments:

• Array index: You need to provide an array index that has the same number of elements as there are dimensions in the array that you are refering to. So if the array is two dimensional you have to pass indices for both dimensions like [4 5]. If the array is one dimensional (like the datasets) you can just provide a single index value (without the '[]') to get to the k-th element. You can use beat_size to check the number of dimensions of an array and the size of each dimension.
• Field name: To go to a certain field inside the record that you are pointing to, you can provide the field name as a string (which is case sensitive, so you should make sure that the name is exactly the same as is returned by beat_fieldnames).

Note that all indices inside the data specification argument list go from 1..N (and not from 0..(N-1)).

For the beat_fetch function there is an additional feature. If you provide a -1 for one or more of the dimensions of an array you will fetch all elements in the specified dimension(s). For example, with beat_fetch(pf,'datasetname',-1,'dsr_time') you can fetch all dsr_time values for all measurements into a single array.

See also BEAT_CLASS, BEAT_FETCH, BEAT_FIELDNAMES, BEAT_SIZE

BEAT-I MATLAB Options

ConvertNumbersToDouble

If set to 0 then the BEAT-I MATLAB interface will, when reading data from a product file, use a matlab class that best matches the datatype of the data element in the product file (i.e. use 'int8' when the data is a one byte signed integer).

If set to 1 then the BEAT-I MATLAB interface will use the matlab class 'double' for all numbers that are read from a product file.

The default value for this option is: 1

FilterRecordFields

Records like for instance a Main Product Header contain fields that have a fixed value (fieldnames like 'PRODUCT=', quote characters, end of line characters, etc.) or are spare fields. If this option is set to 1 then these kinds of fields will be filtered out when retrieving a record from a product file. If this option is set to 0 then all fields will be returned.

The default value for this option is: 1

PerformConversions

The BEAT library has a global option that allows you to switch between reading data from a productfile in the way that it was exactly stored or in a more convenient way. For instance, sometimes floating point values with one digit precision are first multiplied by 10 and stored as an integer value in the product. If PerformConversions is set to 0 then BEAT will read this integer value, but if it is set to 1 then BEAT will first convert the integer back to a floating point value and divide it by 10 again. To see which fields of a product are effected by the PerformConversions option and what the conversion factor is look at the Data Dictionary documentation that came with BEAT.

You should also be aware that changing this option not only effects the result of BEAT_FETCH, but also the result of BEAT_CLASS (since this may, for instance, return 'single' instead of 'int16' if PerformConversions is set to 1) and BEAT_UNIT.

The default value for this option is: 1

Use64bitInteger

Some data elements in a product file are stored as 64bit integers. The BEAT-I MATLAB interface is able to read this data and return them to matlab with the not fully supported matlab classes 'int64' and 'uint64'. If you set Use64bitInteger to 0 then the BEAT-I MATLAB interface will convert the 64bit integer to a double and return the data with a matlab class 'double'.

Note that if ConvertNumbersToDouble is set to 1 then all integers will already be converted to doubles so in that case this option won't have any effect.

The default value for this option is: 0

UseMMap

By default BEAT uses a technique called 'memory mapping' to open and access data from product files. Using mmap greatly outperforms the default approach of reading data using the open()/read() combination. The downside of mapping a file into memory is that it takes away valuable address space. When you run a 32-bit Operating System your maximum addressable memory range is 4GB and if you simultaneously try to keep a few large product files open your memory space can quickly become full. Opening additional files will then produce 'out of memory' errors. Note that this 'out of memory' situation has nothing to do with the amount of RAM you have installed in your computer. It is only related to the size of a memory pointer on your system, which is limited to 4GB.

If you are using BEAT in a situation where you need to have multiple large product files open at the same time you can turn of the use of memory mapping by disabling this option. If you change the memory mapping option, the new setting will only be applicable for files that will be opened after you changed the option. Any files that were already open will keep using the mechanism with which they were opened.

The default value for this option is: 1

UseSpecialTypes

The BEAT Data Dictionary contains a series of special types that were introduced to make it easier for the user to read certain types of information. Examples of special types are the 'time', 'complex', 'geolocation', and 'no data' types. Each special data type is an abstraction on top of another non-special data type. Sometimes you want to access a file using just the non-special data types (e.g. if you want to get to the raw time data in a file). If you disable this option, the BEAT-I MATLAB interface will use the base type of a special type (and not the special type itself) when reading data or retrieving information about a data item. See the BEAT Data Dictionary documentation for more information about special types.

The default value for this option is: 1

See also BEAT_GETOPT, BEAT_SETOPT