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 – The Nominal client used to issue the data export request

  • output_path – 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 – List of channels to export.

    Note: Must be non-empty.

  • tags – Optional dictionary of tags to apply when exporting each channel.

  • start_time – The minimum timestamp to include in the export.

    Note: If not provided, uses the earliest available timestamp.

  • end_time – The maximum timestamp to include in the export.

    Note: If not provided, uses the latest available timestamp.

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

    Note: Mutually exclusive with num_buckets.

  • num_buckets – Number of buckets to aggregate the selected time window into.

    Note: Mutually exclusive with resolution.

  • export_timestamp_type – Format of exported timestamps. Defaults to string-based iso8601 timestamps.

  • forward_fill_lookback – 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 – 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 – 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=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:

>> 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:

>> 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:

>> 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):

% 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.