The official Nominal Python client.

Nominal is the leading platform for operationalizing test data.

Installation

The Nominal Python Client can be installed with pip:

$
$ pip install nominal

Version

We use semantic versioning for the Nominal Python Client. To see the client version, run the following from within Python:

1
import nominal
2
3
print(nominal.__version__)

$
$ pip install --upgrade nominal

Connect to Nominal

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.

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

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())

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

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())

Usage examples

Upload a Dataset

Download this example CSV to your local computer:

1
import pandas
2
3
df = pandas.read_csv('hf://datasets/nominal-io/frosty-flight/frosty_flight_1k_rows.csv')
4
df.to_csv('frosty_flight_1k_rows.csv', index=False)

Then upload the CSV file to Nominal:

1
from nominal.core import NominalClient
2
3
client = NominalClient.from_profile("default")  # replace with your profile name
4
5
dataset = client.create_dataset('Frosty Flight')
6
dataset.add_tabular_data_to_dataset(
7
    'frosty_flight_1k_rows.csv',
8
    timestamp_column = 'source_time',
9
    timestamp_type = 'iso_8601',
10
)
11
12
print('Uploaded dataset:', dataset.rid)

See client.create_dataset()

Create a Run

1
from nominal.core import NominalClient
2
3
client = NominalClient.from_profile("default")  # replace with your profile name
4
5
flight_simulator_run = client.create_run(
6
    name = 'High precipitation flight',
7
    start = '2024-09-09T12:35:00Z',
8
    end = '2024-09-09T13:18:00Z',
9
)
10
11
print("Created run:", flight_simulator_run.rid)

See client.create_run()

Add Data to a Run

(Scroll up to Upload a dataset to see how the csv_dataset was created.)

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

See Run.add_dataset()

Create a Run with Data

Create a Run and add a Dataset to it in one swoop.

1
from nominal.core import NominalClient
2
3
client = NominalClient.from_profile("default")  # replace with your profile name
4
5
dataset = client.create_dataset("my_dataset", "description")
6
dataset.add_tabular_data('frosty_flight_1k_rows.csv', timestamp_column = 'source_time', timestamp_type = 'iso_8601')
7
dataset.poll_until_ingestion_completed()
8
9
run = client.create_run("my_run", dataset.bounds.start, dataset.bounds.end, "description")
10
run.add_dataset(dataset)

Update Run metadata

1
run = client.get_run('ri.scout.gov-staging.run.ce205f7e-9ef1-4a8b-92ae-11edc77441c6')
2
run.update(name = 'New Run Title')

See Run.update()

Please refer to the Function Reference and guides on the left-hand sidebar for more extensive examples.

Appendix

Tips & tricks for test engineers getting started with Python.

Python is the fastest growing language in STEM for data analytics. It’s free and functionally equivalent to MATLAB in many respects.

Python IDEs

If you’re new to scripting in Python, below are a few recommendations for Python IDEs (integrated development environments).

Jupyter

The guides on this website are styled after Jupyter notebook, a free and beginner-friendly analysis environment for Python. If you’re creating a lot of charts, or enjoy narrating your analysis code with text, you may find Jupyter productive.

VSCode

VSCode is a more minimalist, equally popular development environment for Python. If you’re creating automation scripts in Python that do not involve charts or analysis, the streamlined UX of VSCode may be appealing.