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.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
mainonly. Workflow tasks exist on themainbranch only, so aWorkflowStageSelectioncannot 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:create_version_job()(orcreate_export_job()) queues the job and returns its ID straight away.get_version_job()(orget_export_job()) reads the job’s state. Passtimeout_secondsto wait for the job to finish. With the default of0, the method reads the state once and returns.
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 themain branch instead, leave out label_selection.
Create a label set and a version
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 withorigin=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
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. Each label that a version holds is a label row: one data unit’s labels on the source branch.
List label sets, versions, and labels
Find a Label Set by Name
get_label_set() takes a label set ID. To find a Label Set by its name, list the label sets that a Project feeds and match the name. Label set names do not have to be unique, so the following example uses the newest match. It also gets a version by its number, or the newest version.
Find a label set and a version by name or number
Get the Labels and Ontology of a Version
A version records which label rows it holds, and the revision of each one that it captured. Use the following to read what a version holds:The SDK does not return a version’s labels as label rows. A member’s
label_id is the label row’s ID, but project.list_label_rows_v2(label_hashes=[...]) returns the label row as it is now, which can differ from the revision the version captured. To work with the labels a version froze, export the version.Get the label rows and Ontology of a version
Compare Two Versions
Each version captures every label row that matches the selection at that time. A label row that has not changed since the previous version keeps the same revision, so you can compare the members of two versions to see what changed between them:- Unchanged: in both versions, at the same revision.
- Revised: in both versions, at a newer revision in the later version. For example, a task that was relabeled.
- Added: only in the later version. For example, a task that reached the selected Workflow stage after the earlier version was created.
- Removed: only in the earlier version. For example, a task that left the selected Workflow stage.
Compare two versions of a label set
Change a Label Set
Useupdate() 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 isREADY, 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.
The following example exports a version, downloads the ZIP file, and reads the manifest to confirm which label set and version the file holds.
Export a version

