Data Structures

Metrics Data Structure

class ontolearner.data_structure.metric.BenchmarkMetrics(*, total_ontologies: int, ontology_metrics: Dict[str, OntologyMetrics], avg_topology: TopologyMetrics, avg_dataset: DatasetMetrics, topology_std: Dict[str, float], relationship_std: Dict[str, float], dataset_std: Dict[str, float])

Bases: BaseModel

Aggregate metrics across multiple ontologies for benchmarking and analysis.

This class provides comprehensive statistical analysis across a collection of ontologies, enabling comparative studies, quality assessment, and benchmarking of ontology learning approaches. It aggregates individual ontology metrics and computes statistical summaries.

Used for generating benchmark reports, identifying outliers, and understanding the distribution of characteristics across ontology collections. Essential for research comparing ontology learning methods across diverse domains.

total_ontologies

Total number of ontologies included in the benchmark.

Type:

int

ontology_metrics

Dictionary mapping ontology IDs to their individual metrics, preserving detailed information for each.

Type:

Dict[str, ontolearner.data_structure.metric.OntologyMetrics]

avg_topology

Average topology metrics computed across all ontologies, showing typical structural characteristics.

Type:

ontolearner.data_structure.metric.TopologyMetrics

avg_dataset

Average dataset metrics across all ontologies, indicating typical learning data characteristics.

Type:

ontolearner.data_structure.metric.DatasetMetrics

topology_std

Standard deviations of topology metrics, showing structural variability across the ontology collection.

Type:

Dict[str, float]

relationship_std

Standard deviations of relationship metrics, indicating diversity in relationship patterns.

Type:

Dict[str, float]

dataset_std

Standard deviations of dataset metrics, showing variability in learning data quality and quantity.

Type:

Dict[str, float]

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

avg_dataset: DatasetMetrics

avg_topology: TopologyMetrics

dataset_std: Dict[str, float]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ontology_metrics: Dict[str, OntologyMetrics]

relationship_std: Dict[str, float]

topology_std: Dict[str, float]

total_ontologies: int

class ontolearner.data_structure.metric.DatasetMetrics(*, num_term_types: Annotated[int, Ge(ge=0)], num_taxonomic_relations: Annotated[int, Ge(ge=0)], num_non_taxonomic_relations: Annotated[int, Ge(ge=0)], avg_terms: Annotated[float, Ge(ge=0)])

Bases: BaseModel

Metrics for evaluating the quality and characteristics of extracted learning datasets.

This class captures quantitative measures of the machine learning datasets extracted from ontologies, focusing on the three fundamental ontology learning tasks. These metrics help assess dataset quality, balance, and suitability for training and evaluation.

num_term_types

Number of term-to-type mappings extracted for Task 1. Higher values indicate richer type assignment data.

Type:

int

num_taxonomic_relations

Number of hierarchical “is-a” relationships extracted for Task 2. Indicates taxonomy richness.

Type:

int

num_non_taxonomic_relations

Number of semantic associations extracted for Task 3. Shows relationship diversity.

Type:

int

avg_terms

Average number of terms assigned to each type, indicating the distribution balance of the term typing dataset.

Type:

float

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

avg_terms: float

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

num_non_taxonomic_relations: int

num_taxonomic_relations: int

num_term_types: int

class ontolearner.data_structure.metric.OntologyMetrics(*, name: str, topology: TopologyMetrics, dataset: DatasetMetrics)

Bases: BaseModel

Complete metrics collection for a single ontology.

This class aggregates all quantitative measures for an ontology, combining structural topology metrics with dataset extraction metrics. It provides a comprehensive view of an ontology’s characteristics for analysis, comparison, and quality assessment.

Used by the Processor class to collect and export metrics to Excel files for benchmarking and analysis across multiple ontologies.

name

Human-readable name of the ontology for identification.

Type:

str

topology

Structural metrics describing the ontology’s graph properties.

Type:

ontolearner.data_structure.metric.TopologyMetrics

dataset

Dataset metrics describing the extracted learning data quality.

Type:

ontolearner.data_structure.metric.DatasetMetrics

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

dataset: DatasetMetrics

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

topology: TopologyMetrics

class ontolearner.data_structure.metric.TopologyMetrics(*, total_nodes: Annotated[int, Ge(ge=0)], total_edges: Annotated[int, Ge(ge=0)], num_root_nodes: Annotated[int, Ge(ge=0)], num_leaf_nodes: Annotated[int, Ge(ge=0)], num_classes: Annotated[int, Ge(ge=0)], num_properties: Annotated[int, Ge(ge=0)], num_individuals: Annotated[int, Ge(ge=0)], max_depth: Annotated[int, Ge(ge=0)], min_depth: Annotated[int, Ge(ge=0)], avg_depth: Annotated[float, Ge(ge=0)], depth_variance: Annotated[float, Ge(ge=0)], max_breadth: Annotated[int, Ge(ge=0)], min_breadth: Annotated[int, Ge(ge=0)], avg_breadth: Annotated[float, Ge(ge=0)], breadth_variance: Annotated[float, Ge(ge=0)])

Bases: BaseModel

Comprehensive metrics describing the structural properties of an ontology graph.

This class captures quantitative measures of an ontology’s topological structure, including graph connectivity, hierarchical organization, and knowledge coverage. These metrics are essential for understanding ontology complexity, quality, and suitability for different learning tasks.

The metrics are organized into four categories: 1. Basic graph structure (nodes, edges, roots, leaves) 2. Knowledge coverage (classes, properties, individuals) 3. Hierarchical depth characteristics 4. Hierarchical breadth characteristics

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

avg_breadth: float

avg_depth: float

breadth_variance: float

depth_variance: float

max_breadth: int

max_depth: int

min_breadth: int

min_depth: int

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

num_classes: int

num_individuals: int

num_leaf_nodes: int

num_properties: int

num_root_nodes: int

total_edges: int

total_nodes: int

Datasets Structure

class ontolearner.data_structure.data.Document(*, id: int | str, title: str, text: str)

Bases: BaseModel

Schema for a textual document in the corpus.

Represents a single document containing text from which terms and ontological knowledge can be extracted. Forms the basis for text-to-ontology learning workflows.

id

Unique identifier for the document.

Type:

int | str

title

Document title or heading.

Type:

str

text

Full text content of the document.

Type:

str

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

id: int | str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

text: str

title: str

class ontolearner.data_structure.data.DocumentReference(*, doc_id: int | str, extraction_method: str)

Bases: BaseModel

Reference linking a term to a document with extraction metadata.

Represents the relationship between a term and the document it was extracted from, including information about the extraction method used. Enables traceability of terms back to their source documents.

doc_id

Unique identifier for the source document.

Type:

int | str

extraction_method

Method used to extract the term from this document.

Type:

str

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

doc_id: int | str

extraction_method: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ontolearner.data_structure.data.NonTaxonomicRelation(*, ID: str = <factory>, head: str, tail: str, relation: str)

Bases: BaseModel

Schema for non-taxonomic relations (Ontology Learning Task 3).

Represents non-hierarchical relationships between concepts, capturing semantic associations beyond simple “is-a” relationships. These relations express how concepts interact, relate, or depend on each other.

This corresponds to the question: “What is the relationship between A and B?” For example: “Wine” madeFrom “Grape”, “Person” livesIn “City”

ID

Unique identifier with “NR_” prefix (auto-generated).

Type:

str

head

The subject/source entity in the relationship.

Type:

str

tail

The object/target entity in the relationship.

Type:

str

relation

The type of relationship connecting head and tail.

Type:

str

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

ID: str

head: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

relation: str

tail: str

class ontolearner.data_structure.data.NonTaxonomicRelations(*, types: List[str], relations: List[str], non_taxonomies: List[NonTaxonomicRelation])

Bases: BaseModel

Aggregated schema for non-taxonomic relation information in an ontology.

Collects all non-hierarchical relationships, the types involved, and the relation types used, providing a complete view of the non-taxonomic semantic structure of an ontology.

types

List of all types/concepts that participate in non-taxonomic relationships (as either head or tail entities).

Type:

List[str]

relations

List of all unique relation types used in the ontology (e.g., “madeFrom”, “locatedIn”, “hasColor”).

Type:

List[str]

non_taxonomies

List of all non-taxonomic relation instances, defining the semantic associations between concepts.

Type:

List[ontolearner.data_structure.data.NonTaxonomicRelation]

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

non_taxonomies: List[NonTaxonomicRelation]

relations: List[str]

types: List[str]

class ontolearner.data_structure.data.OntologyData(*, term_typings: List[TermTyping], type_taxonomies: TypeTaxonomies, type_non_taxonomic_relations: NonTaxonomicRelations)

Bases: BaseModel

Complete schema for all ontology learning data extracted from an ontology.

This is the main data container that aggregates all three types of ontological information needed for machine learning tasks. It represents the complete structured knowledge extracted from an ontology file.

The three components correspond to the three fundamental ontology learning tasks: 1. Term typing: What types do terms belong to? 2. Taxonomy discovery: What are the hierarchical relationships? 3. Non-taxonomic relation discovery: What are the semantic associations?

term_typings

All term-to-type mappings for learning type prediction.

Type:

List[ontolearner.data_structure.data.TermTyping]

type_taxonomies

All hierarchical relationships and involved types.

Type:

ontolearner.data_structure.data.TypeTaxonomies

type_non_taxonomic_relations

All semantic associations and relation types.

Type:

ontolearner.data_structure.data.NonTaxonomicRelations

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

term_typings: List[TermTyping]

type_non_taxonomic_relations: NonTaxonomicRelations

type_taxonomies: TypeTaxonomies

class ontolearner.data_structure.data.PseudoSentence(*, id: str, pseudo_sentences: List[str], terms: List[str], types: List[str])

Bases: BaseModel

Schema for pseudo-sentence generation with associated metadata.

Represents a batch of artificially generated sentences along with the terms and types they contain. Used in synthetic text-to-ontology generation workflows to create training data.

id

Unique identifier for this pseudo-sentence batch.

Type:

str

pseudo_sentences

List of generated sentence texts.

Type:

List[str]

terms

List of terms that appear in these sentences.

Type:

List[str]

types

List of types associated with the terms.

Type:

List[str]

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

id: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pseudo_sentences: List[str]

terms: List[str]

types: List[str]

class ontolearner.data_structure.data.SyntheticText2OntoData(*, child_to_parent: Dict[str, List[str]], pseudo_sentences: List[PseudoSentence], generated_docs: List[Document])

Bases: BaseModel

Schema for synthetic text-to-ontology generation data.

Aggregates all data produced by synthetic text generation workflows, including hierarchical mappings, pseudo-sentences, and generated documents. Used to create artificial training corpora for text-to-ontology learning.

This schema supports workflows that generate synthetic text from existing ontological structures to augment training data or create controlled experimental conditions.

child_to_parent

Hierarchical mapping showing parent-child relationships between terms, derived from ontological taxonomies.

Type:

Dict[str, List[str]]

pseudo_sentences

List of generated pseudo-sentence batches with associated terms and types.

Type:

List[ontolearner.data_structure.data.PseudoSentence]

generated_docs

Complete documents generated from pseudo-sentences, ready for use in text-to-ontology pipelines.

Type:

List[ontolearner.data_structure.data.Document]

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

child_to_parent: Dict[str, List[str]]

generated_docs: List[Document]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pseudo_sentences: List[PseudoSentence]

class ontolearner.data_structure.data.TaxonomicRelation(*, ID: str = <factory>, parent: str, child: str)

Bases: BaseModel

Schema for taxonomic relations (Ontology Learning Task 2).

Represents hierarchical “is-a” relationships between concepts, which form the taxonomic backbone of ontologies. Each instance captures a parent-child relationship that defines the ontological hierarchy.

This corresponds to the question: “Is concept A a parent of concept B?” For example: “Wine” is-a-parent-of “RedWine” → True

ID

Unique identifier with “TR_” prefix (auto-generated).

Type:

str

parent

The more general concept in the hierarchy.

Type:

str

child

The more specific concept that is a subclass of parent.

Type:

str

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

ID: str

child: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parent: str

class ontolearner.data_structure.data.Term(*, term: Annotated[str, MinLen(min_length=1)], extraction_method: str = 'abstractive')

Bases: BaseModel

Schema for a term extracted from textual documents.

Represents a single term (word or phrase) that has been identified and extracted from text using either extractive or abstractive methods. Used in text-to-ontology workflows for term identification.

term

The extracted term text (minimum 1 character).

Type:

str

extraction_method

Method used for extraction, either “extractive” (directly from text) or “abstractive” (generated/inferred).

Type:

str

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

extraction_method: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

term: str

class ontolearner.data_structure.data.TermTyping(*, ID: str = <factory>, term: str, types: ~typing.List[str])

Bases: BaseModel

Schema for term typing data (Ontology Learning Task 1).

Represents the assignment of semantic types to terms, which is the first fundamental task in ontology learning. Each instance captures a term and its associated types, enabling machine learning models to learn patterns for predicting types of new terms.

This corresponds to the question: “What type(s) does this term belong to?” For example: “Chardonnay” → [“WhiteWine”, “Wine”, “AlcoholicBeverage”]

ID

Unique identifier with “TT_” prefix (auto-generated).

Type:

str

term

The term being classified (e.g., “Chardonnay”, “Einstein”).

Type:

str

types

List of semantic types assigned to the term. Can be multiple types due to multiple inheritance in ontologies.

Type:

List[str]

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

ID: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

term: str

types: List[str]

class ontolearner.data_structure.data.TextualData(*, terms: List[Term] = [], documents: List[Document] = [], term2documents: Dict[str, List[DocumentReference]] = {})

Bases: BaseModel

Schema for textual data from a single processing split.

Aggregates all textual information for a specific data split, including extracted terms, source documents, and the mapping between them. Used in text-to-ontology pipelines to organize and track relationships between terms and their source documents.

terms

List of terms extracted from the documents.

Type:

List[ontolearner.data_structure.data.Term]

documents

List of source documents in this split.

Type:

List[ontolearner.data_structure.data.Document]

term2documents

Mapping from term strings to lists of document references showing which documents contain each term.

Type:

Dict[str, List[ontolearner.data_structure.data.DocumentReference]]

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

documents: List[Document]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

term2documents: Dict[str, List[DocumentReference]]

terms: List[Term]

class ontolearner.data_structure.data.TypeTaxonomies(*, types: List[str], taxonomies: List[TaxonomicRelation])

Bases: BaseModel

Aggregated schema for taxonomic information in an ontology.

Collects all taxonomic relationships and the types involved in them, providing a complete view of the hierarchical structure of an ontology. Used to organize and access all “is-a” relationships for learning tasks.

types

Complete list of all types/concepts that participate in taxonomic relationships (both as parents and children).

Type:

List[str]

taxonomies

List of all taxonomic relations in the ontology, defining the hierarchical structure.

Type:

List[ontolearner.data_structure.data.TaxonomicRelation]

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

taxonomies: List[TaxonomicRelation]

types: List[str]