Skip to content

Group runs (groupBy)#

To perform in-group and cross-group analyses on runs, you can group them by one or more columns.

  1. Next to the search input box, click Group by.
  2. Enter the name of the field to group the runs by.


At the left edge of the table, a new column appears.

It contains a group for each value of the selected field.

Each group is represented by the top run according to the active sorting.

Expanding a group displays the top 10 runs. To open a new table view with only the runs in a given group, click Show all.

See in Neptune 


If you want to access the filtered view later, you can save it as a custom view.

To compare all runs within a group against each other, click the eye icon () on the collapsed group.

Comparing metrics of grouped runs#

You can compare groups of runs against each other in the Compare runsCharts view.

When you toggle the Average grouped runs switch, each graph represents the mean of a run group.

Adding values to group by later#

If you've already logged a set of runs and would like to introduce a field to group them by, you have a few options.

Fetch and modify runs via API#

You resume a run as follows:

import neptune

run = neptune.init_run(with_id="RUN-ID")

where RUN-ID is the identifier of some existing run.

How do I find the ID?

You can grab the ID manually from the Runs table. It's displayed in the leftmost column.

Location of ID column in the runs table of the Neptune web app

The ID is stored in the system namespace (sys/id). If the run is active, you can obtain its ID with run["sys/id"].fetch(). For example:

>>> run = neptune.init_run(project="ml-team/classification")
>>> run["sys/id"].fetch()

You can do this manually for each run, or automate it by fetching all the runs from your project.

The below script illustrates how to obtain the run IDs as a list, then resume the runs one by one.

Example script
import neptune

with neptune.init_project(project="ml-team/xnlu") as project: # (1)!
    runs_table_df = project.fetch_runs_table().to_pandas() # (2)!
    run_ids = runs_table_df["sys/id"].to_list()

for run_id in run_ids:
    with neptune.init_run(with_id=run_id) as run: # (3)!
        # some criteria for the new field or value
        run["some_field"] = some_value
  1. Initialize your project with neptune.init_project() to get a Project object that you can operate on.
  2. Use fetch_runs_table() on the project object to get a list of run IDs.
  3. Use the IDs to resume each run and modify its metadata.

Depending on the field and value you want to introduce, you can implement some checks or other criteria in order to determine what metadata to assign to the run.

Edit system fields in-app#

You can manually edit the name or description fields and introduce some suitable values for the groupBy operation.

For example, to add a custom description:

  1. Open the run menu () next to the ID and select Show run information.

    Run menu in Neptune app

  2. In the Description box, enter some custom text.

  3. To save, click the check mark ().
  4. Click Group by and select the sys/description field.


The runs are grouped by the value of the description field.

If you need to edit a large number of runs, consider iterating through them programmatically instead.