# Dataset

## class nominal.Dataset

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

Obtained from an asset or a client:

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

Streaming into it:

```matlab
s = ds.stream();
```

> **See also**
>
> [`nominal.Asset`](https://dev.nominal.io/matlab/ref/Asset.md#nominal.Asset "nominal.Asset"), [`nominal.Stream`](https://dev.nominal.io/matlab/ref/Stream.md#nominal.Stream "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.

    ```matlab
    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()`](https://dev.nominal.io/matlab/ref/Asset.md#nominal.Asset.addDataset "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`](https://dev.nominal.io/matlab/ref/Stream.md#nominal.Stream "nominal.Stream")

    ### write(channels, timestamps, values, options)

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

    ```matlab
    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()`](https://dev.nominal.io/matlab/ref/Dataset.md#nominal.Dataset.stream "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.

    ```matlab
    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.

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

    ```matlab
    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()`](https://dev.nominal.io/matlab/ref/Dataset.md#nominal.Dataset.export "nominal.Dataset.export"), `retime`, `synchronize`

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

    Write channels to a file on disk.

    ```matlab
    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()`](https://dev.nominal.io/matlab/ref/Dataset.md#nominal.Dataset.fetch "nominal.Dataset.fetch"), [`nominal.Dataset.exportUrl()`](https://dev.nominal.io/matlab/ref/Dataset.md#nominal.Dataset.exportUrl "nominal.Dataset.exportUrl")

    ### exportUrl(channels, startTime, endTime, options)

    A time-limited download link instead of a file.

    ```matlab
    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()`](https://dev.nominal.io/matlab/ref/Dataset.md#nominal.Dataset.export "nominal.Dataset.export")

    ### setChannelMetadata(name, dataType, options)

    Attach or update a channel’s units.

    ```matlab
    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.

    ```matlab
    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.