BEAT-II Python
The BEAT-II Python interface consists of a Python package ‘beatl2’ containing a 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 Python interface.
Contents
Initialisation
BEAT-II uses CODA for reading data from atmospheric data products. When you import the BEAT-II Python package this will also trigger an initialisation of CODA. Part of this initialisation is that CODA will search its definition path for all .codadef Product Format Definition files. For the Python interface you will normally have to set this definition path manually. If you try to ingest data and the location is not set properly, BEAT-II will give you the error -2204 'BEAT could not automatically recognize the type of this product' for products that should normally be supported.
To specify the definition search path you can set the CODA_DEFINITION environment variable before you import the BEAT-II Python package (see also the CODA Python documentation). Setting the environment variable can be performed from within Python using:
import os
os.putenv('CODA_DEFINITION', '<your codadef search path>')
# ...
import beatl2
For the search path you should use the location of the .codadef files as provided with your BEAT installation. The files are installed in '<prefix>/share/beat/definitions' on Unix based systems and in '<prefix>/definitions' on Windows (where <prefix> is the location where you installed BEAT).
BEAT-II Record Class
beatl2.Record
The class 'Record' is provided as the basic data structure. Manipulation of Records is done through module-level functions that mimic the BEAT-II interfaces found in other high-level environments such as IDL and MATLAB.
In addition, Record objects offer a number of Python-specific convenience methods (for e.g. printing and copying), and can be manipulated using standard Python language constructs.
Sample usage:
import beatl2 filename = '/tmp/gomos-l2.gom' rec = beatl2.ingest(filename) slicedrec = beatl2.slice_data(rec, None, range(10)) beatl2.export_data('ascii', '/tmp/gomos-slice.asc', slicedrec)
Functions
beatl2.append
Append two BEAT-II records.
>>> record = beatl2.append(record_1, record_2)
will append record_2 to record_1 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.export_data
Export a BEAT-II record to a file.
>>> export_data(format, filepath, record)
will export the given beatl2 Record 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. If the export file already exists it will be overwritten.
See also beatl2.import_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 in 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 distance parameters are negative and/or the records have no fields to match on) the function will return an error.
Both records should be of a valid type.
More information about BEAT-II records can be found in the BEAT-II Data Description documentation.
beatl2.import_data
Import a BEAT-II record from a file.
>>> record = beatl2.import_data(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_data.
See also beatl2.export_data.
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 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, provide either a Python list of strings, or a single pattern string containing Unix shell-like wildcards. The string will be processed by the Python glob.glob() routine and converted to a list of filenames matching the pattern. If there are no files matching the pattern you will get an error.
All product files should be of the same product type for the ingestion to succeed.
The filter parameter 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_data
Shrink a BEAT-II record to a subrange of its data.
>>> outrecord = beatl2.slice(inrecord, dimension, indexrange)
will shrink the inrecord in the given dimension (which should be a sub-dimension of the main dimension; use the None value for the dimension parameter if you want to slice in the main dimension).
The range should be a range of integers representing the indices (with regard to the main dimension) of the elements that should be kept.
More information about BEAT-II records can be found in the BEAT-II Data Description documentation.
beatl2.version
Get version number of BEAT.
>>> version = beatl2.version()
returns the version number of the current BEAT release.