### Install Huggingface Datasets package

Source: https://krr-oxford.github.io/DeepOnto/ontolama

Install the Huggingface datasets package to access OntoLAMA datasets. This is a prerequisite for using the Huggingface platform for data access.

```bash
pip install datasets

```

--------------------------------

### Install DeepOnto with OntoLAMA support

Source: https://krr-oxford.github.io/DeepOnto

Install DeepOnto with optional OntoLAMA support, which requires the 'openprompt' package. This command installs 'openprompt' as a dependency.

```bash
pip install deeponto[ontolama]
```

--------------------------------

### Install DeepOnto from PyPI

Source: https://krr-oxford.github.io/DeepOnto

Install the DeepOnto package from PyPI. Requires Python 3.8 or higher. Other dependencies are installed automatically.

```bash
# requiring Python>=3.8
pip install deeponto
```

--------------------------------

### Generate Input Examples for OntoLAMA

Source: https://krr-oxford.github.io/DeepOnto/deeponto/complete/ontolama

Loads an OntoLAMA dataset and transforms its data points into input examples suitable for prompt-based inference. Handles different data field names for datasets like 'bimnli'.

```python
def get_examples(self, task_name, split):
    """Load a specific OntoLAMA dataset and transform the data points into
    input examples for prompt-based inference.
    """

    dataset = self.load_dataset(task_name, split)

    premise_name = "v_sub_concept"
    hypothesis_name = "v_super_concept"
    # different data fields for the bimnli dataset
    if "bimnli" in task_name:
        premise_name = "premise"
        hypothesis_name = "hypothesis"

    prompt_samples = []
    for samp in dataset:
        inp = InputExample(text_a=samp[premise_name], text_b=samp[hypothesis_name], label=samp["label"])
        prompt_samples.append(inp)

    return prompt_samples
```

--------------------------------

### Install DeepOnto from Git Repository

Source: https://krr-oxford.github.io/DeepOnto

Install the latest version of DeepOnto directly from its GitHub repository. This is useful for accessing unreleased features.

```bash
pip install git+https://github.com/KRR-Oxford/DeepOnto.git
```

--------------------------------

### get_examples(task_name, split)

Source: https://krr-oxford.github.io/DeepOnto/deeponto/complete/ontolama

Loads an OntoLAMA dataset and transforms its data points into input examples suitable for prompt-based inference.

```APIDOC
## get_examples(task_name, split)

### Description
Load a specific OntoLAMA dataset and transform the data points into input examples for prompt-based inference.

### Parameters
- **task_name** (str) - The name of the task/dataset to load.
- **split** (str) - The data split to load (e.g., 'train', 'test').

### Returns
- **list[InputExample]**: A list of InputExample objects ready for prompt-based inference.
```

--------------------------------

### Load Default BERTMap Configuration

Source: https://krr-oxford.github.io/DeepOnto/bertmap

Load the default configuration file for BERTMap. This is useful for starting with a standard setup.

```python
from deeponto.align.bertmap import BERTMapPipeline, DEFAULT_CONFIG_FILE

config = BERTMapPipeline.load_bertmap_config(DEFAULT_CONFIG_FILE)

```

--------------------------------

### Install PyTorch with CUDA 11.6

Source: https://krr-oxford.github.io/DeepOnto

Install PyTorch with CUDA 11.6 support. This command is known to work and can be used if the latest PyTorch version causes compatibility issues.

```bash
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu116
```

--------------------------------

### train

Source: https://krr-oxford.github.io/DeepOnto/deeponto/complete/bertsubs

Initiates the Huggingface trainer with provided arguments and starts the training process. Can optionally skip fine-tuning.

```APIDOC
## train(train_args, do_fine_tune=True)

### Description
Initiate the Huggingface trainer with input arguments and start training.

### Parameters
#### Path Parameters
- **train_args** (TrainingArguments) - Required - Arguments for training.
- **do_fine_tune** (bool) - Optional - `False` means loading the checkpoint without training. Defaults to `True`.
```

--------------------------------

### BERTSubsumptionClassifierTrainer Setup and Fine-tuning

Source: https://krr-oxford.github.io/DeepOnto/deeponto/complete/bertsubs

Initializes the BERTSubsumptionClassifierTrainer, configures training arguments, and performs fine-tuning if enabled. It handles special token addition and model saving.

```python
start_time = datetime.datetime.now()
torch.cuda.empty_cache()
bert_trainer = BERTSubsumptionClassifierTrainer(
    config.fine_tune.pretrained,
    train_data=tr,
    val_data=va,
    max_length=config.prompt.max_length,
    early_stop=config.fine_tune.early_stop,
)

epoch_steps = len(bert_trainer.tra) // config.fine_tune.batch_size  # total steps of an epoch
logging_steps = int(epoch_steps * 0.02) if int(epoch_steps * 0.02) > 0 else 5
eval_steps = 5 * logging_steps
training_args = TrainingArguments(
    output_dir=config.fine_tune.output_dir,
    num_train_epochs=config.fine_tune.num_epochs,
    per_device_train_batch_size=config.fine_tune.batch_size,
    per_device_eval_batch_size=config.fine_tune.batch_size,
    warmup_ratio=config.fine_tune.warm_up_ratio,
    weight_decay=0.01,
    logging_steps=logging_steps,
    logging_dir=f"{config.fine_tune.output_dir}/tb",
    eval_steps=eval_steps,
    evaluation_strategy="steps",
    do_train=True,
    do_eval=True,
    save_steps=eval_steps,
    load_best_model_at_end=True,
    save_total_limit=1,
    metric_for_best_model="accuracy",
    greater_is_better=True,
)
if config.fine_tune.do_fine_tune and (
    config.prompt.prompt_type == "traversal"
    or (config.prompt.prompt_type == "path" and config.prompt.use_sub_special_token)
):
    bert_trainer.add_special_tokens(["<SUB>"])

bert_trainer.train(train_args=training_args, do_fine_tune=config.fine_tune.do_fine_tune)
if config.fine_tune.do_fine_tune:
    bert_trainer.trainer.save_model(
        output_dir=os.path.join(config.fine_tune.output_dir, "fine-tuned-checkpoint")
    )
    print("fine-tuning done, fine-tuned model saved")
else:
    print("pretrained or fine-tuned model loaded.")
end_time = datetime.datetime.now()
print("Fine-tuning costs %.1f minutes" % ((end_time - start_time).seconds / 60))
```

--------------------------------

### Render Tree as Image (render_image)

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/verbalisation

Generates a PNG image of the range node tree. Requires Graphviz to be installed.

```bash
sudo apt install graphviz
```

```python
def render_image(self):
    """Calling this function will generate a temporary `range_node.png` file
    which will be displayed.

    To make this visualisation work, you need to install `graphviz` by, e.g.,

    ```bash
    sudo apt install graphviz
    ```
    """
    RenderTreeGraph(self).to_picture("range_node.png")
    return Image("range_node.png")
```

--------------------------------

### Start BERT Model Training

Source: https://krr-oxford.github.io/DeepOnto/deeponto/align/bertmap

Initiates the training process for the BERT model. Raises an error if called in evaluation mode.

```python
def train(self, resume_from_checkpoint: Optional[Union[bool, str]] = None):
    """Start training the BERT model."""
    if self.eval_mode:
        raise RuntimeError("Training cannot be started in `eval` mode.")
    self.trainer.train(resume_from_checkpoint=resume_from_checkpoint)
```

--------------------------------

### Initialize OntologyNormaliser

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/normalisation

Initializes the OntologyNormaliser class. No specific setup is required for this constructor.

```python
def __init__(self):
    return
```

--------------------------------

### Visualize OWL Axiom Parse Tree

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/verbalisation

Visualizes the parsed OWL axiom tree as an image using graphviz. Requires graphviz to be installed.

```python
axiom_parser.parse(str(owl_axiom)).render_image()
```

--------------------------------

### Get Maximum JVM Memory

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/ontology

Retrieves the maximum heap size allocated to the Java Virtual Machine. Requires the JVM to be started.

```python
@staticmethod
def get_max_jvm_memory():
    """Get the maximum heap size assigned to the JVM."""
    if jpype.isJVMStarted():
        return int(Runtime.getRuntime().maxMemory())
    else:
        raise RuntimeError("Cannot retrieve JVM memory as it is not started.")
```

--------------------------------

### Initialize OntologyProjector

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/projection

Initializes an ontology projector with options to control taxonomy direction, inclusion of only taxonomy, and inclusion of literals. Use this to set up the projection parameters.

```python
def __init__(
    self, bidirectional_taxonomy: bool = False, only_taxonomy: bool = False, include_literals: bool = False
):
    """Initialise an ontology projector.

    Args:
        bidirectional_taxonomy (bool, optional): _description_. If `True` then per each `SubClass` edge one `SuperClass` edge will
            be generated. Defaults to `False`.
        only_taxonomy (bool, optional): If `True`, then projection will only include `subClass` edges. Defaults to `False`.
        include_literals (bool, optional): _description_. If `True` the projection will also include triples involving data property
            assertions and annotations. Defaults to `False`.
    """
    self.bidirectional_taxonomy = bidirectional_taxonomy
    self.include_literals = include_literals
    self.only_taxonomy = only_taxonomy
    self.projector = Projector(self.bidirectional_taxonomy, self.only_taxonomy, self.include_literals)
```

--------------------------------

### Intra-Ontology Subsumption Setup with BERTSubs

Source: https://krr-oxford.github.io/DeepOnto/bertsubs

Configure and initialize BERTSubs for intra-ontology subsumption. Requires an ontology file and optional training/validation/test files. Specify the test type and subsumption type.

```python
from yacs.config import CfgNode
from deeponto.complete.bertsubs import BERTSubsIntraPipeline, DEFAULT_CONFIG_FILE_INTRA
from deeponto.utils import load_file
from deeponto.onto import Ontology

config = CfgNode(load_file(DEFAULT_CONFIG_FILE_INTRA)) # Load default configuration file
config.onto_file = './foodon.owl'
config.train_subsumption_file = './train_subsumptions.csv' # optional
config.valid_subsumption_file = './valid_subsumptions.csv' # optional
config.test_subsumption_file = './test_subsumptions.csv' #optional
config.test_type = 'evaluation' #'evaluation': calculate metrics with ground truths given in the test_subsumption_file; 'prediction': predict scores for candidate subsumptions given in test_submission_file
config.subsumption_type = 'named_class'  # 'named_class' or 'restriction' 
config.prompt.prompt_type = 'isolated'  # 'isolated', 'traversal', 'path' (three templates)

onto = Ontology(owl_path=config.onto_file)
intra_pipeline = BERTSubsIntraPipeline(onto=onto, config=config)
```

--------------------------------

### Initialize BERTMap Pipeline

Source: https://krr-oxford.github.io/DeepOnto/bertmap

Load configuration and ontologies, then initialize the BERTMap pipeline for global matching.

```python
from deeponto.onto import Ontology
from deeponto.align.bertmap import BERTMapPipeline

config_file = "path_to_config.yaml"
src_onto_file = "path_to_the_source_ontology.owl"  
tgt_onto_file = "path_to_the_target_ontology.owl" 

config = BERTMapPipeline.load_bertmap_config(config_file)
src_onto = Ontology(src_onto_file)
tgt_onto = Ontology(tgt_onto_file)

BERTMapPipeline(src_onto, tgt_onto, config)

```

--------------------------------

### Sort RangeNode List by Start Position (sort_by_start)

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/verbalisation

A static method to sort a list of RangeNode objects based on their 'start' attribute.

```python
@staticmethod
def sort_by_start(nodes: list[RangeNode]):
    """A sorting function that sorts the nodes by their starting positions."""
    temp = {sib: sib.start for sib in nodes}
    return list(dict(sorted(temp.items(), key=lambda item: item[1])).keys())
```

--------------------------------

### Initialize OntologyVerbaliser

Source: https://krr-oxford.github.io/DeepOnto/verbaliser

Load an ontology and initialize the OntologyVerbaliser. Ensure the ontology file exists.

```python
from deeponto.onto import Ontology, OntologyVerbaliser

# load an ontology and init the verbaliser
onto = Ontology("some_ontology_file.owl")
verbaliser = OntologyVerbaliser(onto)
```

--------------------------------

### Ranking Evaluation Output Example

Source: https://krr-oxford.github.io/DeepOnto/bio-ml

Example output from the `ranking_eval` function, showing calculated metrics like MRR and Hits@K for different K values.

```json
{
'MRR': 0.9586373098280843,
'Hits@1': 0.9371951219512196,
'Hits@5': 0.9820121951219513,
'Hits@10': 0.9878048780487805
}

```

--------------------------------

### Inter-Ontology Subsumption Setup with BERTSubs

Source: https://krr-oxford.github.io/DeepOnto/bertsubs

Configure and initialize BERTSubs for inter-ontology subsumption. Requires source and target ontology files, along with optional training/validation/test files. Define test and subsumption types.

```python
from yacs.config import CfgNode
from deeponto.complete.bertsubs import BERTSubsInterPipeline, DEFAULT_CONFIG_FILE_INTER
from deeponto.utils import load_file
from deeponto.onto import Ontology

config = CfgNode(load_file(DEFAULT_CONFIG_FILE_INTER)) # Load default configuration file
config.src_onto_file = './helis2foodon/helis_v1.00.owl'
config.tgt_onto_file = './helis2foodon/foodon-merged.0.4.8.subs.owl'
config.train_subsumption_file = './helis2foodon/train_subsumptions.csv' # optional
config.valid_subsumption_file = './helis2foodon/valid_subsumptions.csv' # optional
config.test_subsumption_file = './helis2foodon/test_subsumptions.csv' # optional
config.test_type = 'evaluation' # 'evaluation', or 'prediction'
config.subsumption_type = 'named_class'  # 'named_class', or 'restriction'
config.prompt.prompt_type = 'path'   # 'isolated', 'traversal', 'path' (three templates)

src_onto = Ontology(owl_path=config.src_onto_file)
tgt_onto = Ontology(owl_path=config.tgt_onto_file)
inter_pipeline = BERTSubsInterPipeline(src_onto=src_onto, tgt_onto=tgt_onto, config=config)
```

--------------------------------

### RangeNode Initialization

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/verbalisation

Initializes a RangeNode with start and end positions, ensuring start is less than end. It also sets a name and attaches any additional keyword arguments as attributes.

```python
def __init__(self, start, end, name=None, **kwargs):
    if start >= end:
        raise RuntimeError("invalid start and end positions ...")
    self.start = start
    self.end = end
    self.name = "Root" if not name else name
    self.name = f"{self.name}[{self.start}:{self.end}]"  # add start and ent to the name
    for k, v in kwargs.items():
        setattr(self, k, v)
    # Assuming NodeMixin is a base class or provides __init__ functionality
    # super().__init__()
```

--------------------------------

### BERTMapPipeline Initialization and Refinement

Source: https://krr-oxford.github.io/DeepOnto/deeponto/align/bertmap

Initializes the BERTMap pipeline with source and target ontologies and configuration. It then performs mapping extension and repair if the demo mode is enabled. The status is updated throughout the process.

```python
BERTMapPipeline(src_onto, tgt_onto, config)

                enlighten_manager=self.enlighten_manager,
                enlighten_status=self.enlighten_status
            )
            self.mapping_refiner.mapping_extension()  # mapping extension
            self.mapping_refiner.mapping_repair()  # mapping repair
        self.enlighten_status.update(demo="Finished")
    else:
        self.enlighten_status.update(demo="Skipped")

    self.enlighten_status.close()
```

--------------------------------

### Get Inferred Sub Entities

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/reasoning

Retrieves IRIs of named sub-entities for a given OWLObject using the reasoner. Set `direct=True` to get only direct children, or `False` for all descendants. Ignores the bottom entity like owl:Nothing.

```python
def get_inferred_sub_entities(self, entity: OWLObject, direct: bool = False):
    """Return the IRIs of named sub-entities of a given `OWLObject` according to the reasoner.

    A mixture of `getSubClasses`, `getSubObjectProperties`, `getSubDataProperties`
    functions imported from the OWLAPI reasoner. The type of input entity will be
    automatically determined. The bottom entity such as `owl:Nothing` is ignored.

    Args:
        entity (OWLObject): An `OWLObject` entity of interest.
        direct (bool, optional): Return parents (`direct=True`) or
            ancestors (`direct=False`). Defaults to `False`.

    Returns:
        (list[str]): A list of IRIs of the sub-entities of the given `OWLObject` entity.
    """
    entity_type = self.get_entity_type(entity)
    get_sub = f"getSub{entity_type}"
    BOTTOM = TOP_BOTTOMS[entity_type].BOTTOM
    sub_entities = getattr(self.owl_reasoner, get_sub)(entity, direct).getFlattened()
    sub_entity_iris = [str(s.getIRI()) for s in sub_entities]
    # the root node is owl#Thing
    if BOTTOM in sub_entity_iris:
        sub_entity_iris.remove(BOTTOM)
    return sub_entity_iris
```

--------------------------------

### Initialize BERTSubsInterPipeline

Source: https://krr-oxford.github.io/DeepOnto/deeponto/align/bertsubs

Initializes the BERTSubsInterPipeline with source and target ontologies, configuration, and sets up samplers. It also reads subsumption files for testing and validation, and extracts subsumptions from ontologies if configured.

```python
def __init__(self, src_onto: Ontology, tgt_onto: Ontology, config: CfgNode):
    self.src_onto = src_onto
    self.tgt_onto = tgt_onto
    self.config = config
    self.config.label_property = self.config.src_label_property
    self.src_sampler = SubsumptionSampler(onto=self.src_onto, config=self.config)
    self.config.label_property = self.config.tgt_label_property
    self.tgt_sampler = SubsumptionSampler(onto=self.tgt_onto, config=self.config)
    start_time = datetime.datetime.now()

    read_subsumptions = lambda file_name: [line.strip().split(',') for line in open(file_name).readlines()]
    test_subsumptions = None if config.test_subsumption_file is None or config.test_subsumption_file == 'None' \
        else read_subsumptions(config.test_subsumption_file)
    valid_subsumptions = None if config.valid_subsumption_file is None or config.valid_subsumption_file == 'None' \
        else read_subsumptions(config.valid_subsumption_file)

    if config.use_ontology_subsumptions_training:
        src_subsumptions = BERTSubsIntraPipeline.extract_subsumptions_from_ontology(onto=self.src_onto,
                                                                                    subsumption_type=config.subsumption_type)
        tgt_subsumptions = BERTSubsIntraPipeline.extract_subsumptions_from_ontology(onto=self.tgt_onto,
                                                                                    subsumption_type=config.subsumption_type)
        src_subsumptions0, tgt_subsumptions0 = [], []
        if config.subsumption_type == 'named_class':
            for subs in src_subsumptions:
                c1, c2 = subs.getSubClass(), subs.getSuperClass()
                src_subsumptions0.append([str(c1.getIRI()), str(c2.getIRI())])
            for subs in tgt_subsumptions:
                c1, c2 = subs.getSubClass(), subs.getSuperClass()
                tgt_subsumptions0.append([str(c1.getIRI()), str(c2.getIRI())])
        elif config.subsumption_type == 'restriction':
            for subs in src_subsumptions:
                c1, c2 = subs.getSubClass(), subs.getSuperClass()
                src_subsumptions0.append([str(c1.getIRI()), str(c2)])
            for subs in tgt_subsumptions:
                c1, c2 = subs.getSubClass(), subs.getSuperClass()
                tgt_subsumptions0.append([str(c1.getIRI()), str(c2)])
            restrictions = BERTSubsIntraPipeline.extract_restrictions_from_ontology(onto=self.tgt_onto)
            print('restrictions in the target ontology: %d' % len(restrictions))
        else:
            warnings.warn('Unknown subsumption type %s' % config.subsumption_type)
            sys.exit(0)
        print('Positive train subsumptions from the source/target ontology: %d/%d' % (
            len(src_subsumptions0), len(tgt_subsumptions0)))

        src_tr = self.src_sampler.generate_samples(subsumptions=src_subsumptions0)
        tgt_tr = self.tgt_sampler.generate_samples(subsumptions=tgt_subsumptions0)
    else:
        src_tr, tgt_tr = [], []

    if config.train_subsumption_file is None or config.train_subsumption_file == 'None':
        tr = src_tr + tgt_tr
    else:
        train_subsumptions = read_subsumptions(config.train_subsumption_file)
        tr = self.inter_ontology_sampling(subsumptions=train_subsumptions, pos_dup=config.fine_tune.train_pos_dup,
                                          neg_dup=config.fine_tune.train_neg_dup)
        tr = tr + src_tr + tgt_tr

    if len(tr) == 0:
        warnings.warn('No training samples extracted')
        if config.fine_tune.do_fine_tune:
            sys.exit(0)

    end_time = datetime.datetime.now()
    print('data pre-processing costs %.1f minutes' % ((end_time - start_time).seconds / 60))
```

--------------------------------

### Get Inferred Super Entities

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/reasoning

Retrieves IRIs of named super-entities for a given OWLObject using the reasoner. Set `direct=True` to get only direct parents, or `False` for all ancestors. Ignores the top entity like owl:Thing.

```python
def get_inferred_super_entities(self, entity: OWLObject, direct: bool = False):
    r"""Return the IRIs of named super-entities of a given `OWLObject` according to the reasoner.

    A mixture of `getSuperClasses`, `getSuperObjectProperties`, `getSuperDataProperties`
    functions imported from the OWLAPI reasoner. The type of input entity will be
    automatically determined. The top entity such as `owl:Thing` is ignored.


    Args:
        entity (OWLObject): An `OWLObject` entity of interest.
        direct (bool, optional): Return parents (`direct=True`) or
            ancestors (`direct=False`). Defaults to `False`.

    Returns:
        (list[str]): A list of IRIs of the super-entities of the given `OWLObject` entity.
    """
    entity_type = self.get_entity_type(entity)
    get_super = f"getSuper{entity_type}"
    TOP = TOP_BOTTOMS[entity_type].TOP  # get the corresponding TOP entity
    super_entities = getattr(self.owl_reasoner, get_super)(entity, direct).getFlattened()
    super_entity_iris = [str(s.getIRI()) for s in super_entities]
    # the root node is owl#Thing
    if TOP in super_entity_iris:
        super_entity_iris.remove(TOP)
    return super_entity_iris
```

--------------------------------

### BERTMapPipeline Initialization

Source: https://krr-oxford.github.io/DeepOnto/deeponto/align/bertmap

Initializes the BERTMapPipeline with source and target ontologies and a configuration object. It sets up paths, loads corpora and fine-tune data, and initializes the BERT synonym classifier if the pipeline name is 'bertmap'.

```python
self.known_mappings = self.config.known_mappings
    if self.known_mappings:
        self.known_mappings = ReferenceMapping.read_table_mappings(self.known_mappings)

    # auxiliary ontologies if any
    self.auxiliary_ontos = self.config.auxiliary_ontos
    if self.auxiliary_ontos:
        self.auxiliary_ontos = [Ontology(ao) for ao in self.auxiliary_ontos]

    self.data_path = os.path.join(self.output_path, "data")
    # load or construct the corpora
    self.corpora_path = os.path.join(self.data_path, "text-semantics.corpora.json")
    self.corpora = self.load_text_semantics_corpora()

    # load or construct fine-tune data
    self.finetune_data_path = os.path.join(self.data_path, "fine-tune.data.json")
    self.finetune_data = self.load_finetune_data()

    # load the bert model and train
    self.bert_config = self.config.bert
    self.bert_pretrained_path = self.bert_config.pretrained_path
    self.bert_finetuned_path = os.path.join(self.output_path, "bert")
    self.bert_resume_training = self.bert_config.resume_training
    self.bert_synonym_classifier = None
    self.best_checkpoint = None
    if self.name == "bertmap":
        self.bert_synonym_classifier = self.load_bert_synonym_classifier()
        # train if the loaded classifier is not in eval mode
        if self.bert_synonym_classifier.eval_mode == False:
            self.logger.info(
                f"Data statistics:\n \ 
                {print_dict(self.bert_synonym_classifier.data_stat)}"
            )
            self.bert_synonym_classifier.train(self.bert_resume_training)
            # turn on eval mode after training
            self.bert_synonym_classifier.eval()
        # NOTE potential redundancy here: after training, load the best checkpoint
        self.best_checkpoint = self.load_best_checkpoint()
        if not self.best_checkpoint:
            raise RuntimeError(f"No best checkpoint found for the BERT synonym classifier model.")
        self.logger.info(f"Fine-tuning finished, found best checkpoint at {self.best_checkpoint}.")
    else:
        self.logger.info(f"No training needed; skip BERT fine-tuning.")
```

--------------------------------

### get_owl_object

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/ontology

Get an OWLObject given its IRI.

```APIDOC
## get_owl_object

### Description
Get an `OWLObject` given its IRI.

### Parameters
- **iri** (`str`) - The IRI of the OWL object to retrieve.

### Returns
- `OWLObject` - The OWL object corresponding to the IRI.

### Raises
- `KeyError` - If the IRI is not found in the ontology.
```

--------------------------------

### Initialize Ontology Object

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/ontology

Initializes an ontology object by loading an OWL file and setting up a reasoner. Supports different reasoner types.

```python
def __init__(self, owl_path: str, reasoner_type: str = "hermit"):
    """Initialise a new ontology.

    Args:
        owl_path (str): The path to the OWL ontology file.
        reasoner_type (str): The type of reasoner used. Defaults to "hermit". Options are ["hermit", "elk", "struct"].
    """
    self.owl_path = os.path.abspath(owl_path)
    self.owl_manager = OWLManager.createOWLOntologyManager()
    self.owl_onto = self.owl_manager.loadOntologyFromOntologyDocument(IRI.create(File(self.owl_path)))
    self.owl_iri = str(self.owl_onto.getOntologyID().getOntologyIRI().get())
    self.owl_classes = self._get_owl_objects("Classes")
    self.owl_object_properties = self._get_owl_objects("ObjectProperties")
    # for some reason the top object property is included
    if OWL_TOP_OBJECT_PROPERTY in self.owl_object_properties.keys():
        del self.owl_object_properties[OWL_TOP_OBJECT_PROPERTY]
    self.owl_data_properties = self._get_owl_objects("DataProperties")
    self.owl_data_factory = self.owl_manager.getOWLDataFactory()
    self.owl_annotation_properties = self._get_owl_objects("AnnotationProperties")
    self.owl_individuals = self._get_owl_objects("Individuals")

    # reasoning
    self.reasoner_type = reasoner_type
    self.reasoner = OntologyReasoner(self, self.reasoner_type)

    # hidden attributes
    self._multi_children_classes = None
    self._sibling_class_groups = None
    self._axiom_type = AxiomType  # for development use

    # summary
    self.info = {
        type(self).__name__: {
            "loaded_from": os.path.basename(self.owl_path),
            "num_classes": len(self.owl_classes),
            "num_object_properties": len(self.owl_object_properties),
            "num_data_properties": len(self.owl_data_properties),
            "num_annotation_properties": len(self.owl_annotation_properties),
            "num_individuals": len(self.owl_individuals),
            "reasoner_type": self.reasoner_type,
        }
    }
```

--------------------------------

### get_entity_type

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/ontology

A static method to get the type of an OWLObject entity.

```APIDOC
## get_entity_type

### Description
A handy method to get the `type` of an `OWLObject` entity.

### Method
`staticmethod`

### Parameters
- **entity** (`OWLObject`) - The OWL object to get the type from.
- **return_singular** (`bool`) - Optional. If True, returns the singular form of the type. Defaults to False.
```

--------------------------------

### render_tree()

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/verbalisation

Renders the entire tree structure starting from the current RangeNode.

```APIDOC
## render_tree()

### Description
Render the whole tree.

### Method
`render_tree(self)`

### Returns
- An object representing the rendered tree (type not specified in source).
```

--------------------------------

### get_iri

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/ontology

Get the IRI of an OWLObject. Raises an exception if there is no associated IRI.

```APIDOC
## get_iri

### Description
Get the IRI of an `OWLObject`. Raises an exception if there is no associated IRI.

### Parameters
- **owl_object** (`OWLObject`) - The OWL object to get the IRI from.

### Returns
- `str` - The IRI of the OWL object.

### Raises
- `RuntimeError` - If the input OWL object does not have an IRI.
```

--------------------------------

### Initialize BERTSubsIntraPipeline

Source: https://krr-oxford.github.io/DeepOnto/deeponto/complete/bertsubs

Initializes the BERTSubsIntraPipeline with an ontology and configuration. It calculates and prints the number of named classes and average labels per class. It also prepares training and validation subsumption data, either by extracting from the ontology or reading from files.

```python
def __init__(self, onto: Ontology, config: CfgNode):
    self.onto = onto
    self.config = config
    self.sampler = SubsumptionSampler(onto=onto, config=config)
    start_time = datetime.datetime.now()

    n = 0
    for k in self.sampler.named_classes:
        n += len(self.sampler.iri_label[k])
    print(
        "%d named classes, %.1f labels per class"
        % (len(self.sampler.named_classes), n / len(self.sampler.named_classes))
    )

    read_subsumptions = lambda file_name: [line.strip().split(",") for line in open(file_name).readlines()]
    test_subsumptions = (
        None
        if config.test_subsumption_file is None or config.test_subsumption_file == "None"
        else read_subsumptions(config.test_subsumption_file)
    )

    # The train/valid subsumptions are not given. They will be extracted from the given ontology:
    if config.train_subsumption_file is None or config.train_subsumption_file == "None":
        subsumptions0 = self.extract_subsumptions_from_ontology(
            onto=onto, subsumption_type=config.subsumption_type
        )
        random.shuffle(subsumptions0)
        valid_size = int(len(subsumptions0) * config.valid.valid_ratio)
        train_subsumptions0, valid_subsumptions0 = subsumptions0[valid_size:], subsumptions0[0:valid_size]
        train_subsumptions, valid_subsumptions = [], []
        if config.subsumption_type == "named_class":
            for subs in train_subsumptions0:
                c1, c2 = subs.getSubClass(), subs.getSuperClass()
                train_subsumptions.append([str(c1.getIRI()), str(c2.getIRI())])

            size_sum = 0
            for subs in valid_subsumptions0:
                c1, c2 = subs.getSubClass(), subs.getSuperClass()
                neg_candidates = BERTSubsIntraPipeline.get_test_neg_candidates_named_class(
                    subclass=c1, gt=c2, max_neg_size=config.valid.max_neg_size, onto=onto
                )
                size = len(neg_candidates)
                size_sum += size
                if size > 0:
                    item = [str(c1.getIRI()), str(c2.getIRI())] + [str(c.getIRI()) for c in neg_candidates]
                    valid_subsumptions.append(item)
            print("\t average neg candidate size in validation: %.2f" % (size_sum / len(valid_subsumptions)))

        elif config.subsumption_type == "restriction":
            for subs in train_subsumptions0:
                c1, c2 = subs.getSubClass(), subs.getSuperClass()
                train_subsumptions.append([str(c1.getIRI()), str(c2)])

            restrictions = BERTSubsIntraPipeline.extract_restrictions_from_ontology(onto=onto)
            print("restrictions: %d" % len(restrictions))
            size_sum = 0
            for subs in valid_subsumptions0:
                c1, c2 = subs.getSubClass(), subs.getSuperClass()
                c2_neg = BERTSubsIntraPipeline.get_test_neg_candidates_restriction(
                    subcls=c1, max_neg_size=config.valid.max_neg_size, restrictions=restrictions, onto=onto
                )
                size_sum += len(c2_neg)
                item = [str(c1.getIRI()), str(c2)] + [str(r) for r in c2_neg]
                valid_subsumptions.append(item)
            print("valid candidate negative avg. size: %.1f" % (size_sum / len(valid_subsumptions)))
        else:
            warnings.warn("Unknown subsumption type %s" % config.subsumption_type)
            sys.exit(0)

    # The train/valid subsumptions are given:
    else:
        train_subsumptions = read_subsumptions(config.train_subsumption_file)
        valid_subsumptions = read_subsumptions(config.valid_subsumption_file)

    print("Positive train/valid subsumptions: %d/%d" % (len(train_subsumptions), len(valid_subsumptions)))
    tr = self.sampler.generate_samples(subsumptions=train_subsumptions)
    va = self.sampler.generate_samples(subsumptions=valid_subsumptions, duplicate=False)

    end_time = datetime.datetime.now()
```

--------------------------------

### Get All Axioms

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/ontology

Retrieves a list of all axioms asserted within the ontology.

```python
def get_all_axioms(self):
    """Return all axioms (in a list) asserted in the ontology."""
    return list(self.owl_onto.getAxioms())
```

--------------------------------

### Generate Samples from Subsumptions

Source: https://krr-oxford.github.io/DeepOnto/deeponto/complete/bertsubs

Generates training samples by constructing strings based on subsumption relationships. It handles different prompt types and can optionally append a sample label.

```python
                    s1 = ""
                    for i in range(len(context_sub)):
                        subsum = context_sub[len(context_sub) - i - 1]
                        subc = subsum[0]
                        s1 += "%s %s " % (
                            self.iri_label[subc][0]
                            if subc in self.iri_label and len(self.iri_label[subc]) > 0
                            else "",
                            sep_token,
                        )
                    for substr in substrs:
                        s1_set.add(s1 + substr)
                else:
                    for substr in substrs:
                        s1_set.add("%s %s" % (sep_token, substr))

                if no_duplicate:
                    break

            if self.config.subsumption_type == "named_class":
                s2_set = set()
                for _ in range(self.config.prompt.context_dup):
                    context_sup, no_duplicate = self.path_subsumptions(
                        cls=supcls, hop=self.config.prompt.prompt_hop, direction="supclass"
                    )
                    if len(context_sup) > 0:
                        s2 = ""
                        for subsum in context_sup:
                            supc = subsum[1]
                            s2 += " %s %s" % (
                                sep_token,
                                self.iri_label[supc][0]
                                if supc in self.iri_label and len(self.iri_label[supc]) > 0
                                else "",
                            )
                        for supstr in supstrs:
                            s2_set.add(supstr + s2)
                    else:
                        for supstr in supstrs:
                            s2_set.add("%s %s" % (supstr, sep_token))

                    if no_duplicate:
                        break
            else:
                s2_set = set(supstrs)

            for s1 in s1_set:
                for s2 in s2_set:
                    local_samples.append([s1, s2])

        else:
            print(f"unknown context type {self.config.prompt.prompt_type}")
            sys.exit(0)

    if sample_label is not None:
        for i in range(len(local_samples)):
            local_samples[i].append(sample_label)

    return local_samples

```

--------------------------------

### Initialize OntologyReasoner

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/reasoning

Initializes the ontology reasoner with a specified ontology and reasoner type. Loads the reasoner upon initialization.

```python
def __init__(self, onto: Ontology, reasoner_type: str):
    """Initialise an ontology reasoner.

    Args:
        onto (Ontology): The input ontology to conduct reasoning on.
        reasoner_type (str): The type of reasoner used. Options are `["hermit", "elk", "struct"]`.
    """
    self.onto = onto
    self.owl_reasoner_factory = None
    self.owl_reasoner = None
    self.reasoner_type = reasoner_type
    self.load_reasoner(self.reasoner_type)
    self.owl_data_factory = self.onto.owl_data_factory
```

--------------------------------

### train

Source: https://krr-oxford.github.io/DeepOnto/deeponto/align/bertmap

Starts the training process for the BERT model. It can optionally resume from a checkpoint.

```APIDOC
## train

### Description
Starts training the BERT model. Can resume from a checkpoint.

### Method
`train(resume_from_checkpoint: Optional[Union[bool, str]] = None)`

### Parameters
* **resume_from_checkpoint** (Optional[Union[bool, str]]) - Optional parameter to specify a checkpoint to resume training from.
```

--------------------------------

### run_inference(config, args)

Source: https://krr-oxford.github.io/DeepOnto/deeponto/complete/ontolama

Main entry point for running the OpenPrompt script for inference. It handles configuration, dataset loading, and orchestrates the training or testing process based on the learning setting.

```APIDOC
## run_inference(config, args)

### Description
Main entry for running the OpenPrompt script.

### Parameters
- **config**: Configuration object for the experiment.
- **args**: Command-line arguments passed to the script.

### Returns
- **config**: The processed configuration object.
- **CUR_TEMPLATE**: The current template used.
- **CUR_VERBALIZER**: The current verbalizer used.
```

--------------------------------

### get_max_jvm_memory

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/ontology

A static method to get the maximum heap size assigned to the JVM.

```APIDOC
## get_max_jvm_memory

### Description
Get the maximum heap size assigned to the JVM.

### Method
`staticmethod`

### Returns
- `int` - The maximum JVM heap size in bytes.

### Raises
- `RuntimeError` - If the JVM is not started.
```

--------------------------------

### Initialize OntoLAMA Data Processor

Source: https://krr-oxford.github.io/DeepOnto/deeponto/complete/ontolama

Initializes the OntoLAMA DataProcessor, setting up the labels for classification tasks.

```python
def __init__(self):
    super().__init__()
    self.labels = ["negative", "positive"]
```

--------------------------------

### render_image()

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/verbalisation

Generates a PNG image visualization of the RangeNode tree. Requires Graphviz to be installed.

```APIDOC
## render_image()

### Description
Calling this function will generate a temporary `range_node.png` file which will be displayed.

To make this visualisation work, you need to install `graphviz` by, e.g.,

```bash
sudo apt install graphviz
```

### Method
`render_image(self)`

### Returns
- An `Image` object representing the generated `range_node.png` file.
```

--------------------------------

### Initialize OntologyPruner

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/pruning

Initializes the OntologyPruner with the ontology to be pruned. The pruning process is performed in-place.

```python
def __init__(self, onto: Ontology):
    """Initialise an ontology pruner.

    Args:
        onto (Ontology): The input ontology to be pruned. Note that the pruning process is in-place.
    """
    self.onto = onto
    self._pruning_applied = None
```

--------------------------------

### get_axiom_type

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/ontology

A static method to get the axiom type (in string format) for a given axiom.

```APIDOC
## get_axiom_type

### Description
Get the axiom type (in `str`) for the given axiom.
Check full list at: <http://owlcs.github.io/owlapi/apidocs_5/org/semanticweb/owlapi/model/AxiomType.html>.

### Method
`staticmethod`

### Parameters
- **axiom** (`OWLAxiom`) - The axiom to get the type from.

### Returns
- `str` - The type of the axiom.
```

--------------------------------

### sort_by_start(nodes)

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/verbalisation

A static method that sorts a list of RangeNode objects based on their starting positions.

```APIDOC
## sort_by_start(nodes)

### Description
A sorting function that sorts the nodes by their starting positions.

### Method
`@staticmethod
sort_by_start(nodes: list[RangeNode])`

### Parameters
- **nodes** (`list[RangeNode]`): A list of RangeNode objects to be sorted.

### Returns
- `list[RangeNode]`: A new list containing the RangeNode objects sorted by their `start` attribute.
```

--------------------------------

### Initialize OntologyVerbaliser

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/verbalisation

Initializes the OntologyVerbaliser with an ontology and configuration options. It automatically downloads the 'en_core_web_sm' model for auto-correction if not found.

```python
def __init__(
    self,
    onto: Ontology,
    apply_lowercasing: bool = False,
    keep_iri: bool = False,
    apply_auto_correction: bool = False,
    add_quantifier_word: bool = False,
):
    """Initialise an ontology verbaliser.

    Args:
        onto (Ontology): An ontology whose entities and axioms are to be verbalised.
        apply_lowercasing (bool, optional): Whether to apply lowercasing to the entity names. Defaults to `False`.
        keep_iri (bool, optional): Whether to keep the IRIs of entities without verbalising them using `self.vocab`. Defaults to `False`.
        apply_auto_correction (bool, optional): Whether to automatically apply rule-based auto-correction to entity names. Defaults to `False`.
        add_quantifier_word (bool, optional): Whether to add quantifier words ("some"/"only") as in the Manchester syntax. Defaults to `False`.
    """
    self.onto = onto
    self.parser = OntologySyntaxParser()

    # download en_core_web_sm for object property
    try:
```

--------------------------------

### Render Tree Structure (render_tree)

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/verbalisation

Renders the entire tree structure starting from the current node.

```python
def render_tree(self):
    """Render the whole tree."""
    return RenderTree(self)
```

--------------------------------

### Run OntoLAMA inference with OpenPrompt

Source: https://krr-oxford.github.io/DeepOnto/ontolama

Initiate prompt-based probing for ontology subsumption inference using OpenPrompt and DeepOnto. Configuration options for learning settings and templates can be manipulated before running inference.

```python
from openprompt.config import get_config
from deeponto.complete.ontolama import run_inference

config, args = get_config()
# you can then manipulate the configuration before running the inference
config.learning_setting = "few_shot"  # zero_shot, full
config.manual_template.choice = 0  # using the first template in the template file
...

```

--------------------------------

### Initialize BERTMapPipeline

Source: https://krr-oxford.github.io/DeepOnto/deeponto/align/bertmap

Initializes the BERTMap or BERTMapLt model. It loads configurations, sets up the output directory and logger, and builds annotation indices from the source and target ontologies. Ensure class annotations are present in the ontologies.

```python
def __init__(self, src_onto: Ontology, tgt_onto: Ontology, config: CfgNode):
    """Initialise the BERTMap or BERTMapLt model.

    Args:
        src_onto (Ontology): The source ontology for alignment.
        tgt_onto (Ontology): The target ontology for alignment.
        config (CfgNode): The configuration for BERTMap or BERTMapLt.
    """
    # load the configuration and confirm model name is valid
    self.config = config
    self.name = self.config.model
    if not self.name in MODEL_OPTIONS.keys():
        raise RuntimeError(f"`model` {self.name} in the config file is not one of the supported.")

    # create the output directory, e.g., experiments/bertmap
    self.config.output_path = "." if not self.config.output_path else self.config.output_path
    self.config.output_path = os.path.abspath(self.config.output_path)
    self.output_path = os.path.join(self.config.output_path, self.name)
    create_path(self.output_path)

    # create logger and progress manager (hidden attribute) 
    self.logger = create_logger(self.name, self.output_path)
    self.enlighten_manager = enlighten.get_manager()

    # ontology
    self.src_onto = src_onto
    self.tgt_onto = tgt_onto
    self.annotation_property_iris = self.config.annotation_property_iris
    self.logger.info(f"Load the following configurations:\n{print_dict(self.config)}")
    config_path = os.path.join(self.output_path, "config.yaml")
    self.logger.info(f"Save the configuration file at {config_path}.")
    self.save_bertmap_config(self.config, config_path)

    # build the annotation thesaurus
    self.src_annotation_index, _ = self.src_onto.build_annotation_index(self.annotation_property_iris, apply_lowercasing=True)
    self.tgt_annotation_index, _ = self.tgt_onto.build_annotation_index(self.annotation_property_iris, apply_lowercasing=True)
    if (not self.src_annotation_index) or (not self.tgt_annotation_index):
        raise RuntimeError("No class annotations found in input ontologies; unable to produce alignment.")

    # provided mappings if any

```

--------------------------------

### Get Node Attributes

Source: https://krr-oxford.github.io/DeepOnto/deeponto/onto/taxonomy

Retrieves the attributes associated with a specific entity ID from the taxonomy graph.

```python
def get_node_attributes(self, entity_id: str):
    """Get the attributes of the given entity."""
    return self.graph.nodes[entity_id]
```