1 of 5

Run

Functions interacting with dbnl Run

close_run

Finalize a Run

dbnl.close_run(
    *,
    run: ,
) -> None:

Mark the specified dbnl Run status as completed. Once a Run is marked as closed, it can no longer be used for reporting Results.

A Run must be closed for all uploaded results to be shown on the UI.

Parameters

Arguments

Description

run

The dbnl Run to be finalized.

Examples

import dbnl
dbnl.login()

dbnl.close_run(run=my_run)

create_run

Create a new dbnl Run

dbnl.create_run(
    *,
    project: ,
    run_config: ,
    display_name: Optional[str] = None,
    metadata: Optional[Dict[str, str]] = None,
) -> :

Parameters

Arguments

Description

project

The dbnl Project that this Run will be associated with.

run_config

The dbnl RunConfig that this Run will be associated with. Two Runs with the same RunConfig can be compared in the web UI and associated in Tests. The associated RunConfig must be from the same Project.

display_name

An optional display name for the Run. Display names do not have to be unique.

metadata

Any additional key-value pairs information the user wants to track.

Returns

Type

Description

Run

A new dbnl Run for reporting results.

Examples

import dbnl
dbnl.login()


proj1 = dbnl.get_or_create_project(name="test_p1")
runcfg1 = dbnl.create_run_config(project=proj1, columns=[{"name": "error", "type": "float"}])

run1 = dbnl.create_run(
    project=proj1, 
    run_config=runcfg1, 
    metadata={"mode": "dev"},
)

get_run

Retrieve a dbnl Run

dbnl.get_run(
    *,
    run_id: str,
) -> :

Parameters

Arguments

Description

run_id

The ID of the dbnl Run. Run ID starts with the prefix run_ . Run ID can be found at the Run detail page. An error will be raised if there does not exist a Run with the given run_id.

Returns

Type

Description

Run

The dbnl Run with the given ID.

Examples

import dbnl
dbnl.login()


proj1 = dbnl.get_or_create_project(name="test_p1")
runcfg1 = dbnl.create_run_config(project=proj1, columns=[{"name": "error", "type": "float"}])
run1 = dbnl.create_run(project=proj1, run_config=runcfg1)

# Retrieving the Run by ID
run2 = dbnl.get_run(run_id=run1.id)
assert run1.id == run2.id

# DBNLRunNotFoundError: A DBNL Run with id run_0000000 does not exist.
run3 = dbnl.get_run(run_id="run_0000000")

report_run_with_results

Create a new Run, report results to it, and close it.

dbnl.report_run_with_results(
    project: ,
    column_data: pd.DataFrame,
    scalar_data: Optional[Union[dict[str, Any], pd.DataFrame]] = None
    display_name: Optional[str] = None,
    row_id: Optional[list[str]] = None,
    run_config_id: Optional[str] = None,
    metadata: Optional[dict[str, str]] = None,
) -> Run:

Parameters

Arguments

Description

project

The dbnl Project that this Run will be associated with.

column_data

A pandas DataFrame with all the column results to report to dbnl. If run_config_id is provided, the columns of the DataFrame must match the columns described in the RunConfig.

scalar_data

A dict or pandas DataFrame with all the scalar results to report to dbnl. If run_config_id is provided, the key of the dict must match the scalars described in the RunConfig.

display_name

An optional display name for the Run. Display names do not have to be unique.

row_id

An optional list of the column names that can be used as unique identifiers.

run_config_id

ID of the RunConfig to use for the Run, defaults to None. If provided, the RunConfig is used as is and the results are validated against it. If not provided, a new Run Config is inferred from the column_data.

metadata

Any additional key-value pairs information the user wants to track.

Returns

Type

Description

Run

The closed Run with the uploaded data.

Examples

import dbnl
import pandas as pd
dbnl.login()


proj = dbnl.get_or_create_project(name="test_p1")
test_data = pd.DataFrame({"error": [0.11, 0.33, 0.52, 0.24]})

run = dbnl.report_run_with_results(
    project=proj,
    column_data=test_data,
    row_id=["idx"],
)