Label set

Label sets capture the labels of a project branch into frozen versions. A label set names a project branch as its source and, optionally, a selection of that branch’s labels. Creating a version captures every selected label at its current revision into a new version. A version never changes once it is READY, so it can be exported again later or compared with another version. Entry points are on EncordUserClient: create_label_set, get_label_set and list_label_sets.

LabelSet Objects

class LabelSet()

A label set: a project branch, which of its labels to capture, and the versions created from them. Obtain one with get_label_set(), list_label_sets() or create_label_set().

id

@property
def id() -> UUID

Get the unique identifier of the label set. Returns:

UUID - The label set ID.

name

@property
def name() -> str

Get the name of the label set. Returns:

str - The name.

description

@property
def description() -> str

Get the description of the label set. Returns:

str - The description, empty when none was given.

origin

@property
def origin() -> LabelSetOrigin

Get where the set’s labels come from. Returns:

LabelSetOrigin - WORKFLOW for labels made in the project, IMPORT for labels written to the branch from outside, such as model predictions.

sources

@property
def sources() -> List[StoredSource]

Get the project branches that feed the set, each with its selection. A listed source carries its ID, project and branch. To read its selection, call refetch_data() on the label set and read sources again. Returns:

List[StoredSource] - One StoredProjectSource today: the project, the branch a version captures, and its label_selection (AllSelection when a version captures every label on the branch). An UnknownSource is a kind of source this SDK version does not recognize.

Example:

source = label_set.sources[0]
if isinstance(source, StoredProjectSource):
    print(source.project_id, source.branch_name, source.label_selection)

created_by_email

@property
def created_by_email() -> str

Get the email of the user who created the set. Returns:

str - The creator’s email.

created_at

@property
def created_at() -> datetime

Get when the set was created. Returns:

datetime - The creation time.

refetch_data

def refetch_data() -> None

Read the label set again from the platform, including each source’s selection.

update

def update(*,
           name: Optional[str] = None,
           description: Optional[str] = None) -> None

Change the name or the description. An argument left as None is unchanged. Arguments:

name - The new name.
description - The new description. Pass "" to clear it.

Raises:

AuthorisationError - You cannot manage the set.

set_label_selection

def set_label_selection(source_id: Union[str, UUID],
                        selection: LabelSelection) -> None

Replace which labels a version captures from one source. Example:

complete = project.workflow.get_stage(name="Complete")
source = label_set.sources[0]
if isinstance(source, StoredProjectSource):
    label_set.set_label_selection(source.id, WorkflowStageSelection(workflow_stage_ids=[complete.uuid]))
    label_set.set_label_selection(source.id, AllSelection())  # back to every label on the branch

Arguments:

source_id - The source under this label set. Available on listed sources too.
selection - A WorkflowStageSelection (on the main branch only), or AllSelection so that the next version captures every label on the branch.

Raises:

AuthorisationError - You cannot manage the set.
ResourceNotFoundError - The source does not belong to this label set.
EncordException - A stage selection was given for a branch other than main.
ValueError - source_id is a badly formed UUID.

list_versions

def list_versions(*,
                  page_size: Optional[int] = None
                  ) -> Iterator[LabelSetVersion]

List the versions of the set, newest first. Arguments:

page_size - Number of versions per page. Default 100, maximum 100.

Returns:

Iterator[LabelSetVersion] - The versions.

get_version

def get_version(version_id: Union[str, UUID]) -> LabelSetVersion

Get one version of the set. Arguments:

version_id - The version.

Returns:

LabelSetVersion - The version.

Raises:

ValueError - version_id is a badly formed UUID.
ResourceNotFoundError - The version does not exist under this set, or you cannot read it.

create_version_job

def create_version_job(name: Optional[str] = None) -> UUID

Queue a new version of the set’s current selection, and return without waiting. Read the job with get_version_job(); once it is done, the version is available through get_version(). Example:

job_id = label_set.create_version_job("v1")
job = label_set.get_version_job(job_id, timeout_seconds=600)
if isinstance(job, VersionJobDone):
    version = label_set.get_version(job.version_id)

Arguments:

name - A label for the version, shown with its number. None means the number alone.

Returns:

UUID - The job.

Raises:

AuthorisationError - You cannot manage the set.

get_version_job

def get_version_job(job_id: Union[str, UUID],
                    *,
                    timeout_seconds: float = 0) -> VersionJob

Get the state of a version job, waiting up to timeout_seconds for it to finish. Arguments:

job_id - The job, as returned by create_version_job().
timeout_seconds - How long to wait while the job is pending, polling with backoff. 0 reads the state once and returns it. The job is never cancelled; a pending result after the wait means it is still running and can be read again.

Returns:

VersionJob - One of LabelSetJobPending, VersionJobDone with the version it created, VersionJobFailed with the reason (no version was created), or LabelSetJobUnknown for a state this SDK version does not recognize.

Raises:

ValueError - job_id is a badly formed UUID.
ResourceNotFoundError - The job does not exist under this set, or you cannot read it.
EncordException - The platform returned a job state this SDK cannot read.

LabelSetVersion Objects

class LabelSetVersion()

A version of a label set: a frozen record of the labels captured when it was created. Obtain one with get_version() or list_versions(). A new version is queued with create_version_job().

id

@property
def id() -> UUID

Get the unique identifier of the version. Returns:

UUID - The version ID.

label_set_id

@property
def label_set_id() -> UUID

Get the label set the version belongs to. Returns:

UUID - The label set ID.

sources

@property
def sources() -> List[StoredCapturedSource]

Get what the version captured. Returns:

List[StoredCapturedSource] - One CapturedSource today: the project branch the version captured, with the ontology and revision its labels were made against when it was created. An UnknownSource is a kind of source this SDK version does not recognize.

Example:

source = version.sources[0]
if isinstance(source, CapturedSource):
    print(source.ontology_id, source.ontology_version_id)

version_number

@property
def version_number() -> int

Get the position of the version in its set, from 1. Returns:

int - The version number.

name

@property
def name() -> str

Get the name of the version. Returns:

str - The name.

status

@property
def status() -> LabelSetVersionStatus

Get the lifecycle of the version. Returns:

LabelSetVersionStatus - BUILDING, READY or FAILED.

created_by_email

@property
def created_by_email() -> str

Get the email of the user who created the version. Returns:

str - The creator’s email.

capture_started_at

@property
def capture_started_at() -> datetime

Get when the capture started. Returns:

datetime - The start time.

capture_finished_at

@property
def capture_finished_at() -> Optional[datetime]

Get when the capture finished. Returns:

Optional[datetime] - The finish time, or None while the version is building.

label_count

@property
def label_count() -> Optional[int]

Get how many labels the version holds. Returns:

Optional[int] - The count, or None until the version is READY.

refetch_data

def refetch_data() -> None

Read the version again from the platform.

get_ontology

def get_ontology() -> OntologyStructure

Get the ontology the version’s labels were made against, as it was when the version was created. Compare this rather than the ids on sources: editing a shared class changes the definition without a new revision, so two versions can share a revision id and still differ. Returns:

OntologyStructure - The frozen ontology.

list_members

def list_members(*,
                 page_size: Optional[int] = None
                 ) -> Iterator[LabelSetVersionMember]

List the labels the version holds, each at the revision captured, in label ID order. Arguments:

page_size - Number of labels per page. Default 100, maximum 100.

Returns:

Iterator[LabelSetVersionMember] - The labels, with the storage item each one was on.

create_export_job

def create_export_job(format: ExportFormat = ExportFormat.JSON) -> UUID

Queue an export of the labels the version holds, and return without waiting. Read the job with get_export_job(); once it is done, it carries a link to the archive. Example:

job_id = version.create_export_job(ExportFormat.COCO)
job = version.get_export_job(job_id, timeout_seconds=600)
if isinstance(job, VersionExportJobDone):
    archive = requests.get(job.signed_url).content

Arguments:

format - Format of the export.

Returns:

UUID - The job.

Raises:

AuthorisationError - You cannot manage the captured project.

get_export_job

def get_export_job(job_id: Union[str, UUID],
                   *,
                   timeout_seconds: float = 0) -> VersionExportJob

Get the state of an export job, waiting up to timeout_seconds for it to finish. Arguments:

job_id - The job, as returned by create_export_job().
timeout_seconds - How long to wait while the job is pending, polling with backoff. 0 reads the state once and returns it. The job is never cancelled; a pending result after the wait means it is still running and can be read again.

Returns:

VersionExportJob - One of LabelSetJobPending, VersionExportJobDone with a link to the archive, valid for seven days and renewed on each read, VersionExportJobFailed, or LabelSetJobUnknown for a state this SDK version does not recognize.

Raises:

ValueError - job_id is a badly formed UUID.
ResourceNotFoundError - The job does not exist under this version, or you cannot read it.
EncordException - The platform returned a job state this SDK cannot read.

Get Started

General

Data

Ontologies

Projects

Labels

DICOM

LabelSet Objects

id

name

description

origin

sources

created_by_email

created_at

refetch_data

update

set_label_selection

list_versions

get_version

create_version_job

get_version_job

LabelSetVersion Objects

id

label_set_id

sources

version_number

name

status

created_by_email

capture_started_at

capture_finished_at

label_count

refetch_data

get_ontology

list_members

create_export_job

get_export_job