Notebook Display#

This notebook demonstrates the html display of Nominals core objects when used with Jupyter notebook, VS Code, or Colab.

A ficticous dataset of a helicopter spin up test is used for demonstration.

The example needs the installed Nominal Python client and a default profile.

Generate Sample Data#

This examples demonstrate the typical lifecycle of piece of test equipment, called an asset. Let’s imagine, for example, that we fire up the rotor of a helicopter to measure its angular velocity.

The test records three minutes of data at 10 Hz: the rotor spins up, holds near 31 rad/s (about 300 rpm), and spins down. Telemetry and vibration go in separate tables:

Hide code cell source

 
import numpy as np
import pandas as pd

t = np.arange(1800) / 10
speed = np.interp(t, [0, 30, 120, 150, 180], [0, 31.4, 31.4, 0, 0])
test_start = pd.Timestamp.now(tz="UTC").floor("s") - pd.Timedelta(minutes=10)
times = test_start + pd.to_timedelta(t, unit="s")
rng = np.random.default_rng(2)
tables = {
    "telemetry": pd.DataFrame(
        {
            "time": times,
            "rotor_speed": speed.round(3),
            # The gearbox warms with each rotor revolution and levels off above 70 °C.
            "gearbox_temp": (
                40 + 35 * (1 - np.exp(-np.cumsum(speed) / 15000))
            ).round(2),
        }
    ),
    "vibration": pd.DataFrame(
        {
            "time": times,
            "accel_rms": (0.02 * speed + rng.normal(0, 0.05, t.size)).round(4),
        }
    ),
}
tables["telemetry"].head()

Each table becomes a dataset on the rig, under its own data scope:

Hide code cell source

 
from nominal.thirdparty.pandas import upload_dataframe

units = {"rotor_speed": "rad/s", "gearbox_temp": "°C", "accel_rms": "g"}
for scope, table in tables.items():
    # The upload writes the index as the first column, so the timestamps go there.
    dataset = upload_dataframe(
        client,
        table.set_index("time"),
        f"RTR-02 {scope}",
        "time",
        timestamp_type="iso_8601",
        labels=[scope],
        properties={"sample_rate_hz": "10"},
    )
    rig.add_dataset(scope, dataset)
    for channel in dataset.get_channels():
        channel.update(unit=units[channel.name])

Each phase of the test becomes a run on the rig, and the gearbox overheating late in the hold becomes an event:

Hide code cell source

 
from nominal.core import EventType

seconds = pd.Timedelta(seconds=1)
for name, begin, end in [
    ("Spin-up", 0, 30),
    ("Hold at 300 rpm", 30, 120),
    ("Spin-down", 120, 150),
]:
    rig.create_run(
        f"RTR-02 {name}",
        start=test_start + begin * seconds,
        end=test_start + end * seconds,
        labels=["example"],
        properties={"test_bay": "Bay 3", "gearbox_sn": "GB-1187"},
        links=[
            {
                "url": "https://dev.nominal.io/platform/data-model/",
                "title": "Nominal data model",
            }
        ],
    )
rig.create_event(
    "Gearbox above 70 °C",
    EventType.FLAG,
    start=test_start + 108 * seconds,
    duration=72 * seconds,
    description="Gearbox temperature passed the 70 °C limit late in the hold.",
    labels=["example"],
);  # the cell shows no output

Create the Nominal Client#

A NominalClient provides the link to the Nominal Platform.

from nominal.core import NominalClient

client = NominalClient.from_profile("default")
rig = client.search_assets(
    properties={"rig_id": "RTR-02", "example": "notebook_display"}
)[0]

An asset#

The rig’s Asset card lists its properties, its datasets, by data scope, and its runs, newest first. Each section starts folded; click its title to open it. Each name links to its page in Nominal, and its copy button copies its RID. Open in Nominal opens the asset’s own page:

rig

Relationship diagrams#

The card above has a Relationships section, after the properties, with a diagram of the rig and the resources around it, drawn like the diagrams in Per-asset organization. Data flows from the bottom up: each dataset feeds the rig under its data scope’s ref name, and the rig’s runs sit above it. The rig’s own node has the thicker border. Each node links to its page in Nominal, and hovering over a node shows its full name.

Run, dataset, workbook, event and data review cards draw diagrams too. A diagram uses only what its card already loads, so it makes no requests of its own, and it needs no JavaScript, so it also displays in untrusted and saved notebooks.

An asset with hundreds of runs would make a diagram too large to read, so a diagram draws at most graph_max_nodes nodes, 20 by default. Past that, each group shows its first few nodes and a node counting the rest. That node links to the section of the card that lists them all. The card’s own node and one node of each group always show, so a cap smaller than that is exceeded. For example, with room for five nodes, the rig’s diagram draws one run and counts the other two. Here collapse_threshold=10 also opens the sections with up to 10 items, so the diagram shows open:

from IPython.display import display

from nominal.core import set_display_options

with set_display_options(graph_max_nodes=5, collapse_threshold=10):
    display(rig)

show_graph=False leaves diagrams out of the cards.

Configuring the display#

set_display_options changes how every card looks, from that cell on, and get_display_options returns the current settings as DisplayOptions:

from nominal.core import get_display_options, set_display_options

get_display_options()

Timestamps show to the second by default. Hover over one to see it to the nanosecond. For example, show timestamps in the test site’s time zone, to the millisecond, in a more readable format:

set_display_options(
    timezone="America/Denver", time_precision="ms", time_format="readable"
)
rig

Called on its own like this, a change lasts until the kernel restarts. To use the same options in every notebook, put the call in an IPython startup file, such as ~/.ipython/profile_default/startup/nominal.py.

Each card loads its related resources from Nominal, with a few requests, and waits at most fetch_timeout seconds, 5 by default, for them. A section that hasn’t loaded by then says so. To display cards faster, or offline, fetch_details=False shows only the fields the resource already holds. Used in a with block, the change lasts only until the block ends:

from IPython.display import display

with set_display_options(fetch_details=False):
    display(rig)

style="text" shows the plain text form instead of cards:

with set_display_options(style="text"):
    display(rig)

A dataset#

A Dataset card shows the time span of its data and lists its files and channels:

telemetry = rig.get_dataset("telemetry")
telemetry

A channel#

A numeric Channel card summarizes its data: the number of samples, the minimum, maximum and mean, the first and last timestamps, and a chart of its range and mean over time:

telemetry.get_channel("gearbox_temp")

A run#

A Run card shows its number, time span and duration, and lists its assets, datasets and links:

hold = next(
    run
    for run in rig.list_runs()
    if run.name == "RTR-02 Hold at 300 rpm" and not run.is_archived
)
hold

Files and events#

Other resources have cards too, such as a dataset’s files (DatasetFile) and an asset’s events (Event):

next(iter(telemetry.list_files()))

rig.search_events()[0]