CODA MATLAB

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

Contents

• CODA Definition Path
• Functions
  • CODA_ATTRIBUTES
  • CODA_CLASS
  • CODA_CLEARALL
  • CODA_CLOSE
  • CODA_DESCRIPTION
  • CODA_EVAL
  • CODA_FETCH
  • CODA_FIELDAVAILABLE
  • CODA_FIELDCOUNT
  • CODA_FIELDNAMES
  • CODA_GETOPT
  • CODA_OPEN
  • CODA_OPEN_AS
  • CODA_PRODUCT_CLASS
  • CODA_PRODUCT_TYPE
  • CODA_PRODUCT_VERSION
  • CODA_SETOPT
  • CODA_SIZE
  • CODA_TIME_TO_STRING
  • CODA_UNIT
  • CODA_VERSION
• Data Specification Argument List
• CODA MATLAB interface options

CODA Definition Path

Note that in order to access products whose formats are defined using .codadef files, you should let CODA now where these .codadef files are stored. By default the CODA MATLAB interface will look for .codadef files in a directory relative to the location of the CODA MATLAB MEX file (../../../share/coda/definitions; note that software that embed CODA may sometimes override this default location).

You can override the default location by setting the CODA_DEFINITION environment variable. This environment variable should be a ':' separated (';' on Windows) list of absolute paths to directories containing .codadef files or absolute paths to .codadef files themselves (or a mix of those).

Functions

The descriptions for each CODA MATLAB interface 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.

CODA_ATTRIBUTES

CODA_ATTRIBUTES Return object attributes.

C = CODA_ATTRIBUTES(CODA_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 coda_file_id parameter must be a valid CODA file handle that was retrieved with coda_open. The format for the data specification argument list <data spec args> is described in a separate section.

This function is deprecated. You can replace it by using CODA_FETCH(CODA_FILE_ID, <DATA SPEC ARGS>, "@").

See also CODA_FETCH, CODA_OPEN, DATA SPEC ARGS

CODA_CLASS

CODA_CLASS Return object class.

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

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

See also CODA_FETCH, CODA_OPEN, DATA SPEC ARGS

CODA_CLEARALL

CODA_CLEARALL Close all open product files and unload all cached product format definitions from memory.

CODA_CLEARALL will close all currently open product files (similar to calling coda_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 all product format definitions from memory. When coda_open is called, CODA will read the product format definition for the opened file and keeps this cached in memory. A call to coda_clearall will remove all cached definitions.

See also CODA_OPEN, CODA_CLOSE

CODA_CLOSE

CODA_CLOSE Close an open product file.

CODA_CLOSE(CODA_FILE_ID) closes the product file which is associated with the coda_file_id file handle.

The coda_file_id parameter must be a valid CODA file handle that was retrieved with coda_open.

See also CODA_OPEN, CODA_CLEARALL

CODA_DESCRIPTION

CODA_DESCRIPTION Retrieve field description.

DESC = CODA_DESCRIPTION(CODA_FILE_ID, <DATA SPEC ARGS>) returns a string containing the description in the product format definition 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 product format definition for this field.

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

See also CODA_FETCH, CODA_OPEN, DATA SPEC ARGS

CODA_EVAL

CODA_EVAL Evaluate a CODA expression.

RESULT = CODA_EVAL(CODA_EXPRESSION, [CODA_FILE_ID, <DATA SPEC ARGS>]) returns the evaluated CODA expression at the given product location.
The coda_expression parameter should be a string with a valid CODA expression. The syntax for the CODA expression language can be found in the CODA Expressions documentation.

If the CODA expression can be evaluated statically, then coda_file_id and <data spec args> are not required, otherwise these arguments are mandatory.
The coda_file_id parameter must be a valid CODA file handle that was retrieved with coda_open. The format for the data specification argument list <data spec args> is described in a separate section.

Note that evaluation of 'void' expressions is not supported.

See also CODA_FETCH, CODA_OPEN, DATA SPEC ARGS

CODA_FETCH

CODA_FETCH Retrieve data from a product file.

DATA = CODA_FETCH(CODA_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 or even the full product. For instance if 'pf' is a valid file handleand the product contains a dataset of records then you can retrieve a time field from the first record using:

value = coda_fetch(pf, "datasetname", 0, "time")

You can also combine the path into a single string parameter:

value = coda_fetch(pf, "datasetname[0]/time")

Which path to provide depends on the format of the product you are trying to access.

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, you could read the whole first record of the dataset using:

record = coda_fetch(pf, "datasetname", 0)

This gives you a MATLAB struct containing all the record fields.

It is also possible to read an entire product at once by leaving the data specification argument list empty:

product = coda_fetch(pf)

To read attributes, you can pass '@' as path element. For instance, the following command reads the 'units' attribute value from a temperature variable:

unit = coda_fetch(pf, "temperature@units")

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

See also CODA_OPEN, DATA SPEC ARGS

CODA_FIELDAVAILABLE

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

IS_AVAILABLE = CODA_FIELDAVAILABLE(CODA_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 coda_file_id parameter must be a valid CODA file handle that was retrieved with coda_open. The format for the data specification argument list <data spec args> is described in a separate section.

See also CODA_FETCH, CODA_OPEN, DATA SPEC ARGS

CODA_FIELDCOUNT

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

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

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

See also CODA_FETCH, CODA_OPEN, DATA SPEC ARGS

CODA_FIELDNAMES

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

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

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

See also CODA_FETCH, CODA_OPEN, DATA SPEC ARGS

CODA_GETOPT

CODA_GETOPT Retrieve CODA MATLAB interface options.

OPTIONS = CODA_GETOPT returns a record with all available CODA MATLAB interface options and their current values.

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

See also CODA_SETOPT, CODA MATLAB interface options

CODA_OPEN

CODA_OPEN Open a product file.

CODA_FILE_ID = CODA_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 CODA MATLAB interface 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 CODA_CLOSE, CODA_OPEN_AS, CODA_CLEARALL

CODA_OPEN_AS

CODA_OPEN_AS Open a product file using a specific format definition.

CODA_FILE_ID = CODA_OPEN_AS(FILEPATH, PRODUCT_CLASS, PRODUCT_TYPE, VERSION) will try to open the specified file for reading similar to CODA_OPEN, but instead of trying to automatically recognise the applicable product class/type/version as CODA_OPEN does, this function will impose the format definition that is associated with the given product_class, product_type, and version parameters.

Note that you normally won't need this function as CODA will be able to recognize which format definition to use automatically. However, for the rare occasions where CODA_OPEN is not sufficient, you can use this function to force the use of a specific format definition.

You can specify -1 for the version to request the latest available version of the format definition.

See also CODA_OPEN, CODA_CLOSE, CODA_CLEARALL

CODA_PRODUCT_CLASS

CODA_PRODUCT_CLASS Retrieve product class of a product file.

PRODUCT_CLASS = CODA_PRODUCT_CLASS(CODA_FILE_ID) returns a string containing the product class of the product.

The coda_file_id parameter must be a valid CODA file handle that was retrieved with coda_open.

See also CODA_OPEN

CODA_PRODUCT_TYPE

CODA_PRODUCT_TYPE Retrieve product type of a product file.

PRODUCT_TYPE = CODA_PRODUCT_TYPE(CODA_FILE_ID) returns a string containing the product type of the product.

The coda_file_id parameter must be a valid CODA file handle that was retrieved with coda_open.

See also CODA_OPEN

CODA_PRODUCT_VERSION

CODA_PRODUCT_VERSION Retrieve product version for a product file.

PRODUCT_VERSION = CODA_PRODUCT_VERSION(CODA_FILE_ID) returns an integer denoting the product version, maintained by CODA to be able to distinguish between different versions of product specifications.

The coda_file_id parameter must be a valid CODA file handle that was retrieved with coda_open.

See also CODA_OPEN

CODA_SETOPT

CODA_SETOPT Set CODA MATLAB interface options.

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

See also CODA_GETOPT, CODA MATLAB interface options

CODA_SIZE

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

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

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

See also CODA_FETCH, CODA_OPEN, DATA SPEC ARGS

CODA_TIME_TO_STRING

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

STR = CODA_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 '2000-01-01 00:00:00.000000'.

CODA_UNIT

CODA_UNIT Retrieve unit information.

UNIT = CODA_UNIT(CODA_FILE_ID, <DATA SPEC ARGS>) returns a string containing the unit information which is stored in the product format definition for the specified data element.

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

See also CODA_FETCH, CODA_OPEN, DATA SPEC ARGS

CODA_VERSION

CODA_VERSION Get version number of CODA.

VERSION = CODA_VERSION returns the version number of CODA.

Data Specification Argument List

Several functions from the CODA 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 three 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 referring 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 you can just provide a single index value (without the '[]') to get to the k-th element. You can use coda_size to check the number of dimensions of an array and the size of each dimension. Note that indices for an array index go from 1..N (and not from 0..(N-1)).
• 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 coda_fieldnames).
• Path: You can provide a string containing a path reference, such as "measurements[0]/time". Using paths will also allow you to navigate to attributes by using "@" as a path component. For instance, '"temperature", "@", "units"' or "temperature@units" will point to the units attribute of the temperature data. Note that array indices used in these string paths need to be 0-based indices on the flattened view of an array. This means that if an array is defined as having more than one dimension then the index as used in a path expression should be between 0 and the total number of array elements (exclusive). For example, for a [10 8] array, the index should be >= 0 and <= 79. For, instance coda_fetch(pf, 'variable', [1 1]) is equivalent to coda_fetch(pf, 'variable[0]')

For the coda_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 coda_fetch(pf, 'datasetname', -1, 'dsr_time') you can fetch all dsr_time values for all measurements into a single array. Note that passing -1 only works when passing it as an explicit argument (i.e. calling coda_fetch(pf, 'dataset[-1]/dsr_time'), where the -1 index is part of a string argument, will not work).

See also CODA_CLASS, CODA_EVAL, CODA_FETCH, CODA_FIELDNAMES, CODA_SIZE

CODA MATLAB interface options

ConvertNumbersToDouble

If set to 0 then the CODA 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 CODA 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

Some records contain fields that have a fixed value 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 CODA library has a global option that allows you to switch between reading data from a product 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 CODA will read this integer value, but if it is set to 1 then CODA 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 corresponding CODA Product Format Definition documentation.

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

The default value for this option is: 1

SwapDimensions

If set, CODA will swap the dimensions of multi-dimensional arrays (i.e. performing a multi-dimensional transpose on the data) so the array dimensions that are found in e.g. the CODA format definitions can be used as-is on the data. This distinction is needed because MATLAB uses Fortran-style ordering for array indices whereas CODA uses C-style array dimensioning ordering as the standard.

If you disable this option, CODA will no longer transpose the data itself, but will invert the ordering of the array indices you pass to e.g. CODA_FETCH and the dimension sizes that are returned by CODA_SIZE.

The default value for this option is: 1

Use64bitInteger

Some data elements in a product file are stored as 64bit integers. The CODA 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 CODA 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 CODA 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 CODA 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 CODA type system 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', 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, CODA 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 CODA Product Format Definition documentation for more information about special types.

The default value for this option is: 1

See also CODA_GETOPT, CODA_SETOPT