Ontology

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.

Feature	Class	Value
Bounding box	`Tool`	`BBOX`
Polygon	`Tool`	`POLYGON`
Polyline	`Tool`	`LINE`
Point	`Tool`	`POINT`
Segmentation mask	`Tool`	`RASTER_SEGMENTATION`
Relationship	`Tool`	`RELATIONSHIP`
Entity	`Tool`	`NER`
Message ranking	`Tool`	`MESSAGE_RANKING`
Single message selection	`Tool`	`MESSAGE_SINGLE_SELECTION`
Multiple message selection	`Tool`	`MESSAGE_MULTI_SELECTION`
Message step reasoning	`Tool`	`STEP_REASONING`
Fact-checking	`Tool`	`FACT_CHECKING`
Prompt rating	`Tool`	`PROMPT_ISSUE`
Radio	`Classification`	`RADIO`
Checklist	`Classification`	`CHECKLIST`
Text	`Classification`	`TEXT`

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
)

# First create the feature schema
feature_schema_cat = client.create_feature_schema(feature_schema_cat_normalized)
# When we create the ontology it will not re-create the feature schema
print(feature_schema_cat.uid)
ontology = client.create_ontology_from_feature_schemas(ontology_name,
                                                       [feature_schema_cat.uid])

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:

Tool	Value
Bounding box	`rectangle`
Polygon	`polygon`
Polyline	`line`
Point	`point`
Segmentation mask	`raster-segmentation`
Entity	`named-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)

radio_with_sub_classification = Classification( 
      class_type=Classification.Type.RADIO, 
      instructions="radio_question_sub", 
      options=[
        Option(value="first_radio_answer",
               options=[
                   Classification(
                    class_type=Classification.Type.RADIO,
                    instructions="sub_radio_question",
                    options=[
                      Option(value="first_sub_radio_answer"),
                      Option(value="second_sub_radio_answer")
                    ]
                  ),
            ])],
    )

ontology_builder = OntologyBuilder(classifications=[
    sub_radio_classification
])

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

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()

Client

Create an ontology

🚧Specify an ontology media type

Create ontologies from new features

Create from normalized JSON format

Create from existing features

Create a nested ontology

Get ontologies

Check if a feature is archived in an ontology

Get all unused ontologies

Delete an unused ontology

Connect an ontology to a project

Methods

Get the tools

Get the classifications

Attributes

🚧
Specify an ontology media type