Dataset

class nominal.Dataset

Time-aligned access to test data, exposing many channels.

Obtained from an asset or a client:

ds = a.getOrCreateDataset("telemetry", "tlm");
ds = c.datasetByRid(rid);
ds = c.createDataset("shared");      % attached to nothing

Streaming into it:

s = ds.stream();

See also

nominal.Asset, nominal.Stream

Constructor Summary

Property Summary

Rid

Resource identifier.

Name

Display name.

Description

Description, or “” if it has none.

Labels

All labels, as a string array.

Properties

All properties, as a containers.Map.

Method Summary

property(key)

Value of one property. Errors if the key is absent.

Returns:

string – The property’s value.

setProperty(key, value)

Set one property, keeping the rest.

ds = ds.setProperty("script", "reduce_flight.m");

Re-reads the dataset first, so properties set since this object was fetched are kept.

Returns:

nominal.Dataset – The updated dataset.

removeProperty(key)

Remove one property, keeping the rest.

Errors if the dataset has no such property.

Returns:

nominal.Dataset – The updated dataset.

assets()

Every asset this dataset is attached to, as a table.

An asset holding the dataset more than once, under different tags, is listed once.

Returns:

table – Variables Name, Rid and Description, ordered by name.

See also

nominal.Asset.addDataset()

stream()

Open a stream that writes into this dataset.

Data is buffered and sent in the background. Deleting the stream, or clearing its last variable, flushes it. Call delete(s) to flush at a known point.

Returns:

nominal.Stream – The open stream.

See also

nominal.Stream

write(channels, timestamps, values, options)

Send a block of samples in one call, with no stream.

ds.write(["rpm" "egt"], t, V)
ds.write(["rpm" "egt"], t, V, Tags=struct(UUT="A"))

Returns once Nominal has accepted the write, with nothing to flush or close. Use this for data already in memory, and stream() for continuous acquisition.

Keep a call to roughly 50,000 points and at most 10 channels. Past that, use a stream.

Parameters:

• channels

  1-by-C string array of channel names.

• timestamps

  N-by-1 int64 nanoseconds, or a datetime vector. Literal, including zero.

• values

  N-by-C double, one column per channel.

Options:

Tags – Stamped on every point written. A struct, or a dictionary for keys that aren’t valid field names. An asset attached with the same Tags sees these points.

See also

nominal.Dataset.stream()

channelMetadata(name)

Units and description for one channel by name.

Errors if the dataset has no channel with that name. Use setChannelMetadata to attach metadata before any data exists.

Returns:

nominal.ChannelMetadata – The channel’s units, description and data type.

channels()

Every channel in this dataset, as a table.

ds.channels()
ds.channels().Name                    % just the names
c = ds.channels();
c(c.Unit == "Cel", :)                 % only the temperatures

Returns:

table – Variables Name, Unit, Description and DataType, ordered by name.

fetch(channel, startTime, endTime, options)

Read one channel back into MATLAB as a timetable.

tt = ds.fetch("rpm", t0, t1)
tt = ds.fetch("rpm", t0, t1, Buckets=2000)
tt = ds.fetch("rpm", t0, t1, Tags=struct(UUT="A"))

The result plots and resamples directly:

plot(tt.Time, tt.("rpm"))
retime(tt, "regular", "linear", TimeStep=seconds(1))

Without Buckets the whole window is fetched, which can take many round trips over a wide window. Use export when the destination is a file.

Parameters:

• startTime

  Zoned datetime or int64 nanoseconds. The window is inclusive at both ends.

• endTime

  Zoned datetime or int64 nanoseconds.

Options:

• Buckets – Have Nominal decimate to roughly this many points (bucket means), capped at 10,000. Use it for plotting.

• Tags – A channel written with tags holds one series per tag set. If it has more than one, pick with Tags, as given to write.

Returns:

timetable – One variable, named after the channel. Row times are datetimes, which do not resolve to nanoseconds. Use export if you need the exact instants.

See also

nominal.Dataset.export(), retime, synchronize

export(path, channels, startTime, endTime, options)

Write channels to a file on disk.

ds.export("run12.mat", ["rpm" "egt"], t0, t1)
ds.export("run12.csv", ch, t0, t1, Format="csv")

Same data as fetch, but in one request, so better for a wide window. Use fetch for samples in the workspace, export for samples on disk. Blocks until the export is complete.

Parameters:

• path

  File to write. Replaced if it exists.

• channels

  Channel names.

• startTime

  Zoned datetime or int64 nanoseconds.

• endTime

  Zoned datetime or int64 nanoseconds.

Options:

• Format – “matfile” (the default), “csv” or “arrow”.

• Resolution – “full” (every sample, the default), “buckets” or “interval”.

• ResolutionValue – The point count for “buckets”, or the nanosecond spacing for “interval”.

See also

nominal.Dataset.fetch(), nominal.Dataset.exportUrl()

exportUrl(channels, startTime, endTime, options)

A time-limited download link instead of a file.

url = ds.exportUrl(["rpm" "egt"], t0, t1, Format="csv")

For handing to a browser or something that is not MATLAB.

Parameters:

• channels

  Channel names.

• startTime

  Zoned datetime or int64 nanoseconds.

• endTime

  Zoned datetime or int64 nanoseconds.

Options:

• Format – “matfile” (the default), “csv” or “arrow”.

• Resolution – “full” (every sample, the default), “buckets” or “interval”.

• ResolutionValue – The point count for “buckets”, or the nanosecond spacing for “interval”.

Returns:

string – The download URL. It expires.

See also

nominal.Dataset.export()

setChannelMetadata(name, dataType, options)

Attach or update a channel’s units.

ds.setChannelMetadata("rpm", "double", Unit="1/min")
ds.setChannelMetadata("rpm", "double", Unit="")     % clear

This is an upsert and works before any data exists, so you can declare units ahead of a stream or write.

Parameters:

• name

  Channel name.

• dataType

  Required and always sent, so naming the wrong one re-declares the channel. One of double, int, uint, string, log, doubleArray, stringArray, struct, video, spatial.

Options:

• Unit – A UCUM symbol such as “1/min”, “Cel” or “m/s2”. A symbol UCUM cannot parse is stored display-only, with no conversions.

• Description – Free text.

Returns:

nominal.ChannelMetadata – What you sent, not what Nominal holds. Re-fetch with channelMetadata to check.

update(options)

Apply metadata changes, returning the updated dataset.

ds2 = ds.update(Description="reduced", Labels=["flight-test"])

Options not passed are left alone. Labels and Properties REPLACE rather than merge: read ds.Labels first and concatenate if you mean to add. setProperty changes one property and keeps the rest.

Options:

• Name – New display name.

• Description – New description.

• Properties – Struct of key-value pairs, replacing all of them. struct() clears them.

• Labels – String array, replacing all of them. string.empty clears them.

Returns:

nominal.Dataset – A new object with the changes applied. The original still shows the pre-update state.