Skip to main content
Label sets are currently in BETA and are not available to every Organization. Contact your Encord representative to enable label sets for your Organization. Label sets require version 0.2.0 or later of the encord SDK.
A label set defines which labels in a Project you want to version. Each time you create a version of a label set, Encord freezes the labels that match the set’s selection, at their current revision, into a numbered snapshot. Versions never change, so you can always trace a model or a delivery back to the exact labels it used. For an introduction to label sets in the Encord app, see Label Sets. To compare label sets with label branches, Label Checkpoint stages, and saved versions, see Choosing How to Version Labels.

Key Concepts

Permissions

Organization Admins, and users with a custom Organization role that can manage all Projects, can also perform these actions.

Limitations

  • One source. A label set reads one branch of one Project.
  • Stage selections on main only. Workflow tasks exist on the main branch only, so a WorkflowStageSelection cannot be used on any other branch.
  • Manual versions only. Versions are created when you call create_version_job(). Scheduled versions are not available.
  • Data Groups. Versions cannot yet be created for Projects that contain Data Groups.

Versions Are Created by Jobs

Creating and exporting a version can take a while, so both run as jobs:
  1. create_version_job() (or create_export_job()) queues the job and returns its ID straight away.
  2. get_version_job() (or get_export_job()) reads the job’s state. Pass timeout_seconds to wait for the job to finish. With the default of 0, the method reads the state once and returns.
A job’s state is one of the following:

Create a Label Set and a Version

The following example creates a label set that captures the labels on tasks in the Complete stage of a Project’s Workflow, and then creates its first version. Each version you create later captures the tasks that are in the stage at that time. To capture every label on the main branch instead, leave out label_selection.
Create a label set and a version
A version cannot be created when no labels match the selection. The version job fails, and VersionJobFailed.error explains why.

Version Model Predictions

To keep a frozen record of each model run, write the model’s predictions to a dedicated branch of the Project, and create a label set with origin=LabelSetOrigin.IMPORT that reads that branch. Each time the model runs, replace the predictions on the branch and create a new version. The following example writes predictions to the preds/model-7 branch, creates a label set for the branch, and creates a version of the predictions. For more information on importing predictions, see Import Predictions.
Upload predictions and create a version
initialise_labels() loads the labels from the previous run, so remove them before you add the new predictions. Otherwise the new version holds the labels from both runs.

List Label Sets, Versions, and Labels

list_label_sets() returns the label sets you can see, newest first. Pass project_id to list only the label sets that a Project feeds. list_versions() returns a label set’s versions, newest first, and list_members() returns the labels a version holds, each at the revision it captured.
List label sets, versions, and labels
Label sets returned by list_label_sets() do not include each source’s selection. Call label_set.refetch_data() before you read a source’s label_selection_mode.
To get the Ontology that a version’s labels were made against, as it was when the version was created, call version.get_ontology().

Change a Label Set

Use update() to change a label set’s name or description, and set_label_selection() to change which labels the next version captures. Existing versions are never changed.
Rename a label set and change its selection

Export a Version

You can export any version whose status is READY, in JSON or COCO format. The export is a ZIP file that holds the labels and a label_set_version.json manifest that records which label set and version the export came from. For details of the manifest, see Export a Version. The download link is valid for seven days. Each time you call get_export_job(), you get a new link.
Export a version