# 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 (`../definitions` on Windows and `../../../share/coda/definitions` on other systems; 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 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 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`