Define a label tree

Tator supports definition of label trees, hierarchies of labels that are required in many classification tasks. In Tator, label trees are defined via Leaf objects, entities which can be assigned user defined attributes besides just a label and that also have foriegn keys to parents. This document will explain how to create a label tree in Tator using a tator-py example script, as well as how to associate that label tree to a custom attribute for use in the web interface's autocomplete function.

Define the label tree

In the tator-py source tree, a script at examples/leaf.py allows for definition a label tree via a yaml file. Start by creating a yaml file similar to the following or copy this source to a file called got.yaml:

name: GoT # The name of the hierarchy.
children:
- name: Targaryen
  children:
  - name: Maekar I
    children:
    - name: Maester Aemon
    - name: Aegon V
      children:
      - name: Jaehaerys II
        children:
        - name: Aerys II (Mad King)
          children:
          - name: Daenerys
          - name: Viserys
          - name: Rhaegar
            children:
            - name: Aegon
      - name: Rhaelle
- name: Stark
  children:
  - name: Rickard
    children:
    - name: Brandon
    - name: Eddard
      children:
      - name: Robb
      - name: Sansa
      - name: Arya
      - name: Brandon
      - name: Rickon
    - name: Benjen
    - name: Lyanna
- name: Baratheon
  children:
  - name: Ormund
    children:
    - name: Steffon
      children:
      - name: Robert
      - name: Stannis
        children:
        - name: Shireen
      - name: Renly
- name: Lannister
  children:
  - name: Tywin
    children:
    - name: Jaime
    - name: Cersei
      children:
      - name: Joffrey
      - name: Myrcella
      - name: Tommen
    - name: Tyrion

Next we need to create a LeafType object. This can be done in tator-py with the following:

import tator
api = tator.get_api(host='https://cloud.tator.io', token=MY_TOKEN)
leaf_spec = {
    'name': 'leaves',
    'description': 'Simple leaf type',
    'attribute_types': [],
}
response = api.create_leaf_type(PROJECT_ID, leaf_type_spec=leaf_spec)
leaf_type_id = response.id

We can now run the example script on the file and create the Leaf objects, passing in the leaf type ID for TYPE_ID:

python examples/leaf.py --host https://cloud.tator.io --token $MY_TOKEN --type_id TYPE_ID --input got.yaml

Set the autocomplete service

Once a label hierarchy is created, a suggestion service becomes available. The last element in the URI is based on the name of the hierarchy as defined by the root node, in this case GoT. The autocomplete service for the entire tree in this example is available at:

https://cloud.tator.io/rest/Leaves/Suggestion/{project_name}.GoT/{project}

The suggestion service can be scoped to a branch within the tree. For example, to make suggestions for only Lannisters, you can use:

https://cloud.tator.io/rest/Leaves/Suggestion/{project_name}.GoT.Lannister/{project}

note

Spaces, dashes, and parentheses in project_name must be replaced by underscores.

These suggestion services are documented in the REST API reference documentation.

Below is an example where a string attribute with name ATTRIBUTE_TYPE_NAME defined for a media type VIDEO_TYPE is associated with this service for autocompletion. Note that the attribute type could be associated with a localization type, state type, file type, or leaf type as well.

api = tator.get_api(host, token)
video_type_obj = api.get_media_type(VIDEO_TYPE)
project_obj = api.get_project(PROJECT_ID)
attribute_type = {}
for elem in video_type_obj.attribute_types:
    if elem.name == ATTRIBUTE_TYPE_NAME:
        attribute_type = elem
        break
attribute_type.autocomplete = {'serviceUrl': f'/rest/Leaves/Suggestion/{project_obj.name}.GoT/{PROJECT_ID}'}
api.rename_attribute(VIDEO_TYPE, {
    'entity_type': 'MediaType',
    'global': 'true',
    'old_attribute_type_name': ATTRIBUTE_TYPE_NAME,
    'new_attribute_type': attribute_type,
})

Use autocomplete

Now users of the web interface who type at least three letters into the string field will see a suggestion list come up matching to all the leaves defined.