Skip to main content

aip_sdk.save_dimension

aip_sdk.save_dimension(dataset: str, name: str, assignments: Mapping[str, str], *, source_run_id: str | None = None, version_id: str | None = None, client: APIClient | None = None) -> SavedAssignedDimension

Save a category you computed for each row as a dataset-scoped dimension.

Calls POST /datasets/{id}/dimensions:assign. The saved dimension resolves as assigned:<name> on every later run of the same dataset, so it can group an analysis (run.analysis(group_by="assigned:<name>")) and appears under Custom in a run's Explore tab. Saving the same name again replaces the previous assignment rather than adding a second dimension.

Only rows you name are assigned. A version row you leave out is counted in the returned unassigned_rows, and when grouping it falls into the missing: group (shown as Unknown in the UI) rather than being dropped.

Values are category labels, not numbers. Bucket a continuous score into labels before saving it — 0.82 must be passed as something like "high".

Parameters

  • dataset str: Dataset id, optionally pinned to a version as "<dataset-id>@vN". A dataset name is not accepted — resolve one first with aip.load_dataset("<name>").id.
  • name str: Dimension name — 1-64 lowercase letters, numbers or underscores, starting with a letter.
  • assignments Mapping[str, str]: Business row id to category label, for the rows you want labelled.
  • source_run_id str | None: Run the values were computed from — stored as metadata.
  • version_id str | None: Dataset version whose row ids are validated. Defaults to the latest version. Mutually exclusive with an @vN pin on dataset.
  • client APIClient | None: Optional pre-configured API client.

Returns

Raises

  • InvalidArgumentError: If name is malformed, assignments is empty, holds a non-string or empty value, or exceeds the row or category limit; or if dataset is malformed or pins a different version from version_id=.
  • DatasetNotFoundError: If dataset does not exist.
  • NotFoundError: If a pinned version_id= does not exist on the dataset.
  • UnprocessableEntityError: If the platform refuses the assignment — most often row ids that are absent from the target version.
  • ConflictError: If concurrent saves of the same dimension cannot be serialised.
  • ResponseParseError: If the save succeeded but its response could not be read.
  • AipError: If no client is given and none is configured.

Examples:

crowding = {row_id: bucket(len(boxes)) for row_id, boxes in labels.items()}
saved = aip.save_dimension(dataset.id, "scene_crowding", crowding)
print(f"{saved.assigned_rows}/{saved.total_rows} rows, {saved.category_count} categories")

stats = run.analysis(group_by=saved.id)["group_stats"]