BEAT-I Python

The BEAT-I Python interface consists of a Python package 'beat' containing several functions that allow the user to easily access data inside product files.

The BEAT-I Python interface contains both a wrapping of the BEAT-I C library interface as well as a version of the higher level BEAT-I functions as can be found in the IDL and MATLAB interfaces of BEAT.

Initialisation of BEAT
High level BEAT-I Data Types
High level BEAT-I Functions
Low level BEAT-I Data Types
Low level BEAT-I Functions

Initialisation of BEAT

When you import the BEAT-I Python package this will trigger an initialisation of CODA. Part of this initialisation is that CODA will search its definition path for all .codadef Product Format Definition files. In order to specify where CODA will look for its .codadef files you can set the CODA_DEFINITION environment variable before you import the BEAT-I Python package. Setting the environment variable can be performed from within Python using:

import os

os.putenv('CODA_DEFINITION', '<your codadef search path>')

# ...

import coda

High level BEAT-I Data Types

When reading data from a product file, BEAT will use the following mapping to translate the ingested data into Python data structures:

BEAT class BEAT read type / BEAT special type Python data type

record beat.Record

array

This will be a numpy array (numpy.array) object. The following table relates the BEAT array base type to the numpy base type:

BEAT class	BEAT read type / BEAT special type	numpy base type
record		Python object (`beat.Record`)
array		Python object (a `numpy.array` object)
integer	int8	int8
integer	uint8	uint8
integer	int16	int16
integer	uint16	uint16
integer	int32	int32
integer	uint32	uint32
integer	int64	int64
integer	uint64	uint64
real	float	float32
real	double	float64
text	char	Python object (the Python object is a Python String of length 1)
text	string	Python object (Python String)
raw	bytes	Python object (`numpy.array` object with base type uint8)
special	no_data	Python object (`None`)
special	time	float64
special	complex	complex64
special	geolocation	A record object (`beat.Record`) containing two Float64 fields called 'latitude' and 'longitude'.

integer int8 Python Integer

integer uint8 Python Integer

integer int16 Python Integer

integer uint16 Python Integer

integer int32 Python Integer

integer uint32 Python Long

integer int64 Python Long

integer uint64 Python Long

real float Python Float

real double Python Float

text char Python String

text string Python String

raw bytes numpy.array object with base type uint8

special no_data None

special time Python Float

special complex Python Complex Number

special geolocation numpy.array object with base type float64. The array contains 2 elements with the first being the latitude and the second the longitude.

High level BEAT-I Functions

Most high level BEAT-I functions require a start and path parameter. These two parameters together define the location of a data item in a product.

The start parameter determines the offset in the product from which the path parameter is expanded. It can either be a file handle or a BEAT Cursor (see Low level BEAT-I Data Types). When a file handle is passed we start at the root of the product and when it is a cursor we start at the position of the cursor.

The path argument is actually a series of parameters (which can also be empty). Starting from the start position, the path parameters should provide valid fieldnames and array indices to navigate deeper into the product. For example, suppose we have a product that has a measurements data set with 100 data set records and in each data set record there is a time field containing a time value of type double. If we want to read the time value in the first data set record (using the file handle filehandle as start parameter) we would use: beat.fetch(filehandle, "measurements", 0, "time"). However, it is also possible to read several data elements at once. We can for instance read the full data set record using beat.fetch(filehandle, "measurements", 0) or even read the whole product using beat.fetch(filehandle). When you read a group of data at once, BEAT will create a dynamic data structure in Python (consisting of beat.Record and numpy.array objects to represent records and arrays) for the product data that is read.

The two types of arguments that you can use in the list of arguments for path are:

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.get_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, just provide the field name as a string. You should be aware that some record fields can be dynamically available. In such cases it is better to check in advance (using beat.get_field_available) whether the field is available, before traversing it.

Just as the low level functions, the high level BEAT-I Python functions will throw an exception when an error condition occurs. For the high level functions the exception will be of type beat.BeatError.

`beat.open(filename)`

This function opens a file and returns a handle to the opened product file.

The high and lowel level beat.open functions are actually one and the same. You can thus use the product file handle that is returned by beat.open both as start parameter in the high level BEAT-I functions mentioned below as well as pf parameter in the low level BEAT-I functions.

`beat.close(filehandle)`

This function closes the file associated with the file handle filehandle.

Just as the beat.open function, the high and lowel level beat.close functions are one and the same.

`beat.get_attributes(start, *path)`

Retrieve the attributes of the specified data item.

This function returns a beat.Record containing the attributes of the specified data item.

The start parameter must be a valid BEAT file handle that was retrieved with beat.open() or a valid BEAT Cursor. If the start argument is a cursor, then the specified path is traversed starting from the position represented by the cursor. The format of the path argument is described at the top of this section.

`beat.get_description(start, *path)`

Retrieve the description of a field.

This function returns a string containing the description in the data dictionary of the specified data element.

`beat.fetch(start, *path)`

Retrieve data from a product file.

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 product file handle obtained by calling beat.open(), then you can read the complete MPH of a product with:

>>> mph = beat.fetch(pf, 'mph')

which gives you a beat.Record 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)).

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.

`beat.get_field_available(start, *path)`

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

This function returns True if the record field is available and False if it is not. The last item of the path argument should point to a record field. An empty path is considered an error, even if the start argument is a BEAT cursor.

`beat.get_field_count(start, *path)`

Retrieve the number of fields in a record.

This function returns the number of fields in the beat.Record instance that will be returned if beat.fetch() is called with the same arguments. The last node on the path should reference a record.

`beat.get_field_names(start, *path)`

Retrieve the names of the fields in a record.

This function returns the names of the fields in the beat.Record instance that will be returned if beat.fetch() is called with the same arguments. The last node on the path should reference a record.

`beat.get_size(start, *path)`

Retrieve the dimensions of the specified array.

This function returns the dimensions of the array that will be returned if beat.fetch() is called with the same arguments. Thus, you can check what the dimensions of an array are without having to retrieve the entire array with beat.fetch(). The last node on the path should reference an array.

`beat.time_to_string(n_seconds_since_2000)`

Convert a number of seconds since 1-1-2000 to a human readable string format. For example:

>>> beat.time_to_string(68260079.0)

would return the string '01-MAR-2002 01:07:59.000000'.

It is possible to input a list or tuple of doubles, in which case a list of strings will be returned.

`beat.get_unit(start, *path)`

Retrieve unit information.

This function returns a string containing the unit information which is stored in the data dictionary for the specified data item.

`beat.version()`

Retrieve BEAT version information.

This function returns a string containing the version number of BEAT. The version number is always of the format 'x.y.z', i.e., major, minor, and revision numbers, separated by dots.

`beat.set_option_filter_record_fields(enable)`

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 (using e.g. beat.fetch). If this option is set to 0 then all fields will be returned.

The default value for this option is: 1

This option only effects the higher level BEAT-I Python functions. The lower level functions do not perform filtering on record fields.

`beat.get_option_filter_record_fields()`

Retrieve the current setting for filtering of record fields.

Low level BEAT-I Data Types

Just as in the C interface the beat_ProductFile, beat_Type, and beat_Cursor types are opaque types. This means that you can not print or inspect these types, but can only pass them around.

To create a new BEAT Cursor there is a special beat.Cursor class from which you instantiate new Cursor objects (these objects are opaque wrappers of the underlying cursors in the C domain). You can create a new cursors with: cursor = beat.Cursor(). After creation you will have to initialize it using the beat.cursor_set_product function (just like in C). It is possible to create a copy of a BEAT Cursor by using a so-called deep copy:

import copy
cursor = beat.Cursor()
cursor2 = copy.deepcopy(cursor)

Low level BEAT-I Functions

For a description of all low level BEAT-I functions please consult the BEAT-I C library (libbeat) documentation. There are a few differences between the Python and C interface with respect to certain parameters and error handling. Below you will find an overview of the calling signature for each of the supported low level BEAT-I functions. You'll notice that most differences are rather straightforward (parameters have moved from the parameter list to the list of return values or have been removed). If a change requires more explanation a remark is added to the function definition.

The low level BEAT-I Python functions do not return error codes to indicate succes or failure (as is the case for the C functions). If an error condition occurs, an exception (of type beat.BeatcError) will be thrown. You can catch this exception using e.g.:

try:
    # call your BEAT function(s) here
except beat.BeatcError, e:
    # handle BEAT-specific exception
    print "ERROR: %s" % e

If you do not catch the exception, the error message will be printed to the console.

`beat.init()`

You do not have to call this function yourself to initialize BEAT. When BEAT is imported in Python the init function will already be called for you. If, however, you call beat.done at any time, you can use this function to re-initialize BEAT again.

`beat.done()`

If, for some reason, you want to unload the BEAT package, you should first clean up BEAT by calling this function. However, unloading a Python package is not a common activity, so you should rarely have to call beat.done().

`beat.set_option_bypass_special_types(enable)`

`beat.get_option_bypass_special_types()`

`beat.set_option_perform_boundary_checks(enable)`

`beat.get_option_perform_boundary_checks()`

`beat.set_option_perform_conversions(enable)`

`beat.get_option_perform_conversions()`

`beat.set_option_use_fast_size_expressions`

`beat.get_option_use_fast_size_expressions`

`beat.set_option_use_mmap`

`beat.get_option_use_mmap`

`beat.NaN()`

`beat.isNaN(x)`

`beat.PlusInf()`

`beat.MinInf()`

`beat.isInf(x)`

`beat.isPlusInf(x)`

`beat.isMinInf(x)`

`beat.c_index_to_fortran_index(num_dims, dim, index)`

`datetime = beat.datetime_to_double(YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, MUSEC)`

`[YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, MUSEC] = beat.double_to_datetime(datetime)`

`beat.month_to_integer(month)`

`utc_string = beat.get_utc_string_from_time(time)`

`time = beat.get_time_from_string(str)`

`beat.match_filefilter(filter, filepaths, callbackfunc)`

The callbackfunc parameter should be a Python function that accepts filepath, status and error as parameters. For example:

>>> def findhelper(filepath, status, error):
...     if status == beat.beat_ffs_match:
...         print "File %s matches filter!" % filepath    
...     elif ((status == beat.beat_ffs_unsupported_file)
...         or (status == beat.beat_ffs_no_match)
...         or (status == beat.beat_ffs_undetermined_match)):
...         # don't print anything if the file does not positively match the filter
...         pass
...     else:
...         print "ERROR: %s (%s)" % (error, filepath)
...     return 0
>>> beat.match_filefilter('', '/home/beatuser', findhelper)

`[product_class, product_type, product_version, file_size] = beat.recognize_file(filename)`

`pf = beat.open(filename)`

The product file handle returned by this function can also be used with the high level BEAT-I functions.

`beat.close(pf)`

`filename = beat.get_product_filename(pf)`

`file_size = beat.get_product_file_size(pf)`

`product_class = beat.get_product_class(pf)`

`product_type = beat.get_product_type(pf)`

`version = beat.get_product_version(pf)`

`type = beat.get_product_root_type(pf)`

`backend = beat.get_product_backend(pf)`

`value = beat.get_product_variable_value(pf, variable, index)`

`beat.type_get_class_name(type_class)`

`beat.type_get_native_type_name(native_type)`

`beat.type_get_special_type_name(special_type)`

`has_ascii_content = beat.type_has_ascii_content(type)`

`has_xml_content = beat.type_has_xml_content(type)`

`type_class = beat.type_get_class(type)`

`read_type = beat.type_get_read_type(type)`

`length = beat.type_get_string_length(type)`

`bit_size = beat.type_get_bit_size(type)`

`name = beat.type_get_name(type)`

`description = beat.type_get_description(type)`

`unit = beat.type_get_unit(pf)`

`fixed_value = beat.type_get_fixed_value(pf)`

`num_fields = beat.type_get_num_record_fields(type)`

`index = beat.type_get_record_field_index_from_name(type, name)`

`field_type = beat.type_get_record_field_type(type, index)`

`name = beat.type_get_record_field_name(type, index)`

`hidden = beat.type_get_record_field_hidden_status(type, index)`

`available = beat.type_get_record_field_available_status(type, index)`

`is_union = beat.type_get_record_union_status(type)`

`num_dims = beat.type_get_array_num_dims(type)`

`dim = beat.type_get_array_dim(type)`

`base_type = beat.type_get_array_base_type(type)`

`special_type = beat.type_get_special_type(type)`

`base_type = beat.type_get_special_base_type(type)`

`beat.cursor_set_product(cursor, product)`

You can create a new cursor with cursor = beat.Cursor(). With beat.cursor_set_product this cursor can then be initialized to the root of a product. It is also possible to use a cursor as start parameter in the high level BEAT-I functions.

`beat.cursor_goto_first_record_field(cursor)`

`beat.cursor_goto_next_record_field(cursor)`

`beat.cursor_goto_record_field_by_index(cursor, index)`

`beat.cursor_goto_record_field_by_name(cursor, name)`

`beat.cursor_goto_available_union_field(cursor)`

`beat.cursor_goto_first_array_element(cursor)`

`beat.cursor_goto_next_array_element(cursor)`

`beat.cursor_goto_array_element(cursor, subs)`

It is not needed to provide the number of dimensions as a parameter (num_subs) since this value is determined from inspecting the length of subs.

`beat.cursor_goto_array_element_by_index(cursor, index)`

`beat.cursor_goto_attributes(cursor)`

`beat.cursor_goto_root(cursor)`

`beat.cursor_goto_parent(cursor)`

`beat.cursor_use_base_type_of_special_type(cursor)`

`has_ascii_content = beat.cursor_has_ascii_content(cursor)`

`has_xml_content = beat.cursor_has_xml_content(cursor)`

`length = beat.cursor_get_string_length(cursor)`

`bit_size = beat.cursor_get_bit_size(cursor)`

`byte_size = beat.cursor_get_byte_size(cursor)`

`num_elements = beat.cursor_get_num_elements(cursor)`

`pf = beat.cursor_get_product_file(cursor)`

`depth = beat.cursor_get_depth(cursor)`

`index = beat.cursor_get_index(cursor)`

`bit_offset = beat.cursor_get_file_bit_offset(cursor)`

`byte_offset = beat.cursor_get_file_byte_offset(cursor)`

`type_class = beat.cursor_get_type_class(cursor)`

`read_type = beat.cursor_get_read_type(cursor)`

`special_type = beat.cursor_get_special_type(cursor)`

`type = beat.cursor_get_type(cursor)`

`index = beat.cursor_get_record_field_index_from_name(cursor, name)`

`available = beat.cursor_get_record_field_available_status(cursor, index)`

`index = beat.cursor_get_available_union_field_index(cursor)`

`dim = beat.cursor_get_array_dim(cursor)`

`dst = beat.cursor_read_int8(cursor)`

`dst = beat.cursor_read_uint8(cursor)`

`dst = beat.cursor_read_int16(cursor)`

`dst = beat.cursor_read_uint16(cursor)`

`dst = beat.cursor_read_int32(cursor)`

`dst = beat.cursor_read_uint32(cursor)`

`dst = beat.cursor_read_int64(cursor)`

`dst = beat.cursor_read_uint64(cursor)`

`dst = beat.cursor_read_float(cursor)`

`dst = beat.cursor_read_double(cursor)`

`dst = beat.cursor_read_char(cursor)`

Since Python does not have a native char type the character data will be returned as a string of length 1.