Skip to content

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,
    export_timestamp_type: _AnyExportableTimestampType = "iso_8601",
    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,
    export_timestamp_type: _AnyExportableTimestampType = "iso_8601",
    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,
    export_timestamp_type: _AnyExportableTimestampType = "iso_8601",
    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,
    export_timestamp_type: _AnyExportableTimestampType = "iso_8601",
    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.

  • export_timestamp_type ¤

    (_AnyExportableTimestampType, default: 'iso_8601' ) –

    Format of exported timestamps. Defaults to string-based iso8601 timestamps.

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