Open in Colab

GitHub

​
Client

import labelbox as lb
import labelbox.data.annotation_types as lb_types
client = lb.Client(api_key="<YOUR_API_KEY>")

​
Create an ontology

Each Tool and Classification type requires a specific value to be passed when creating the feature.
FeatureClassValue
Bounding boxToolBBOX
PolygonToolPOLYGON
PolylineToolLINE
PointToolPOINT
Segmentation maskToolRASTER_SEGMENTATION
RelationshipToolRELATIONSHIP
EntityToolNER
Message rankingToolMESSAGE_RANKING
Single message selectionToolMESSAGE_SINGLE_SELECTION
Multiple message selectionToolMESSAGE_MULTI_SELECTION
Message step reasoningToolSTEP_REASONING
Fact-checkingToolFACT_CHECKING
Prompt ratingToolPROMPT_ISSUE
RadioClassificationRADIO
ChecklistClassificationCHECKLIST
TextClassificationTEXT
When you create an ontology, specify the media_type parameter, which represents the modality of the data rows that the ontology will be used to label. Certain features are only compatible with certain media types.

​
Specify an ontology media type

The media_type parameter of client.create_ontology defaults to None, but it’s highly recommended to specify one for validation and error handling.
The media_type parameter takes the following values:
  • lb.MediaType.Audio
  • lb.MediaType.Conversational
  • lb.MediaType.Document
  • lb.MediaType.Geospatial_Tile
  • lb.MediaType.Html
  • lb.MediaType.Image
  • lb.MediaType.Simple_Tile
  • lb.MediaType.Text
  • lb.MediaType.Video

​
Create ontologies from new features

You can define new features to build new ontologies. The following code sample shows how to create simple features for upserting into ontologies. To learn more about creating features, see Features. 
object_features = [
    lb.Tool(
        tool=lb.Tool.Type.BBOX,
        name="regulatory-sign",
        color="#ff0000",
    )
]

classification_features = [
lb.Classification(
class_type=lb.Classification.Type.CHECKLIST,
name="Quality Issues",
options=[
lb.Option(value="blurry", label="Blurry"),
lb.Option(value="distorted", label="Distorted")
]
)

]
You can then create an ontology with your defined features either using ontology_builder or client.create_ontology_from_feature_schemas(). 
ontology_builder = lb.OntologyBuilder(
    tools=object_features,
    classifications=classification_features
)

ontology = client.create_ontology(
  "Ontology from new features",
  ontology_builder.asdict(),
  media_type=lb.MediaType.Image
)
For more complex ontology creation examples, see Ontology examples guide .

​
Create from normalized JSON format

  • Users can create ontologies from a JSON definition of the ontology.
  • Each tool type requires a specific value to be passed:
ToolValue
Bounding boxrectangle
Polygonpolygon
Polylineline
Pointpoint
Segmentation maskraster-segmentation
Entitynamed-entity
# This automatically creates new feature schema
ontology_name = "sdk-ontology"
feature_schema_cat_normalized = {
    'tool': 'polygon',
    'name': 'cat',
    'color': 'black'
}

ontology_normalized_json = {
"tools": [feature_schema_cat_normalized],
"classifications": []
}
ontology = client.create_ontology(name=ontology_name,
normalized=ontology_normalized_json,
media_type=lb.MediaType.Image)

​
Create from existing features

If you already have features created, you can query them by name or by schema id. Re-using an existing feature is highly recommended. 
## Search feature by name in your org
regulatory_sign_feature_schema = next(client.get_feature_schemas("regulatory-sign"))
classification_feature = next(client.get_feature_schemas("Quality Issues"))

## Get feature by feature schema ID. Alternatively you can get this from the UI
regulatory_sign_feature_schema = client.get_feature_schema("FEATURE_SCHEMA_ID")

ontology = client.create_ontology_from_feature_schemas("Ontology from existing features", [regulatory_sign_feature_schema.uid, classification_feature.uid], media_type=MediaType.Image)

​
Create a nested ontology

You can create a child feature nested under a parent feature. Only classification features can be children of a nested ontology. For instance, if you want to create an ontology where a bounding box has a radio sub-classification, you will add a classificationsfield that contains a list of classification features as children. 
bbox_with_sub_classification = lb.Tool(tool=lb.Tool.Type.BBOX, name="cat",
         classifications=[
            lb.Classification(class_type=lb.Classification.Type.RADIO, name="radio", options=[
                lb.Option(value="long-fur"),
                lb.Option(value="short-fur")
            ])
         ])

ontology_builder = lb.OntologyBuilder(tools=[
bbox_with_sub_classification
])

ontology = client.create_ontology("Simple nested ontology", ontology_builder.asdict(), media_type=MediaType.Image)

​
Get ontologies

# get by ID
ontology = client.get_ontology("<ontology_id>")

# get by name

ontology = next(client.get_ontologies("<ontology_name>"))

# get multiple ontologies by keyword

ontologies = client.get_ontologies(name_contains="<keyword>")

​
Check if a feature is archived in an ontology

client.is_feature_schema_archived("<ontology_id>", "<feature_schema_id>")

​
Get all unused ontologies

client.get_unused_ontologies()

​
Delete an unused ontology

client.delete_unused_ontology("<ontology_id>")

​
Connect an ontology to a project

# get (or create) a project
project = client.get_project("<project_id>")

# get (or create) an ontology

ontology = client.get_ontology("<ontology_id>")

# the argument must be an object of the Ontology class

project.connect_ontology(ontology)

​
Methods

​
Get the tools

tools = ontology.tools()

for tool in tools:
print(tool)

​
Get the classifications

classifications = ontology.classifications()

for classification in classifications:
print(classification)

​
Attributes

# name (str)
ontology.name

# description (str)

ontology.description

# updated at (datetime)

ontology.updated_at

# created at (datetime)

ontology.created_at

# normalized output of the ontology (JSON)

ontology.normalized

# count of object tools in the ontology (int)

ontology.object_schema_count

# count of classifications in the ontology (int)

ontology.classification_schema_count

# created by (relationship to User object)

user = ontology.created_by()