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.

An Asset is Nominal’s primitive for test data without a time domain. This guide details common patterns for working with Assets in Python.

Connect to Nominal

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

Get your Nominal API token from your User settings page.

See the Quickstart for more details on connecting to Nominal from Python.

1 import nominal.nominal as nm
2 
3 nm._config.set_token(
4     url = 'https://api.gov.nominal.io/api',
5     token = '* * *' # Replace with your Access Token from 
6                     # https://app.gov.nominal.io/settings/user?tab=tokens
7 )

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

Create an Asset

It’s possible to create an empty asset without any data.

1 import nominal.nominal as nm
2 
3 uav_drone_asset = nm.create_asset(
4     name = 'Quadcopter-000-123'
5 )
6 
7 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 import nominal.nominal as nm
3 
4 df = pl.read_csv('hf://datasets/nominal-io/frosty-flight/frosty_flight_1k_rows.csv')
5 df.write_csv('frosty_flight_1k_rows.csv')
6 
7 csv_dataset = nm.upload_csv(
8     'frosty_flight_1k_rows.csv',
9     name = 'Frosty Flight',
10     timestamp_column = 'source_time',
11     timestamp_type = 'iso_8601',
12 )
13 
14 uav_drone_asset.add_dataset(
15     dataset = csv_dataset,
16     data_scope_name = 'high-precipitation-flight'
17 )

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 import nominal.nominal as nm
2 
3 found_assets = nm.search_assets(search_text = '000-123')
4 
5 if len(found_assets) == 0:
6     uav_drone_asset = nm.create_asset(
7     name = 'Quadcopter-000-123',
8 )

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:

All Nominal primitives (eg Datasets, Runs, Workbooks, and Checks) have a unique identifier called a “Resource ID”. Resource IDs may be referred to as “RID” or simply “ID” 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 import nominal.nominal as nm
2 
3 asset = nm.get_asset('ri.scout.cerulean-staging.asset.6c41d7fd-a48f-4d60-baa7-f34492264156')
4 
5 asset.remove_data_sources(data_sources = ['ri.catalog.cerulean-staging.dataset.d4f413c4-4787-4259-a142-1286587b50af'])

1	import nominal.nominal as nm
2
3	nm._config.set_token(
4	url = 'https://api.gov.nominal.io/api',
5	token = '* * *' # Replace with your Access Token from
6	# https://app.gov.nominal.io/settings/user?tab=tokens
7	)

1	import nominal.nominal as nm
2
3	uav_drone_asset = nm.create_asset(
4	name = 'Quadcopter-000-123'
5	)
6
7	print("Created asset:", uav_drone_asset.rid)

1	import polars as pl
2	import nominal.nominal as nm
3
4	df = pl.read_csv('hf://datasets/nominal-io/frosty-flight/frosty_flight_1k_rows.csv')
5	df.write_csv('frosty_flight_1k_rows.csv')
6
7	csv_dataset = nm.upload_csv(
8	'frosty_flight_1k_rows.csv',
9	name = 'Frosty Flight',
10	timestamp_column = 'source_time',
11	timestamp_type = 'iso_8601',
12	)
13
14	uav_drone_asset.add_dataset(
15	dataset = csv_dataset,
16	data_scope_name = 'high-precipitation-flight'
17	)

1	import nominal.nominal as nm
2
3	found_assets = nm.search_assets(search_text = '000-123')
4
5	if len(found_assets) == 0:
6	uav_drone_asset = nm.create_asset(
7	name = 'Quadcopter-000-123',
8	)

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

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

1	import nominal.nominal as nm
2
3	asset = nm.get_asset('ri.scout.cerulean-staging.asset.6c41d7fd-a48f-4d60-baa7-f34492264156')
4
5	asset.remove_data_sources(data_sources = ['ri.catalog.cerulean-staging.dataset.d4f413c4-4787-4259-a142-1286587b50af'])