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
.matfile. NOTE: The parent directory will be created if it does not already exist. NOTE: Must have a.matsuffix. -
(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
resolutionandnum_bucketsare specified, or if the output path does not have a.matsuffix.
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.