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.

A Run is Nominal’s primitive for test data that shares a common time domain. This guide details common patterns for working with Runs in Python.

Connect to Nominal

To instantiate a Run, 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.set_token(
4     base_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 a Run

It’s possible to create an empty run without any data. Runs must have a start and end time expressed in absolute time. All Datasets added to the Run should overlap with this time domain.

1 import nominal.nominal as nm
2 
3 flight_simulator_run = nm.create_run(
4     name = 'High precipitation flight',
5     start = '2024-09-09T12:35:00Z',
6     end = '2024-09-09T13:18:00Z',
7 )
8 
9 print("Created run:", flight_simulator_run.rid)

Add data to a run

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

1 import polars as pl
2 import 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 flight_simulator_run.add_dataset(
15     dataset = csv_dataset,
16     ref_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.

The three function calls above can be shortened to a single call using nm.create_run_csv():

1 import polars as pl
2 import 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 flight_simulator_run = nm.create_run_csv(
8     'frosty_flight_1k_rows.csv',
9     name = 'Frosty Flight',
10     timestamp_column = 'source_time',
11     timestamp_type = 'iso_8601'
12 )

Run data with ref names

To add a Dataset with a reference name to a Run, set the ref_name parameter in Run.add_dataset().

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

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

Check if a Run exists

You can check for a Run’s existence with nm.search_runs().

1 import nominal.nominal as nm
2 
3 found_runs = nm.search_runs(exact_name = 'High precipitation flight')
4 
5 if len(found_runs) == 0:
6     flight_simulator_run = nm.create_run(
7     name = 'High precipitation flight',
8     start = '2024-09-09T12:35:00Z',
9     end = '2024-09-09T13:18:00Z',
10 )

Update a Run

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

For example, to set a Run’s end time to the present moment:

1 import datetime
2 flight_simulator_run.update(end = datetime.datetime.now())

To update a Run’s title:

1 flight_simulator_run.update(title = 'Low precipitation flight')

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

Run attachments

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

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

Retrieve a Run

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

1 run = nm.get_run('ri.scout.cerulean-staging.run.22697726-5454-4fad-a3ea-fe45e9fa9f09')
2 run.update(labels = ['X-PLANE'])

To retrieve a Run’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 Runs

Runs can be queried with nm.search_runs().

For example, to retrieve all runs with the label “X-PLANE”:

1 x_plane_runs = nm.search_runs(label = 'X-PLANE')

See nm.search_runs() for all Run search parameters.

Remove Run Data Sources

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

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

1	import nominal.nominal as nm
2
3	nm.set_token(
4	base_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	flight_simulator_run = nm.create_run(
4	name = 'High precipitation flight',
5	start = '2024-09-09T12:35:00Z',
6	end = '2024-09-09T13:18:00Z',
7	)
8
9	print("Created run:", flight_simulator_run.rid)

1	import polars as pl
2	import 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	flight_simulator_run.add_dataset(
15	dataset = csv_dataset,
16	ref_name = 'high-precipitation-flight'
17	)

1	import nominal.nominal as nm
2
3	found_runs = nm.search_runs(exact_name = 'High precipitation flight')
4
5	if len(found_runs) == 0:
6	flight_simulator_run = nm.create_run(
7	name = 'High precipitation flight',
8	start = '2024-09-09T12:35:00Z',
9	end = '2024-09-09T13:18:00Z',
10	)

1	import datetime
2	flight_simulator_run.update(end = datetime.datetime.now())

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

1	run = nm.get_run('ri.scout.cerulean-staging.run.22697726-5454-4fad-a3ea-fe45e9fa9f09')
2	run.update(labels = ['X-PLANE'])

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