The official Nominal Python client.

Nominal is the leading platform for operationalizing test data.

Installation

1
pip3 install nominal --upgrade

Version

You can check your version of nominal in Python with:

1
from importlib.metadata import version
2
version('nominal')

(Make sure that your version is >= 1.11.0)

Connect to Nominal

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
)

Usage examples

Upload a Dataset

Download this example CSV to your local computer:

1
import polars as pl
2
3
df = pl.read_csv('hf://datasets/nominal-io/frosty-flight/frosty_flight_1k_rows.csv')
4
df.write_csv('frosty_flight_1k_rows.csv')

Then upload the CSV file to Nominal:

1
import nominal.nominal as nm
2
3
csv_dataset = nm.upload_csv(
4
    'frosty_flight_1k_rows.csv',
5
    name = 'Frosty Flight',
6
    timestamp_column = 'source_time',
7
    timestamp_type = 'iso_8601',
8
)
9
10
print('Uploaded dataset:', csv_dataset.rid)

See nm.upload_csv()

Create a Run

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)

See nm.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.

nm.create_run_csv() combines upload_csv(), create_run(), and add_dataset().

1
import nominal.nominal as nm
2
3
nm.create_run_csv(
4
    'frosty_flight_1k_rows.csv',
5
    name = 'Frosty Flight',
6
    timestamp_column = 'source_time',
7
    timestamp_type = 'iso_8601'
8
)

See nm.create_run_csv()

Update Run metadata

1
import nominal.nominal as nm
2
3
run = nm.get_run('ri.scout.gov-staging.run.ce205f7e-9ef1-4a8b-92ae-11edc77441c6')
4
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.

Download Python

If you don’t have Python installed, you can download it for free from the Python Software Foundation. We recommend version 3.8 or higher.

To check whether Python is installed, simply open your Terminal (Mac) or command prompt (Windows), and type python (or python3) in the prompt. If you receive an error, you likely do not have Python installed on your machine.

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.