To use this guide, install the Nominal Python library with pip3 install nominal.

See Quickstart for more details.

Please contact us if you’re not sure whether your organization has access to Nominal.

Assets organize test data around physical systems, rather than around individual test events. For example, an Asset might be an airplane or a satellite. Each Asset can connect to runs, workbooks, and checklists.

Connect to Nominal

To add an Asset, first connect to your Nominal platform tenant.

Concepts

Base URL: The URL through which the Nominal API is accessed (typically https://api.gov.nominal.io/api; shown under Settings → API keys).
Workspace: A mechanism by which to isolate datasets; each user has one or more workspace, and data in one cannot be seen from another. Note that a token / API key is attached to a user, and may access multiple workspaces.
Profile: A combination of base URL, API key, and workspace.

There are two primary ways of authenticating the Nominal Client. The first is to use a profile stored on disk, and the second is to use a token directly.

Storing credentials to disk

Run the following in a terminal and follow on-screen prompts to set up a connection profile:

$ $ nom config profile add default
> 
> # Alternatively, if `nom` is missing from the path:
> $ python -m nominal config profile add default

Here, “default” can be any name chosen to represent this profile (reminder: a profile represents a base URL, API key, and workspace).

The profile will be stored in ~/.config/nominal/config.yml, and can then be used to create a client:

1 from nominal.core import NominalClient
2 
3 client = NominalClient.from_profile("default")
4 
5 # Get details about the currently logged-in user to validate authentication
6 # Will display an object like: `User(display_name='your_email@your_company.com', ...)`
7 print(client.get_user())

If you have previously used nom to store credentials, prior to the availability of profiles, you will need to migrate your old configuration file (~/.nominal.yml) to the new format (~/.config/nominal/config.yml).

You can do this with the following command:

$ nom config migrate
> 
> # Or, if `nom` is missing from your path:
> python -m nominal config migrate

Directly using credentials in your scripts

1 from nominal.core import NominalClient
2 
3 # Get an instance of the client using provided credentials
4 client = NominalClient.from_token("<insert api key>")
5 
6 # Get details about the currently logged-in user to validate authentication
7 # Will display an object like: `User(display_name='your_email@your_company.com', ...)`
8 print(client.get_user())

NOTE: you should never share your Nominal API key with anyone. We therefore recommend that you not save it in your code and/or scripts.

If you trust the computer you are on, use nom to store the credential to disk.
Otherwise, use a password manager such as 1password or bitwarden to keep your token safe.

If you’re not sure whether your company has a Nominal tenant, please reach out to us.

Create an Asset

To create an Asset, use create_asset(). You can, optionally, add a description, properties, and labels:

1 from nominal.core import NominalClient
2 
3 uav_drone_asset = nm.create_asset(
4     name = 'Quadcopter-456',
5     description = 'Airborne observation platform',
6     properties = {'rotors': '4'},
7     labels = ('camera', 'airborne')
8 )
9 
10 print("Created asset:", uav_drone_asset.rid)

Add data to an asset

To add a Dataset to an Asset, use Asset.add_dataset():

1 import polars as pl
2 from nominal.core import NominalClient
3 
4 client = NominalClient.from_profile("default")  # replace with your profile name
5 
6 df = pl.read_csv('hf://datasets/nominal-io/frosty-flight/frosty_flight_1k_rows.csv')
7 df.write_csv('frosty_flight_1k_rows.csv')
8 
9 csv_dataset = client.create_dataset("Frosty Flight")
10 
11 csv_dataset.add_tabular_data(
12     'frosty_flight_1k_rows.csv',
13     timestamp_column = 'source_time',
14     timestamp_type = 'iso_8601',
15 )
16 
17 uav_drone_asset.add_dataset(
18     dataset = csv_dataset,
19     data_scope_name = 'high-precipitation-flight'
20 )

Datasets are the file representation of Nominal’s Data Source primitive. Most often, Datasets are tabular files with at least one time dimension. Datasets can also be video files.

Head over to the Datasets page to see your organization’s most recently uploaded Datasets.

Asset data with data scope names

To add a Dataset with a data scope name to an Asset, set the data_scope_name parameter in Asset.add_dataset().

1 uav_drone_asset.add_dataset(
2     dataset = csv_dataset,
3     data_scope_name = 'high-precipitation-flight'
4 )

Data scope names are a namespace for data sources that share common channels, but do not necessarily belong to the same Asset. They allow data sources with similar schema to be referenced as a group. For example, data sources with the same data scope name can share Workbook templates and Checklists.

Check if an Asset exists

You can check for a Asset’s existence with nm.search_assets().

1 from nominal.core import NominalClient
2 
3 client = NominalClient.from_profile("default")  # replace with your profile name
4 
5 found_assets = client.search_assets(search_text = '000-123')
6 
7 if len(found_assets) == 0:
8     uav_drone_asset = nm.create_asset(
9     name = 'Quadcopter-000-123',
10 )

Update an Asset

Asset metadata can be updated with Asset.update():

For example, to set an Asset’s title:

1 uav_drone_asset.update(title = 'Quadcopter-001-456')

Please see Asset.update() for all updatable metadata.

Asset attachments

File attachments such as PDF reports or PowerPoints can be added to Assets:

1 filepath = '/path/to/my_report.pdf'
2 attachment = nm.upload_attachment(file = filepath, name = 'KittyHawk.pdf')
3 nominal_asset.add_attachments(attachments = [attachment])

Retrieve an Asset

Like Datasets, Assets can be retrieved by their resource ID (“RID”):

1 asset = nm.get_asset('ri.scout.cerulean-staging.asset.22697726-5454-4fad-a3ea-fe45e9fa9f09')
2 asset.update(labels = ['NEW-MOTOR-VENDOR'])

To retrieve an Asset’s RID, visit its detail page and click on the clipboard icon next to “ID” in the right-hand drawer:

run-metadata

All Nominal primitives (eg Datasets, Runs, Workbooks, and Checks) have a unique identifier called a “Resource ID”. Resource IDs may be referred to as “RIDs”, or simply “IDs”, throughout the platform. They can be obtained from a primitive’s detail page (or URL) and have a format that looks like ri.catalog.cerulean-staging.dataset.e5ede17b-05f9-404d-aaf5-ba85c99761a2.

Query Assets

Assets can be queried with nm.search_assets().

For example, to retrieve all assets with the label “NEW-MOTOR-VENDOR”:

1 quadcopter_assets = nm.search_assets(label = 'NEW-MOTOR-VENDOR')

See nm.search_assets() for all Assets search parameters.

Remove Asset Data Sources

The list data_sources can contain Connection, Dataset, Video instances, or rids as string.

1 from nominal.core import NominalClient
2 
3 client = NominalClient.from_profile("default")  # replace with your profile name
4 
5 asset = client.get_asset('ri.scout.cerulean-staging.asset.6c41d7fd-a48f-4d60-baa7-f34492264156')
6 
7 asset.remove_data_sources(data_sources = ['ri.catalog.cerulean-staging.dataset.d4f413c4-4787-4259-a142-1286587b50af'])

Archive an Asset

Once an Asset is no longer needed, it can be archived. This does not delete the Asset, but makes it invisible on the web. If you save the rid of the Asset, you can retrieve and unarchive it at a later date.

1 uav_drone_asset.archive()