# Run

## class nominal.Run

A bounded time window of activity on an asset.

Created on an asset, or fetched by RID:

```matlab
r = a.run("burn-12");           % starts now, left open
r = c.runByRid(rid);
```

A run can span several assets, say a test chamber and the unit in it:

```matlab
r = r.addAsset(dut);
```

Closing it:

```matlab
r = r.finish();                 % ends now
```

Times are datetime on the way out, and accept either datetime or int64
nanoseconds on the way in.

> **See also**
>
> [`nominal.Asset`](https://dev.nominal.io/matlab/ref/Asset.md#nominal.Asset "nominal.Asset"), [`nominal.Dataset`](https://dev.nominal.io/matlab/ref/Dataset.md#nominal.Dataset "nominal.Dataset")

Constructor Summary

Property Summary
:   ### Rid

    Resource identifier.

    ### Name

    Display name.

    ### Description

    Description.

    ### Number

    Sequential run number within the workspace.

    ### Url

    Web URL in the Nominal app.

    ### Labels

    All labels, as a string array.

    ### StartTime

    When the run began, UTC.

    ### EndTime

    When it ended, or NaT while still open.

    ### AssetRids

    Assets it belongs to.

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

    ### fetch(channel, options)

    Read one channel over this run, as a timetable.

    ```matlab
    tt = r.fetch("rpm")
    tt = r.fetch("rpm", RefName="can", Buckets=2000)
    ```

    The window is this run’s start to its end, or to now while it
    is open. Reads through one of the run’s data sources, so that
    source’s tag filter and time offset apply without being
    passed.

    Options:
    :   - **RefName** – Which data source. Defaults to “default”.
        - **Buckets** – Have Nominal decimate to roughly this many points.
        - **Tags** – Narrow further, if the source still holds several
          tag sets.

    Returns:
    :   *timetable* – One variable, named after the channel.

    > **See also**
    >
    > [`nominal.Asset.fetch()`](https://dev.nominal.io/matlab/ref/Asset.md#nominal.Asset.fetch "nominal.Asset.fetch"), [`nominal.Dataset.fetch()`](https://dev.nominal.io/matlab/ref/Dataset.md#nominal.Dataset.fetch "nominal.Dataset.fetch")

    ### setProperty(key, value)

    Set one property, keeping the rest.

    ```matlab
    r = r.setProperty("result", "pass");
    ```

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

    Returns:
    :   *nominal.Run* – The updated run.

    ### removeProperty(key)

    Remove one property, keeping the rest.

    Errors if the run has no such property.

    Returns:
    :   *nominal.Run* – The updated run.

    ### addAsset(asset)

    Put this run on another asset, returning the updated run.

    ```matlab
    r = chamber.run("test-42");
    r = r.addAsset(dut);
    ```

    Adding one the run already has changes nothing.

    Parameters:
    :   **asset**

        A nominal.Asset or an asset RID.

    Returns:
    :   *nominal.Run* – The updated run.

    > **See also**
    >
    > [`nominal.Run.removeAsset()`](https://dev.nominal.io/matlab/ref/Run.md#nominal.Run.removeAsset "nominal.Run.removeAsset"), [`nominal.Asset.run()`](https://dev.nominal.io/matlab/ref/Asset.md#nominal.Asset.run "nominal.Asset.run")

    ### removeAsset(asset)

    Take this run off an asset, returning the updated run.

    ```matlab
    r = r.removeAsset(dut);
    ```

    Errors if the run is not on it, or if it is the run’s only
    asset: a run always has one.

    Parameters:
    :   **asset**

        A nominal.Asset or an asset RID.

    Returns:
    :   *nominal.Run* – The updated run.

    > **See also**
    >
    > [`nominal.Run.addAsset()`](https://dev.nominal.io/matlab/ref/Run.md#nominal.Run.addAsset "nominal.Run.addAsset")

    ### finish(endTime)

    Close the run, returning the updated run.

    ```matlab
    r = r.finish();
    ```

    Parameters:
    :   **endTime**

        Zoned datetime or int64 nanoseconds. Omit it to
        end the run now.

    Returns:
    :   *nominal.Run* – The closed run.

    ### addDataset(refName, dataset)

    Attach a dataset under a reference name.

    **This fails for a run made with nominal.Asset.run.** That run
    already shows every data source on its asset, including ones
    added later, so there is nothing to attach.

    For a run with its own data, use nominal.Client.createRun.

    ### update(options)

    Apply metadata changes, returning the updated run.

    ```matlab
    r2 = r.update(Labels=["burn" "nominal"], ...
                  EndTime=datetime("now", TimeZone="UTC"));
    ```

    Options not passed are left alone. Labels and Properties
    REPLACE rather than merge: read r.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.
        - **StartTime** – Zoned datetime or int64 nanoseconds.
        - **EndTime** – Zoned datetime or int64 nanoseconds.

    Returns:
    :   *nominal.Run* – A new object with the changes applied. The
        original still shows the pre-update state.