otx.api.entities.label_schema#

This module implements the LabelSchema entity.

Functions

natural_sort_label_id(target)

Generates a natural sort key for a LabelEntity object based on its ID.

Classes

`LabelGroup`(name, labels[, group_type, id])	A label group which has exclusive (multiclass) or contains the empty label.
`LabelGroupType`(value)	Enum to indicate the LabelGroupType.
`LabelSchemaEntity`([label_tree, label_groups])	This class represents the relationships of labels.
`LabelTree`()	Represents a hierarchy of labels in the form a tree.

Exceptions

`LabelGroupDoesNotExistException`	Exception thrown if the LabelGroup does not exist.
`LabelGroupExistsException`	Exception thrown if the LabelGroup already exists.

exception otx.api.entities.label_schema.LabelGroupDoesNotExistException[source]#

Bases: ValueError

Exception thrown if the LabelGroup does not exist.

exception otx.api.entities.label_schema.LabelGroupExistsException[source]#

Bases: ValueError

Exception thrown if the LabelGroup already exists.

class otx.api.entities.label_schema.LabelGroup(name: str, labels: Sequence[LabelEntity], group_type: LabelGroupType = LabelGroupType.EXCLUSIVE, id: ID | None = None)[source]#

Bases: object

A label group which has exclusive (multiclass) or contains the empty label.

Non-exclusive (multilabel) relationships are represented by multiple (exclusive) label groups.

The labels have to be from one task.

Parameters:

name (str) – Descriptive name of the label group
labels (Sequence[LabelEntity]) – Labels that form the group
group_type (LabelGroupType) – EXCLUSIVE or EMPTY_LABEL
id (ID) – ID of the LabelGroup. If no ID is provided, a new ObjectId() will be assigned

is_single_label() → bool[source]#

Returns True if the label group only contains one label.

Returns:: True if the label group only contains one label.
Return type:: bool

remove_label(label: LabelEntity) → None[source]#

Remove label from label group if it exists in the group.

Parameters:: label (LabelEntity) – label to remove

property id: ID#: DEPRECATED.

property minimum_label_id: ID#: Returns the minimum (oldest) label ID, which is the first label in self.labels since this list is sorted.

class otx.api.entities.label_schema.LabelGroupType(value)[source]#

Bases: Enum

Enum to indicate the LabelGroupType.

class otx.api.entities.label_schema.LabelSchemaEntity(label_tree: LabelTree | None = None, label_groups: List[LabelGroup] | None = None)[source]#

Bases: object

This class represents the relationships of labels.

This class currently keeps track of the following relationships:

parent/child label relationship
label group relationships

Parameters:

label_tree (LabelTree) – a hierarchy of labels represented as a tree
label_groups (List[LabelGroup]) – list of groups of labels that form logical groups. E.g. a group of mutually exclusive labels.

add_child(parent: LabelEntity, child: LabelEntity)[source]#: Add a child Label to parent.

add_group(label_group: LabelGroup)[source]#

Adding a group to label schema.

Parameters:: label_group (LabelGroup) – label group to add
Returns:: None

add_labels_to_group_by_group_name(group_name: str, labels: Sequence[LabelEntity])[source]#

Adds labels to group named group_name.

Parameters:

labels (str) – list of Label
group_name (Sequence[LabelEntity]) – group name

Raises:

LabelGroupDoesNotExistException – This is raised if the group does not exist

are_exclusive(label1: LabelEntity, label2: LabelEntity) → bool[source]#: Returns whether label and label2 are mutually exclusive.

classmethod from_labels(labels: Sequence[LabelEntity]) → LabelSchemaEntity[source]#

Create LabelSchemaEntity from a list of exclusive labels.

Parameters:: labels (Sequence[LabelEntity]) – list of labels
Returns:: LabelSchemaEntity from the given labels

get_ancestors(label: LabelEntity) → List[LabelEntity][source]#: Returns ancestors of label, including self.

get_children(parent: LabelEntity) → List[LabelEntity][source]#: Return a list of the children of the passed parent Label.

get_descendants(parent: LabelEntity) → List[LabelEntity][source]#: Returns descendants (children and children of children, etc.) of parent.

get_exclusive_groups() → List[LabelGroup][source]#: Returns exclusive groups in the LabelSchema.

get_group_containing_label(label: LabelEntity) → LabelGroup | None[source]#

Returns the label group which contains the label.

Parameters:: label (LabelEntity) – the query label
Returns:: the group containing the label
Return type:: Optional[LabelGroup]

get_groups(include_empty: bool = False) → List[LabelGroup][source]#

Get the label groups in the label schema.

Parameters:: include_empty (bool) – flag determining whether to include empty label groups
Returns:: list of all label groups in the label schema
Return type:: List[LabelGroup]

get_label_group_by_name(group_name: str) → LabelGroup | None[source]#

Get the label group by the passed group_name.

Parameters:: group_name (str) – name of the group to get
Returns:: Optional[LabelGroup]

get_label_ids(include_empty: bool) → List[ID][source]#

Returns a list of label ids that are in the LabelSchema.

Parameters:: include_empty (bool) – Include empty label id or not.
Returns:: sorted list of label ids
Return type:: List[ID]

get_labels(include_empty: bool) → List[LabelEntity][source]#

Get the labels in the label schema.

Parameters:: include_empty (bool) – flag determining whether to include empty labels
Returns:: list of all labels in the label schema
Return type:: List[LabelEntity]

get_labels_exclusive_to(label: LabelEntity) → List[LabelEntity][source]#: Returns a list of labels that are exclusive to the passed label.

get_parent(label: LabelEntity) → LabelEntity | None[source]#

Returns the parent of label.

Returns:: the parent if it has one otherwise None
Return type:: Optional[LabelEntity]

get_siblings_in_group(label: LabelEntity) → List[LabelEntity][source]#: Return a list of the ‘siblings’, which are all labels within the same group as a label.

resolve_labels_greedily(scored_labels: List[ScoredLabel]) → List[ScoredLabel][source]#

Resolves hierarchical labels and exclusivity based on a list of ScoredLabels (labels with probability).

The following two steps are taken:

select the most likely label from each label group
add it and it’s predecessors if they are also most likely labels (greedy approach).

Parameters:: scored_labels (List[LabelEntity]) – list of labels to resolve
Returns:: List of ScoredLabels (labels with probability)
Return type:: List[ScoredLabel]

resolve_labels_probabilistic(scored_labels: List[ScoredLabel], selected_labels: List[LabelEntity] | None = None) → List[ScoredLabel][source]#

Resolves hierarchical labels and exclusivity based on a list of ScoredLabels (labels with probability).

The following two steps are taken:

selects the most likely label from an exclusive (multiclass) group
removes children of “not-most-likely” (non-max) parents in an exclusive group (top-down approach)

The method is intended to post-process the output of probabilistic systems such as predictions coming from machine learning methods to resolve ambiguities and logical impossibilities. When processing (non-probabilistic) user input please use complete_labels instead.

Parameters:

scored_labels (List[ScoredLabel]) – a list of ScoredLabels (labels with probability)
selected_labels (List[LabelEntity]) – if not None, will only consider labels within selected_labels for resolving. Any other labels which have relations with selected_labels (e.g. parent), but are outside selected_labels are set to a default probability of 1.0

class otx.api.entities.label_schema.LabelTree[source]#

Bases: MultiDiGraph

Represents a hierarchy of labels in the form a tree.

The tree is represented by a directed graph

add_child(parent: LabelEntity, child: LabelEntity)[source]#: Add a child Label to parent.

add_edge(node1, node2, edge_value=None)[source]#

Add edge between two nodes in the tree.

Parameters:

node1 – first node
node2 – second node
edge_value – The value of the new edge. Defaults to None.

add_edges(edges)[source]#: Add edges between Labels.

add_node(node)[source]#: Add node to the tree.

clear_topological_cache()[source]#

Clear the internal cache of the list of labels sorted in topological order.

This function should be called if the topology of the graph has changed to: prevent the cache from being stale.
Note that it is automatically called when modifying the topology through the: methods provided by this class.

get_ancestors(label: LabelEntity) → List[LabelEntity][source]#: Returns ancestors of label, including self.

get_children(parent: LabelEntity) → List[LabelEntity][source]#: Returns children of parent.

get_descendants(parent: LabelEntity) → List[LabelEntity][source]#: Returns descendants (children and children of children, etc.) of parent.

get_labels_in_topological_order() → List[LabelEntity][source]#

Return a list of the labels in this graph sorted in topological order.

To avoid performance issues, the output of this function is cached.

Returns:: sorted list of labels
Return type:: List[LabelEntity]

get_parent(label: LabelEntity) → LabelEntity | None[source]#

Returns the parent of label.

Returns:: the parent if it has one otherwise None

get_siblings(label: LabelEntity) → List[LabelEntity][source]#: Returns the siblings of a label.

remove_node(node)[source]#: Remove node from the tree.

subgraph(labels: Sequence[LabelEntity]) → LabelTree[source]#: Return the subgraph containing the given labels.

property num_labels#: Return the number of labels in the tree.

property type#: Returns the type of the LabelTree.

otx.api.entities.label_schema.natural_sort_label_id(target: ID | LabelEntity | ScoredLabel) → List[int | str][source]#

Generates a natural sort key for a LabelEntity object based on its ID.

Args: target (Union[ID, LabelEntity]): The ID or LabelEntity or ScoredLabel object to be sorted.

Returns: List[Union[int, str]]: A list of integers representing the numeric substrings in the ID in the order they appear.

Example: origin_sorted_labels = sorted(labels, key=lambda x: x.id_) natural_sorted_labels = sorted(labels, key=lambda x: x.natural_sort_label_id)

print(origin_sorted_labels) # Output: [LabelEntity(0), LabelEntity(1), LabelEntity(10), … LabelEntity(2)] print(natural_sorted_labels) # Output: [LabelEntity(0), LabelEntity(1), LabelEntity(2), … LabelEntity(10)]