nucleus.model_run

Model Runs are deprecated and will be removed in a future version of the python client. It is now possible to upload model predictions without a need for creating a model run.

The recommended run-free (“model v2”) path uploads and reads predictions directly on a Model — the concept is (model, dataset_item) -> prediction, with no model run or dataset:

import nucleus
client = nucleus.NucleusClient(YOUR_SCALE_API_KEY)
prediction_1 = nucleus.BoxPrediction(label="label", x=0, y=0, width=10, height=10, reference_id="1", confidence=0.9, class_pdf={'label': 0.9, 'other_label': 0.1})
prediction_2 = nucleus.BoxPrediction(label="label", x=0, y=0, width=10, height=10, reference_id="2", confidence=0.2, class_pdf={'label': 0.2, 'other_label': 0.8})
model = client.create_model(name="My Model", reference_id="My-CNN", metadata={"timestamp": "121012401"})

# Run-free upload / read, tied to the model itself:
model.upload_predictions([prediction_1, prediction_2])
model.predictions_refloc("1")

Benchmark evaluations can likewise anchor on the model directly, ignoring model runs, via client.create_benchmark_evaluation_v2(benchmark_id, model_id=model.id).

The older per-dataset path also remains available:

response = dataset.upload_predictions(model, [prediction_1, prediction_2])

ModelRun

This class is deprecated and will be removed from the python client.
class nucleus.model_run.ModelRun(model_run_id, dataset_id=None, client=None)

This class is deprecated and will be removed from the python client.

Parameters:

  • model_run_id (str)

  • dataset_id (Optional[str])

add_predictions(predictions, update=False, asynchronous=False, batch_size=5000, remote_files_per_upload_request=20, local_files_per_upload_request=10)

Adds predictions to this model run.

Each prediction identifies its target item by dataset_item_id (the di_* id returned on exported items), so predictions can come from anywhere and be added at any time — a single run can cover items that live in different datasets.

Parameters:

  • predictions (List[Union[nucleus.prediction.BoxPrediction, nucleus.prediction.PolygonPrediction, nucleus.prediction.CuboidPrediction, nucleus.prediction.SegmentationPrediction]]) – Predictions to upload. Each must set dataset_item_id to identify its item.

  • update (bool) – If True, existing predictions for the same (reference_id, annotation_id) will be overwritten. If False, existing predictions will be skipped.

  • asynchronous (bool) – Not supported yet — passing True raises NotImplementedError.

  • batch_size (int) – Number of predictions processed in each concurrent batch.

  • remote_files_per_upload_request (int) – Number of remote segmentation files to upload in each request.

  • local_files_per_upload_request (int) – Number of local segmentation files to upload in each request. The maximum is 10.

Return type:

dict

Returns:

{
    "model_run_id": str,
    "predictions_processed": int,
    "predictions_ignored": int,
}
commit(payload=None)

Commits the model run. Starts matching algorithm defined by payload.

Parameters:

payload (Optional[dict]) –

Dict with optional keys:

  • class_agnostic: A flag to specify if matching algorithm should be class-agnostic or not. Default value: True.

  • allowed_label_matches: An optional list of AllowedMatch objects to specify allowed matches for ground truth and model predictions. If specified, class_agnostic flag is assumed to be False. Each AllowedMatch has ground_truth_label and model_prediction_label.

    Example response format:

    [
    {
        "ground_truth_label": "car",
        "model_prediction_label": "car",
    }
]

Returns:

Dict with model_run_id.

Example response format:

{
    "model_run_id": "run_123",
}

Return type:

dict

iloc(i)

Returns Model Run Info For Dataset Item by its number.

Parameters:

i (int) – Absolute number of Dataset Item for a dataset corresponding to the model run.

Returns:

List[Union[BoxPrediction, PolygonPrediction, CuboidPrediction, SegmentationPrediction]]
info()

Provides information about the Model Run.

model_id: Model Id corresponding to the run.

name: A human-readable name of the model project.

status: Status of the Model Run.

metadata: An arbitrary metadata blob specified for the run.

Returns:

model_id, name, status, and metadata.

Example response format:

{
    "model_id": "prj_123",
    "name": "example-model-project",
    "status": "Completed",
    "metadata": Dict[str, Any],
}

Return type:

Dict with the following keys

loc(dataset_item_id)

Returns Model Run Info For Dataset Item by its id.

Parameters:

dataset_item_id (str) – Internally controlled id for dataset item.

Returns:

{
    "annotations": List[Box2DPrediction],
}
predict(annotations, update=DEFAULT_ANNOTATION_UPDATE_MODE, asynchronous=False, batch_size=5000, remote_files_per_upload_request=20, local_files_per_upload_request=10)

Uploads model outputs as predictions for a model_run.

Deprecated along with the rest of this class. The target dataset is inferred from the run rather than named, so this fails for a run that spans more than one dataset — there is no single dataset to infer. Use dataset.upload_predictions_for_model_run(model_run_id, predictions) instead: the dataset_id comes from the Dataset you call it on and the model_run_id is passed explicitly, so both are named.

Parameters:

  • annotations (List[Union[nucleus.prediction.BoxPrediction, nucleus.prediction.PolygonPrediction, nucleus.prediction.CuboidPrediction, nucleus.prediction.SegmentationPrediction]]) – Predictions to upload for this model run.

  • update (bool) – If True, existing predictions for the same (reference_id, annotation_id) will be overwritten. If False, existing predictions will be skipped.

  • asynchronous (bool) – Whether or not to process the upload asynchronously (and return an AsyncJob object). Default is False.

  • batch_size (int) – Number of predictions processed in each concurrent batch. Default is 5000. If you get timeouts when uploading geometric annotations, you can try lowering this batch size. This is only relevant for asynchronous=False.

  • remote_files_per_upload_request (int) – Number of remote files to upload in each request. Segmentations have either local or remote files, if you are getting timeouts while uploading segmentations with remote urls, you should lower this value from its default of 20. This is only relevant for asynchronous=False.

  • local_files_per_upload_request (int) – Number of local files to upload in each request. Segmentations have either local or remote files, if you are getting timeouts while uploading segmentations with local files, you should lower this value from its default of 10. The maximum is 10. This is only relevant for asynchronous=False

Return type:

Union[dict, nucleus.async_job.AsyncJob]

Returns:

{
    "model_run_id": str,
    "predictions_processed": int,
    "predictions_ignored": int,
}
prediction_loc(reference_id, annotation_id)

Returns info for single Prediction by its reference id and annotation id.

Parameters:

  • reference_id (str) – The user specified id for the image.

  • annotation_id (str) – The user specified id for the prediction, or if one was not provided, the Scale internally generated id for the prediction.

Returns:

BoxPrediction | PolygonPrediction | CuboidPrediction
refloc(reference_id)

Returns Model Run Info For Dataset Item by its reference_id.

Parameters:

reference_id (str) – reference_id of a dataset item.

Returns:

List[Union[BoxPrediction, PolygonPrediction, CuboidPrediction, SegmentationPrediction]]