nucleus.evaluation_v2¶

Evaluation V2 — metrics and examples for a model run.

`EvaluationV2`	An Evaluation V2 run for a run-free model.
`EvaluationV2Status`	Status of an Evaluation V2 run.
`RollupGroup`	A rollup class: raw labels evaluated together under one class name.

class nucleus.evaluation_v2.EvaluationV2¶

An Evaluation V2 run for a run-free model.

The model-run-anchored flow is deprecated; new evaluations should be anchored on a Model via model_id.

cancel()¶

Cancel this evaluation if it is still running.

Stops the evaluation and sets its status to cancelled. Finished evaluations cannot be cancelled (use delete() to archive them).

Returns:: self, refreshed with the post-cancel status.
Return type:: EvaluationV2

charts(iou_threshold=0.5, filters=None, query=None)¶

Return aggregate metrics for this evaluation.

Parameters:

iou_threshold (float) – IoU threshold for matching (default 0.5).
filters (Optional[Union[nucleus.data_transfer_object.evaluation_v2.EvaluationV2FilterArgs, Dict[str, Any]]]) – Optional filters (EvaluationV2FilterArgs or dict).
query (Optional[str]) – Optional query string to narrow results.

Returns:

Summary metrics (mAP, confusion matrix, PR curve, etc.).

Return type:

EvaluationV2Charts

delete()¶

Delete this evaluation.

Return type:: None

examples(match_type=None, limit=50, offset=0, sort_by=None, sort_order=None, filters=None, query=None)¶

Return paginated match examples, optionally filtered by match type.

Parameters:

match_type (Optional[str]) – "TP", "FP", or "FN". Omit (or None) to return examples of all match types.
limit (int) – Page size (default 50, max 100).
offset (int) – Offset for pagination.
sort_by (Optional[str]) – Optional field to sort by — one of "confidence", "iou", "dataset_item_id", "gt_area".
sort_order (Optional[str]) – Optional sort direction ("ASC" or "DESC").
filters (Optional[Union[nucleus.data_transfer_object.evaluation_v2.EvaluationV2FilterArgs, Dict[str, Any]]]) – Optional filters (EvaluationV2FilterArgs or dict).
query (Optional[str]) – Optional query string to narrow results.

Returns:

Matching rows and total count.

Return type:

EvaluationV2ExamplesPage

filter_schema()¶

Return the filter vocabulary for this evaluation.

Lists the ground-truth labels, prediction labels, and item-metadata fields (with inferred value types and distinct values) present in this evaluation’s results — the valid inputs for EvaluationV2FilterArgs when calling charts() or examples().

Returns:: EvaluationV2FilterSchema.
Return type:: nucleus.data_transfer_object.evaluation_v2.EvaluationV2FilterSchema

refresh()¶

Reload this evaluation from Nucleus.

Returns:: self, with updated fields.
Return type:: EvaluationV2

retry()¶

Retry this evaluation if it failed.

Creates a new evaluation for the same anchor (the model for a run-free evaluation, or the model run for a legacy one), reusing this evaluation’s slice, rollup groups, and exclusion rules. Only failed evaluations can be retried.

Returns:: The newly created (retry) evaluation.
Return type:: EvaluationV2

wait_for_completion(timeout_sec=600, poll_interval=5)¶

Wait until the evaluation finishes or is cancelled.

Parameters:

timeout_sec (float) – Maximum seconds to wait.
poll_interval (float) – Seconds between status checks.

Returns:

self, after a terminal status is reached.

Raises:

RuntimeError – If the evaluation fails or times out.

Return type:

EvaluationV2

class nucleus.evaluation_v2.EvaluationV2Status¶

Status of an Evaluation V2 run.

Initialize self. See help(type(self)) for accurate signature.

class nucleus.evaluation_v2.RollupGroup¶

A rollup class: raw labels evaluated together under one class name.

Rollup groups are the primary label configuration for benchmark evaluations — each group maps a set of raw ground-truth/prediction labels onto a single canonical class_name. A label may appear in at most one group across the configuration.