# export_channels_to_matlab

## nominal.thirdparty.matlab.export_channels_to_matlab(client: NominalClient, output_path: Path, channels: Sequence[Channel], *, start_time: str | datetime | int | None = None, end_time: str | datetime | int | None = None, resolution: int, export_timestamp_type: Iso8601 | Epoch | Relative | Literal['iso_8601', 'epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days'] = 'iso_8601', forward_fill_lookback: int | None = None, chunk_size: int = DEFAULT_CHUNK_SIZE) → None

## nominal.thirdparty.matlab.export_channels_to_matlab(client: NominalClient, output_path: Path, channels: Sequence[Channel], *, start_time: str | datetime | int | None = None, end_time: str | datetime | int | None = None, num_buckets: int, export_timestamp_type: Iso8601 | Epoch | Relative | Literal['iso_8601', 'epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days'] = 'iso_8601', forward_fill_lookback: int | None = None, chunk_size: int = DEFAULT_CHUNK_SIZE) → None

## nominal.thirdparty.matlab.export_channels_to_matlab(client: NominalClient, output_path: Path, channels: Sequence[Channel], *, start_time: str | datetime | int | None = None, end_time: str | datetime | int | None = None, export_timestamp_type: Iso8601 | Epoch | Relative | Literal['iso_8601', 'epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days'] = 'iso_8601', forward_fill_lookback: int | None = None, chunk_size: int = DEFAULT_CHUNK_SIZE) → None

Export one or more channels to a MATLAB `mat` file on disk.

This function requests a server-side export of the given channels over a specified
time range, and streams the result directly to the provided output path. The export
is returned from the API as a gzip-compressed byte stream, which is decompressed
on the fly and written to disk without loading the full dataset into memory.

Parameters:
:   - **client** ([*NominalClient*](https://dev.nominal.io/python/ref/generated/nominal.core.NominalClient.md#nominal.core.NominalClient "nominal.core.client.NominalClient"))

      The Nominal client used to issue the data export request
    - **output_path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)"))

      Location on disk to write the resulting `mat` file.

      **Note:** The parent directory will be created if it does not already exist.

      Must have a `mat` suffix.
    - **channels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*Channel*](https://dev.nominal.io/python/ref/generated/nominal.core.Channel.md#nominal.core.Channel "nominal.core.channel.Channel")*]*)

      List of channels to export.

      **Note:** Must be non-empty.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Optional dictionary of tags to apply when exporting each channel.
    - **start_time** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      The minimum timestamp to include in the export.

      **Note:** If not provided, uses the earliest available timestamp.
    - **end_time** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      The maximum timestamp to include in the export.

      **Note:** If not provided, uses the latest available timestamp.
    - **resolution** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Fixed resolution (in nanoseconds) to downsample the export data.

      **Note:** Mutually exclusive with `num_buckets`.
    - **num_buckets** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Number of buckets to aggregate the selected time window into.

      **Note:** Mutually exclusive with `resolution`.
    - **export_timestamp_type** ([*Iso8601*](https://dev.nominal.io/python/ref/generated/nominal.ts.Iso8601.md#nominal.ts.Iso8601 "nominal.ts.Iso8601") *|* [*Epoch*](https://dev.nominal.io/python/ref/generated/nominal.ts.Epoch.md#nominal.ts.Epoch "nominal.ts.Epoch") *|* [*Relative*](https://dev.nominal.io/python/ref/generated/nominal.ts.Relative.md#nominal.ts.Relative "nominal.ts.Relative") *|* [*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'iso_8601'**,* *'epoch_picoseconds'**,* *'epoch_nanoseconds'**,* *'epoch_microseconds'**,* *'epoch_milliseconds'**,* *'epoch_seconds'**,* *'epoch_minutes'**,* *'epoch_hours'**,* *'epoch_days'**]*)

      Format of exported timestamps. Defaults to string-based iso8601 timestamps.
    - **forward_fill_lookback** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      If provided, enables forward-filling of values at timestamps
      where data is missing, up to the given lookback duration. If not provided,
      missing values are left empty.
    - **chunk_size** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      Size in bytes of the buffer used while streaming the decompressed
      export to disk. Defaults to 1 MiB.

Exceptions raised by the underlying API client or file I/O operations
(e.g. network errors, filesystem errors) propagate to the caller.

Raises:
:   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If no channels are provided, if both `resolution` and `num_buckets`
    are specified, or if the output path does not have a `mat` suffix.

Example

```python
# Export undecimated data over a given time range
export_channels_to_matlab(
    client=client,
    output_path=pathlib.Path("out/my_export.mat"),
    channels=[channel_a, channel_b],
    start_time=datetime.datetime(2024, 1, 1, tzinfo=datetime.UTC),
    end_time=datetime.datetime(2024, 2, 1, tzinfo=datetime.UTC),
)

# Export with fixed resolution (100ms) and relative timestamps in microseconds
export_channels_to_matlab(
    client=client,
    output_path=pathlib.Path("out/resampled.mat"),
    channels=[channel_a, channel_b],
    resolution=100_000_000,
    export_timestamp_type=Relative(
        "microseconds", datetime.datetime(1970, 1, 1, tzinfo=datetime.UTC)
    ),
)

# Export with original resolution but timestamps as seconds since unix epoch
export_channels_to_matlab(
    client=client,
    output_path=pathlib.Path("out/epoch_seconds.mat"),
    channels=[channel_a, channel_b],
    export_timestamp_type="epoch_seconds",
)

# Export bucketed data with forward fill up to 5 seconds
export_channels_to_matlab(
    client=client,
    output_path=pathlib.Path("out/bucketed.mat"),
    channels=[channel_a, channel_b, channel_c],
    num_buckets=3600,
    forward_fill_lookback=5_000_000_000,
)
```

Usage in MATLAB:
:   Once the `mat` file is generated, you can load it directly into MATLAB using
    the built-in `load` function or by double-clicking the file in the MATLAB UI:

    ```matlab
    >> result = load("out/my_export.mat");
    ```

    The result contains a struct named `data`, where each field corresponds to a
    channel exported from Nominal, represented as a numeric array. You can convert
    this struct to a MATLAB table using `struct2table` for easier manipulation:

    ```matlab
    >> T = struct2table(result.data);
    ```

    If any channel name contains characters that are not valid MATLAB identifiers
    (for example, a period `"."`), you can still access it safely using the dynamic
    field reference syntax in either the struct or table form:

    ```matlab
    >> data.("channel.name")
    >> T.("channel.name")
    ```

    If your export includes timestamps as ISO-8601 strings, they will often appear
    as a cell array of character vectors in the table. You can convert them into
    native MATLAB [`datetime`](https://docs.python.org/3/library/datetime.html#module-datetime "(in Python v3.15)") objects like so (replace `timestamps` with the actual
    field name if different):

    ```matlab
    % Normalize timestamps to always include a fractional second then convert to utc datetime
    >> T.timestamps = datetime( ...
        regexprep(T.timestamps, ':(\d{2})Z$', ':$1.000000Z'), ...
        'InputFormat', ...
        'yyyy-MM-dd''T''HH:mm:ss.SSSSSS''Z''', ...
        'TimeZone', ...
        'UTC');
    ```

    After this conversion, you can use MATLAB’s native time-series and plotting
    functions directly on the `timestamps` column.