caution

This function is experimental and might be changed or removed in a future minor release. Use with caution in production code.

fetch_metric_buckets()

Python package: neptune-query

Fetches a table of metric values split by X-axis buckets.

One point is returned from each bucket. To control the number of buckets, use the limit parameter.

Fetch experiment metrics

You can filter the results by:

• Experiments: Specify which experiments to search.
• Attributes: Only list metrics that match certain criteria.

Parameters

project

str

optional

default: None

Path of the Neptune project, as workspace-name/project-name.

If not provided, the NEPTUNE_PROJECT environment variable is used.

experiments

str | list of str | Filter

required

Filter specifying which experiments to include.

• If a string is provided, it's treated as a regex pattern that the experiment names must match.
• If a list of strings is provided, it's treated as exact experiment names to match.
• To provide a more complex condition on an arbitrary attribute value, pass a Filter object.

If no filter is specified, all experiments are returned.

x

Literal["step"]

optional

default: "step"

The X-axis series used for the bucketing. Only "step" is currently supported.

y

str | list of str | AttributeFilter

required

Filter specifying which metrics to include.

• If a string is provided, it's treated as a regex pattern that the metric names must match.
• If a list of strings is provided, it's treated as exact metric names to match.
• To provide a more complex condition, pass an AttributeFilter object.

limit

int

optional

default: 1000

Number of buckets to use. The default and maximum value is 1000.

lineage_to_the_root

bool

optional

default: True

If True, includes all values from the complete experiment history.

If False, only includes values from the most recent experiment in the lineage.

include_point_previews

bool

optional

default: False

If set to True, metric previews are included in the returned DataFrame. The DataFrame will have additional sub-columns with preview information: is_preview and preview_completion.

Returns

The returned DataFrame is a multi-index table with the following levels:

• experiment: The experiment name.
• metric: The metric name, such as train/loss.
• bucket: The x- and y-values of the point returned from the bucket.

Both the first and last points of each metric are always included:

• For every first bucket of a given series, the first point is returned.
• For the remaining buckets, the last point is returned.

Point previews

If include_point_previews=True, the following additional sub-columns are included for each bucket:

• is_preview: Whether the value is a preview.
• preview_completion: The completion rate.

Example

From two specific experiments, fetch training metrics split into 5 buckets:

import neptune_query as nq


nq.fetch_metric_buckets(
    experiments=["seagull-week1", "seagull-week2"],
    x="step",
    y=r"^train/",
    limit=5,  # Only 5 buckets for broad trends
)

Output

experiment    seagull-week1                                        seagull-week2
metric           train/loss              train/accuracy               train/loss             train/accuracy
bucket                    x           y               x          y             x          y               x          y
(0.0, 200.0]       0.766337   46.899769        0.629231  29.418603      0.793347   3.618248        0.445641  16.923348
(200.0, 400.0]   200.435899   42.001229      200.825488  11.989595    200.151307  21.244816      200.720397  20.515981
(400.0, 600.0]   400.798869   10.429626      400.640794  10.276835    400.338434  33.692977      400.381568  15.954130
(600.0, 800.0]   600.856616   20.633254      600.033832   0.927636    600.002655  37.048722      600.713322  49.537098
(800.0, 1000.0]  800.522183    6.084259      800.019450  39.666397    800.003379  22.569435      800.745987  42.658697