Text Files

Import Text Regions to Text Files

A single text region object label can be added at a character range between start and end using range.

Text Region Ontology

Text Regions - Text Files - Basic

from encord import EncordUserClient, Project
from encord.objects import Object, ObjectInstance
from encord.objects.coordinates import TextCoordinates
from encord.objects.frames import Range
from encord.objects.attributes import RadioAttribute, TextAttribute, Option

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the unique Project ID
BUNDLE_SIZE = 100

# Authorize connection to Encord
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use domain="https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Get project
project: Project = user_client.get_project(PROJECT_ID)
assert project is not None, f"Project with ID {PROJECT_ID} not found."

# Ontology verification
ontology_structure = project.ontology_structure
assert ontology_structure is not None, "Ontology structure not found in the project."

text_object: Object = ontology_structure.get_child_by_title(title="Edit", type_=Object)
assert text_object is not None, "Ontology object for 'Edit' not found."

correction_radio_attribute = ontology_structure.get_child_by_title(
    type_=RadioAttribute, title="Corrections"
)
assert correction_radio_attribute is not None, "Radio attribute 'Corrections' not found."

english_correction_option = correction_radio_attribute.get_child_by_title(
    type_=Option, title="English corrections"
)
assert english_correction_option is not None, "Option 'English corrections' not found under 'Corrections'."

english_correction_text_attribute = english_correction_option.get_child_by_title(
    type_=TextAttribute, title="Correction text"
)
assert english_correction_text_attribute is not None, (
    "Text attribute 'Correction text' not found under 'English corrections'."
)

# Labels
text_annotations = {
    "paradise-lost.txt": [
        {
            "label_ref": "text_region_001",
            "coordinates": Range(start=5000, end=5050),
            "correction_text": "This needs to be updated for clarity.",
        },
        {
            "label_ref": "text_region_002",
            "coordinates": Range(start=6000, end=6050),
            "correction_text": "Rephrase for better readability.",
        },
    ],
    "War and Peace.txt": [
        {
            "label_ref": "text_region_003",
            "coordinates": Range(start=3000, end=3050),
            "correction_text": "Grammar correction required.",
        },
        {
            "label_ref": "text_region_004",
            "coordinates": Range(start=4000, end=4050),
            "correction_text": "Check for historical accuracy.",
        },
    ],
}

# Initialize label rows
label_row_map = {}

with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for data_title in text_annotations.keys():
        label_rows = project.list_label_rows_v2(data_title_eq=data_title)
        if not label_rows:
            print(f"Skipping: No label row found for {data_title}")
            continue
        lr = label_rows[0]
        lr.initialise_labels(bundle=bundle)
        label_row_map[data_title] = lr

# Apply labels
label_rows_to_save = []

for data_title, annotations in text_annotations.items():
    lr = label_row_map.get(data_title)
    if lr is None:
        print(f"Skipping: No initialized label row found for {data_title}")
        continue

    for ann in annotations:
        coord = TextCoordinates(range=[ann["coordinates"]])

        inst: ObjectInstance = text_object.create_instance()
        inst.set_for_frames(frames=0, coordinates=coord)
        inst.set_answer(attribute=correction_radio_attribute, answer=english_correction_option)
        inst.set_answer(attribute=english_correction_text_attribute, answer=ann["correction_text"])
        lr.add_object_instance(inst)

        print(f"Added [English correction] text region {ann['label_ref']} to {data_title}")

    label_rows_to_save.append(lr)

# Save label rows
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for lr in label_rows_to_save:
        lr.save(bundle=bundle)
        print(f"Saved label row for {lr.data_title}")

print("English correction labels applied.")

# Import dependencies
from encord import EncordUserClient, Project
from encord.objects import ChecklistAttribute, Object, ObjectInstance, Option, RadioAttribute, TextAttribute
from encord.objects.coordinates import TextCoordinates
from encord.objects.frames import Range

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the unique Project ID
BUNDLE_SIZE = 100

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Get project
project: Project = user_client.get_project(PROJECT_ID)
assert project is not None, f"Project with ID {PROJECT_ID} not found."

# Get ontology structure
ontology_structure = project.ontology_structure
assert ontology_structure is not None, "Ontology structure not found in the project."

# Find ontology object for Text Region
text_object: Object = ontology_structure.get_child_by_title(title="Edit", type_=Object)
assert text_object is not None, "Ontology object for 'Edit' not found."

# Define radio attributes for corrections
correction_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Corrections")
assert correction_radio_attribute is not None, "Radio attribute 'Corrections' not found."

english_correction_option = correction_radio_attribute.get_child_by_title(type_=Option, title="English corrections")
assert english_correction_option is not None, (
    "Option 'English corrections' not found under 'Corrections' radio attribute."
)

chinese_correction_option = correction_radio_attribute.get_child_by_title(type_=Option, title="繁體中文修正")
assert chinese_correction_option is not None, "Option '繁體中文修正' not found under 'Corrections' radio attribute."

# Define checklist attributes for each correction type
english_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="English")
assert english_checklist_attribute is not None, "Checklist attribute 'English' not found."

en_ca_option = english_checklist_attribute.get_child_by_title(type_=Option, title="en-ca")
assert en_ca_option is not None, "Option 'en-ca' not found under 'English' checklist attribute."

en_gb_option = english_checklist_attribute.get_child_by_title(type_=Option, title="en-gb")
assert en_gb_option is not None, "Option 'en-gb' not found under 'English' checklist attribute."

en_us_option = english_checklist_attribute.get_child_by_title(type_=Option, title="en-us")
assert en_us_option is not None, "Option 'en-us' not found under 'English' checklist attribute."

chinese_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="繁體中文")
assert chinese_checklist_attribute is not None, "Checklist attribute '繁體中文' not found."

zh_tw_option = chinese_checklist_attribute.get_child_by_title(type_=Option, title="zh-tw")
assert zh_tw_option is not None, "Option 'zh-tw' not found under '繁體中文' checklist attribute."

zh_hk_option = chinese_checklist_attribute.get_child_by_title(type_=Option, title="zh-hk")
assert zh_hk_option is not None, "Option 'zh-hk' not found under '繁體中文' checklist attribute."

# Define text attributes for user-provided corrections
english_correction_text_attribute = english_correction_option.get_child_by_title(
    type_=TextAttribute, title="Correction text"
)
assert english_correction_text_attribute is not None, (
    "Text attribute 'Correction text' not found under 'English corrections' option."
)

chinese_correction_text_attribute = ontology_structure.get_child_by_title(type_=TextAttribute, title="更正")
assert chinese_correction_text_attribute is not None, "Text attribute '更正' not found."

# Mapping of text files to multiple text regions with manual corrections
text_annotations = {
    "Paradise Lost.txt": [
        {
            "label_ref": "text_region_001",
            "coordinates": Range(start=5000, end=5050),
            "languages": "en-ca, en-us",
            "correction_text": "This needs to be updated for clarity.",
        },
        {
            "label_ref": "text_region_002",
            "coordinates": Range(start=6000, end=6050),
            "languages": "en-gb, en-us",
            "correction_text": "Rephrase for better readability.",
        },
    ],
    "War and Peace.txt": [
        {
            "label_ref": "text_region_003",
            "coordinates": Range(start=3000, end=3050),
            "languages": "en-ca, en-gb",
            "correction_text": "Grammar correction required.",
        },
        {
            "label_ref": "text_region_004",
            "coordinates": Range(start=4000, end=4050),
            "languages": "en-ca",
            "correction_text": "Check for historical accuracy.",
        },
    ],
}


# Cache label rows after initialization
label_row_map = {}

# First initialize label rows in a bundle
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for data_title in text_annotations.keys():
        label_rows = project.list_label_rows_v2(data_title_eq=data_title)
        assert label_rows is not None, f"Error: label rows retrieval failed for {data_title}."

        if not label_rows:
            print(f"Skipping: No label row found for {data_title}")
            continue

        label_row = label_rows[0]
        label_row.initialise_labels(bundle=bundle)

        # Cache the initialized label row for further use
        label_row_map[data_title] = label_row
        assert data_title in label_row_map, f"Error: Label row for {data_title} not cached correctly."

# Apply annotations
label_rows_to_save = []

for data_title, annotations in text_annotations.items():
    label_row = label_row_map.get(data_title)
    assert label_row is not None, f"Error: No initialized label row found for {data_title}."

    for annotation in annotations:
        selected_languages = annotation.get("languages", "").split(", ")
        assert selected_languages, (
            f"Error: No languages specified for annotation with label_ref {annotation['label_ref']}."
        )

        # Create Object Instance for English corrections if applicable
        if any(lang in ["en-ca", "en-gb", "en-us"] for lang in selected_languages):
            english_instance: ObjectInstance = text_object.create_instance()
            assert english_instance is not None, (
                f"Error: Failed to create ObjectInstance for English corrections for {annotation['label_ref']}."
            )

            english_instance.set_for_frames(
                frames=0,
                coordinates=TextCoordinates(range=[annotation["coordinates"]]),
            )
            assert english_instance.frames == 0, (
                f"Error: Frames not correctly set for English instance of {annotation['label_ref']}."
            )
            assert english_instance.coordinates.range == [annotation["coordinates"]], (
                f"Error: Coordinates not correctly set for English instance of {annotation['label_ref']}."
            )

            english_instance.set_answer(attribute=correction_radio_attribute, answer=english_correction_option)
            assert english_instance.get_answer(correction_radio_attribute) == english_correction_option, (
                "Error: English correction option not set correctly."
            )

            english_selected_options = [
                option
                for lang, option in {"en-ca": en_ca_option, "en-gb": en_gb_option, "en-us": en_us_option}.items()
                if lang in selected_languages
            ]
            assert english_selected_options, (
                f"Error: No options selected for English corrections for {annotation['label_ref']}."
            )

            if english_checklist_attribute and english_selected_options:
                english_instance.set_answer(attribute=english_checklist_attribute, answer=english_selected_options)

            english_instance.set_answer(
                attribute=english_correction_text_attribute, answer=annotation["correction_text"]
            )
            label_row.add_object_instance(english_instance)

        # Create Object Instance for Chinese corrections if applicable
        if any(lang in ["zh-tw", "zh-hk"] for lang in selected_languages):
            chinese_instance: ObjectInstance = text_object.create_instance()
            assert chinese_instance is not None, (
                f"Error: Failed to create ObjectInstance for Chinese corrections for {annotation['label_ref']}."
            )

            chinese_instance.set_for_frames(
                frames=0,
                coordinates=TextCoordinates(range=[annotation["coordinates"]]),
            )
            assert chinese_instance.frames == 0, (
                f"Error: Frames not correctly set for Chinese instance of {annotation['label_ref']}."
            )
            assert chinese_instance.coordinates.range == [annotation["coordinates"]], (
                f"Error: Coordinates not correctly set for Chinese instance of {annotation['label_ref']}."
            )

            chinese_instance.set_answer(attribute=correction_radio_attribute, answer=chinese_correction_option)
            assert chinese_instance.get_answer(correction_radio_attribute) == chinese_correction_option, (
                "Error: Chinese correction option not set correctly."
            )

            chinese_selected_options = [
                option
                for lang, option in {"zh-tw": zh_tw_option, "zh-hk": zh_hk_option}.items()
                if lang in selected_languages
            ]
            assert chinese_selected_options, (
                f"Error: No options selected for Chinese corrections for {annotation['label_ref']}."
            )

            if chinese_checklist_attribute and chinese_selected_options:
                chinese_instance.set_answer(attribute=chinese_checklist_attribute, answer=chinese_selected_options)

            chinese_instance.set_answer(
                attribute=chinese_correction_text_attribute, answer=annotation["correction_text"]
            )
            label_row.add_object_instance(chinese_instance)

        print(f"Added text region {annotation['label_ref']} to {data_title}")

    label_rows_to_save.append(label_row)

# Save changes using a bundle
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for label_row in label_rows_to_save:
        assert label_row is not None, "Error: Label row to save is None."
        label_row.save(bundle=bundle)
        print(f"Saved label row for {label_row.data_title}")

print("Multiple labels with manually provided correction text applied successfully!")

Import Classifications to Text Files

The example for the Classification uses nested attributes with the Ontology structure as follows:

• Accurate?
  • Yes
  • No
    • Correction (text field to provide edits for the correction)

create_instance must use range_only=True for text documents. This includes HTML documents.

Template

# Import dependencies
from typing import List
from pathlib import Path
from encord import EncordUserClient, Project
from encord.objects.frames import Range
from encord.objects import LabelRowV2, Classification, Option, OntologyStructure

SSH_PATH = "<file-path-to-ssh-private-key>"
PROJECT_ID = "<project-unique-id>"

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which predictions are to be added
project: Project = user_client.get_project(PROJECT_ID)

# Specify the data unit to apply classification
label_row = project.list_label_rows_v2(
    data_title_eq="<file-name-for-text-file>.html"
)[0]


# Download the existing labels 
label_row.initialise_labels()

# Get the Ontology structure
ontology_structure: OntologyStructure = label_row.ontology_structure

# Assume that the following radio button classification exists in the Ontology.
radio_ontology_classification: Classification = (
    ontology_structure.get_child_by_title(
        title="<classification-name>", type_=Classification
    )
)

radio_classification_option = radio_ontology_classification.get_child_by_title(
title="<option-name>",
type_=Option
)

# Create classification instance. `range_only=True` is required for HTML documents
radio_classification_instance = radio_ontology_classification.create_instance(range_only=True)

# Set the answer of the classification instance
radio_classification_instance.set_answer(radio_classification_option)

# Select the frames where the classification instance is present. Not required for global classifications
radio_classification_instance.set_for_frames(frames=0)

# Add it to the label row
label_row.add_classification_instance(radio_classification_instance)

# Save labels
label_row.save()

# Import dependencies
from __future__ import annotations
from pathlib import Path
from encord import EncordUserClient, Project
from encord.objects import (
    Classification,
    OntologyStructure,
    LabelRowV2,
    TextAttribute,
    RadioAttribute,
    Option
)
from encord.objects.frames import Range

SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
PROJECT_ID = "8a321a14-5f76-4a12-961b-3b1f2da932gk"

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which predictions are to be added
project: Project = user_client.get_project(PROJECT_ID)

# Specify the data unit to apply classification
label_row = project.list_label_rows_v2(
    data_title_eq="My Text File.txt"
)[0]

label_row.initialise_labels()

ontology_structure: OntologyStructure = label_row.ontology_structure

# Get the parent classification
text_ontology_classification = ontology_structure.get_child_by_title(
    title="Accurate?", type_=Classification
)

# Create an instance of the radio button classification
text_classification_instance = text_ontology_classification.create_instance(range_only=True)

# Get the radio button attribute and option
accurate_radio_attribute = text_ontology_classification.get_child_by_title("Accurate?", type_=RadioAttribute)
not_accurate_option = text_ontology_classification.get_child_by_title(title="No", type_=Option)

# Set the answer for the radio button
text_classification_instance.set_answer(attribute=accurate_radio_attribute, answer=not_accurate_option)

# Get the nested attribute "Correction"
correction_attribute = text_ontology_classification.get_child_by_title("Correction", type_=TextAttribute)

# Set the text for the nested attribute
text_classification_instance.set_answer(attribute=correction_attribute, answer="This page needs to be updated.")

# Set the classification (for text documents) for the entire file
text_classification_instance.set_for_frames(frames=0)

# Add the classification instance to the label row
label_row.add_classification_instance(text_classification_instance)

# Save the label row
label_row.save()

Export Labels for Text Files

Template

# Import dependencies
from encord import EncordUserClient
import json

SSH_PATH= "<file-path-to-ssh-private-key"
PROJECT_ID= "<project-unique-id>"
DATA_UNIT_NAME= "<file-name-of-html-file>"

# Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
project = user_client.get_project(PROJECT_ID)

# Specify the data unit you want to export labels for. Replace <file_name> with the name of your specific data unit.
specific_label_row = project.list_label_rows_v2(
    data_title_eq=DATA_UNIT_NAME
)[0]

# Download label information for the specific data unit
specific_label_row.initialise_labels()

# Print the labels as JSON
print(json.dumps(specific_label_row.to_encord_dict()))

# Import dependencies
from encord import EncordUserClient
import json

SSH_PATH= "/Users/chris-encord/sdk-ssh-private-key.txt"
PROJECT_ID= "7a321a15-5f76-4a12-961b-2b1f2da932bb"
DATA_UNIT_NAME= "My Text File.txt"

# Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
project = user_client.get_project(PROJECT_ID)

# Specify the data unit you want to export labels for. Replace <file_name> with the name of your specific data unit.
specific_label_row = project.list_label_rows_v2(
    data_title_eq=DATA_UNIT_NAME
)[0]

# Download label information for the specific data unit
specific_label_row.initialise_labels()

# Print the labels as JSON
print(json.dumps(specific_label_row.to_encord_dict()))

Remove Labels from Text Files

Template

from encord import EncordUserClient
import json

SSH_PATH= "<file-path-to-ssh-private-key>"
PROJECT_ID= "<project-unique-id>"
DATA_UNIT_NAME= "<file-name-of-html-file>"

# Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
project = user_client.get_project(PROJECT_ID)

# Specify the data unit you want to export labels for. Replace <file_name> with the name of your specific data unit.
specific_label_row = project.list_label_rows_v2(
    data_title_eq=DATA_UNIT_NAME
)[0]


object_to_remove = None
specific_label_row.initialise_labels()
for object_instance in specific_label_row.get_object_instances():
    if object_instance.object_hash == '<label-unique-id>':
        object_to_remove = object_instance

specific_label_row.remove_object(object_to_remove)

specific_label_row.save()

from encord import EncordUserClient
import json

SSH_PATH= "/Users/chris-encord/sdk-ssh-private-key.txt"
PROJECT_ID= "7v321a15-5f76-4a12-961b-2b1f2da932bb"
DATA_UNIT_NAME= "My Text File.txt"

# Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
project = user_client.get_project(PROJECT_ID)

# Specify the data unit you want to export labels for. Replace <file_name> with the name of your specific data unit.
specific_label_row = project.list_label_rows_v2(
    data_title_eq=DATA_UNIT_NAME
)[0]


object_to_remove = None
specific_label_row.initialise_labels()
for object_instance in specific_label_row.get_object_instances():
    if object_instance.object_hash == 'dH3DrglO':
        object_to_remove = object_instance

specific_label_row.remove_object(object_to_remove)

specific_label_row.save()