matlab

export_channels_to_matlab

export_channels_to_matlab(
    client: NominalClient,
    output_path: Path,
    channels: Sequence[Channel],
    *,
    start_time: _InferrableTimestampType | None = None,
    end_time: _InferrableTimestampType | None = None,
    resolution: IntegralNanosecondsDuration,
    relative_to: datetime | IntegralNanosecondsUTC | None = None,
    relative_resolution: _LiteralTimeUnit = "nanoseconds",
    forward_fill_lookback: IntegralNanosecondsDuration | None = None,
    chunk_size: int = DEFAULT_CHUNK_SIZE
) -> None

export_channels_to_matlab(
    client: NominalClient,
    output_path: Path,
    channels: Sequence[Channel],
    *,
    start_time: _InferrableTimestampType | None = None,
    end_time: _InferrableTimestampType | None = None,
    num_buckets: int,
    relative_to: datetime | IntegralNanosecondsUTC | None = None,
    relative_resolution: _LiteralTimeUnit = "nanoseconds",
    forward_fill_lookback: IntegralNanosecondsDuration | None = None,
    chunk_size: int = DEFAULT_CHUNK_SIZE
) -> None

export_channels_to_matlab(
    client: NominalClient,
    output_path: Path,
    channels: Sequence[Channel],
    *,
    start_time: _InferrableTimestampType | None = None,
    end_time: _InferrableTimestampType | None = None,
    relative_to: datetime | IntegralNanosecondsUTC | None = None,
    relative_resolution: _LiteralTimeUnit = "nanoseconds",
    forward_fill_lookback: IntegralNanosecondsDuration | None = None,
    chunk_size: int = DEFAULT_CHUNK_SIZE
) -> None

export_channels_to_matlab(
    client: NominalClient,
    output_path: Path,
    channels: Sequence[Channel],
    *,
    tags: Mapping[str, str] | None = None,
    start_time: _InferrableTimestampType | None = None,
    end_time: _InferrableTimestampType | None = None,
    resolution: IntegralNanosecondsDuration | None = None,
    num_buckets: int | None = None,
    relative_to: datetime | IntegralNanosecondsUTC | None = None,
    relative_resolution: _LiteralTimeUnit = "nanoseconds",
    forward_fill_lookback: IntegralNanosecondsDuration | 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) –

  The Nominal client used to issue the data export request

• output_path

  (Path) –

  Location on disk to write the resulting .mat file. NOTE: The parent directory will be created if it does not already exist. NOTE: Must have a .mat suffix.

• channels

  (Sequence[Channel]) –

  List of channels to export. NOTE: Must be non-empty.

• tags

  (Mapping[str, str] | None, default: None ) –

  Optional dictionary of tags to apply when exporting each channel.

• start_time

  (_InferrableTimestampType | None, default: None ) –

  The minimum timestamp to include in the export. NOTE: If not provided, uses the earliest available timestamp.

• end_time

  (_InferrableTimestampType | None, default: None ) –

  The maximum timestamp to include in the export. NOTE: If not provided, uses the latest available timestamp.

• resolution

  (IntegralNanosecondsDuration | None, default: None ) –

  Fixed resolution (in nanoseconds) to downsample the export data. NOTE: Mutually exclusive with num_buckets.

• num_buckets

  (int | None, default: None ) –

  Number of buckets to aggregate the selected time window into. NOTE: Mutually exclusive with resolution.

• relative_to

  (datetime | IntegralNanosecondsUTC | None, default: None ) –

  If provided, output timestamps will be relative to this epoch time. Otherwise, absolute timestamps will be used.

• relative_resolution

  (_LiteralTimeUnit, default: 'nanoseconds' ) –

  If exporting relative timestamps, the time unit to use.

• forward_fill_lookback

  (IntegralNanosecondsDuration | None, default: 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, default: DEFAULT_CHUNK_SIZE ) –

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

Raises:

• ValueError –

  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

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

# Export with fixed resolution (100ms) and relative timestamps in microseconds
export_channels_to_matlab(
    client,
    pathlib.Path("out/resampled.mat"),
    [channel_a, channel_b],
    resolution=100_000_000,
    relative_to=datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone.utc),
    relative_resolution="microseconds",
)

# Export bucketed data with forward fill up to 5 seconds
export_channels_to_matlab(
    client,
    pathlib.Path("out/bucketed.mat"),
    [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` 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.