class_docstr: Relation Classifier to predict the relation between two entities.
  
  Task
  ----
  Relation Classification (RC) is the task of identifying the semantic relation between two entities in a text.
  In contrast to (end-to-end) Relation Extraction (RE), RC requires pre-labelled entities.
  
  Example:
  --------
  For the `founded_by` relation from `ORG` (head) to `PER` (tail) and the sentence
  "Larry Page and Sergey Brin founded Google .", we extract the relations
  - founded_by(head='Google', tail='Larry Page') and
  - founded_by(head='Google', tail='Sergey Brin').
  
  Architecture
  ------------
  The Relation Classifier Model builds upon a text classifier.
  The model generates an encoded sentence for each entity pair
  in the cross product of all entities in the original sentence.
  In the encoded representation, the entities in the current entity pair are masked/marked with control tokens.
  (For an example, see the docstrings of different encoding strategies, e.g. :class:`TypedEntityMarker`.)
  Then, for each encoded sentence, the model takes its document embedding and puts the resulting
  text representation(s) through a linear layer to get the class relation label.
  
  The implemented encoding strategies are taken from this paper by Zhou et al.: https://arxiv.org/abs/2102.01373
  
  .. warning::
      Currently, the model has no multi-label support.
class_docstr_tok: ["Relation","Classifier","to","predict","the","relation","between","two","entities",".","Task","--","--","Relation","Classification","(","RC",")","is","the","task","of","identifying","the","semantic","relation","between","two","entities","in","a","text",".","In","contrast","to","(","end-to-end",")","Relation","Extraction","(","RE",")",",","RC","requires","pre-labelled","entities",".","Example",":","--","--","--","--","For","the","`","founded_by","`","relation","from","`","ORG","`","(","head",")","to","`","PER","`","(","tail",")","and","the","sentence","''","Larry","Page","and","Sergey","Brin","founded","Google",".","``",",","we","extract","the","relations","-","founded_by","(","head='Google","'",",","tail='Larry","Page","'",")","and","-","founded_by","(","head='Google","'",",","tail='Sergey","Brin","'",")",".","Architecture","--","--","--","--","--","--","The","Relation","Classifier","Model","builds","upon","a","text","classifier",".","The","model","generates","an","encoded","sentence","for","each","entity","pair","in","the","cross","product","of","all","entities","in","the","original","sentence",".","In","the","encoded","representation",",","the","entities","in","the","current","entity","pair","are","masked\/marked","with","control","tokens",".","(","For","an","example",",","see","the","docstrings","of","different","encoding","strategies",",","e.g",".",":","class",":","`","TypedEntityMarker","`",".",")","Then",",","for","each","encoded","sentence",",","the","model","takes","its","document","embedding","and","puts","the","resulting","text","representation","(","s",")","through","a","linear","layer","to","get","the","class","relation","label",".","The","implemented","encoding","strategies","are","taken","from","this","paper","by","Zhou","et","al",".",":","https",":","\/\/arxiv.org\/abs\/2102.01373","..","warning",":",":","Currently",",","the","model","has","no","multi-label","support","."]
docstr: Initializes a `RelationClassifier`.
  
  Args:
      embeddings: The document embeddings used to embed each sentence
      label_dictionary: A Dictionary containing all predictable labels from the corpus
      label_type: The label type which is going to be predicted, in case a corpus has multiple annotations
      entity_label_types: A label type or sequence of label types of the required relation entities. You can also specify a label filter in a dictionary with the label type as key and the valid entity labels as values in a set. E.g. to use only 'PER' and 'ORG' labels from a NER-tagger: `{'ner': {'PER', 'ORG'}}`. To use all labels from 'ner', pass 'ner'.
      entity_pair_labels: A set of valid relation entity pair combinations, used as relation candidates. Specify valid entity pairs in a set of tuples of labels (<HEAD>, <TAIL>). E.g. for the `born_in` relation, only relations from 'PER' to 'LOC' make sense. Here, relations from 'PER' to 'PER' are not meaningful, so it is advised to specify the `entity_pair_labels` as `{('PER', 'ORG')}`. This setting may help to reduce the number of relation candidates. Leaving this parameter as `None` (default) disables the relation-candidate-filter, i.e. the model classifies the relation for each entity pair in the cross product of *all* entity pairs (inefficient).
      entity_threshold: Only pre-labelled entities above this threshold are taken into account by the model.
      cross_augmentation: If `True`, use cross augmentation to transform `Sentence`s into `EncodedSentenece`s. When cross augmentation is enabled, the transformation functions, e.g. `transform_corpus`, generate an encoded sentence for each entity pair in the cross product of all entities in the original sentence. When disabling cross augmentation, the transform functions only generate  encoded sentences for each gold relation annotation in the original sentence.
      encoding_strategy: An instance of a class conforming the :class:`EncodingStrategy` protocol
      zero_tag_value: The label to use for out-of-class relations
      allow_unk_tag: If `False`, removes `<unk>` from the passed label dictionary, otherwise do nothing.
      classifierargs: The remaining parameters passed to the underlying :class:`flair.models.DefaultClassifier`
docstr_tok: ["Initializes","a","`","RelationClassifier","`",".","Args",":","embeddings",":","The","document","embeddings","used","to","embed","each","sentence","label_dictionary",":","A","Dictionary","containing","all","predictable","labels","from","the","corpus","label_type",":","The","label","type","which","is","going","to","be","predicted",",","in","case","a","corpus","has","multiple","annotations","entity_label_types",":","A","label","type","or","sequence","of","label","types","of","the","required","relation","entities",".","You","can","also","specify","a","label","filter","in","a","dictionary","with","the","label","type","as","key","and","the","valid","entity","labels","as","values","in","a","set",".","E.g",".","to","use","only","'PER","'","and","'ORG","'","labels","from","a","NER-tagger",":","`","{","'ner","'",":","{","'PER","'",",","'ORG","'","}","}","`",".","To","use","all","labels","from","'ner","'",",","pass","'ner","'",".","entity_pair_labels",":","A","set","of","valid","relation","entity","pair","combinations",",","used","as","relation","candidates",".","Specify","valid","entity","pairs","in","a","set","of","tuples","of","labels","(","<","HEAD",">",",","<","TAIL",">",")",".","E.g",".","for","the","`","born_in","`","relation",",","only","relations","from","'PER","'","to","'LOC","'","make","sense",".","Here",",","relations","from","'PER","'","to","'PER","'","are","not","meaningful",",","so","it","is","advised","to","specify","the","`","entity_pair_labels","`","as","`","{","(","'PER","'",",","'ORG","'",")","}","`",".","This","setting","may","help","to","reduce","the","number","of","relation","candidates",".","Leaving","this","parameter","as","`","None","`","(","default",")","disables","the","relation-candidate-filter",",","i.e",".","the","model","classifies","the","relation","for","each","entity","pair","in","the","cross","product","of","*","all","*","entity","pairs","(","inefficient",")",".","entity_threshold",":","Only","pre-labelled","entities","above","this","threshold","are","taken","into","account","by","the","model",".","cross_augmentation",":","If","`","True","`",",","use","cross","augmentation","to","transform","`","Sentence","`","s","into","`","EncodedSentenece","`","s",".","When","cross","augmentation","is","enabled",",","the","transformation","functions",",","e.g",".","`","transform_corpus","`",",","generate","an","encoded","sentence","for","each","entity","pair","in","the","cross","product","of","all","entities","in","the","original","sentence",".","When","disabling","cross","augmentation",",","the","transform","functions","only","generate","encoded","sentences","for","each","gold","relation","annotation","in","the","original","sentence",".","encoding_strategy",":","An","instance","of","a","class","conforming","the",":","class",":","`","EncodingStrategy","`","protocol","zero_tag_value",":","The","label","to","use","for","out-of-class","relations","allow_unk_tag",":","If","`","False","`",",","removes","`","<","unk",">","`","from","the","passed","label","dictionary",",","otherwise","do","nothing",".","classifierargs",":","The","remaining","parameters","passed","to","the","underlying",":","class",":","`","flair.models.DefaultClassifier","`"]
code: def __init__(
      self,
      embeddings: DocumentEmbeddings,
      label_dictionary: Dictionary,
      label_type: str,
      entity_label_types: Union[
          str, Sequence[str], Dict[str, Optional[Set[str]]]
      ],
      entity_pair_labels: Optional[Set[Tuple[str, str]]] = None,
      entity_threshold: Optional[float] = None,
      cross_augmentation: bool = True,
      encoding_strategy: EncodingStrategy = TypedEntityMarker(),
      zero_tag_value: str = "O",
      allow_unk_tag: bool = True,
      **classifierargs,
  ) -> None:
      """Initializes a `RelationClassifier`.
  
      Args:
          embeddings: The document embeddings used to embed each sentence
          label_dictionary: A Dictionary containing all predictable labels from the corpus
          label_type: The label type which is going to be predicted, in case a corpus has multiple annotations
          entity_label_types: A label type or sequence of label types of the required relation entities. You can also specify a label filter in a dictionary with the label type as key and the valid entity labels as values in a set. E.g. to use only 'PER' and 'ORG' labels from a NER-tagger: `{'ner': {'PER', 'ORG'}}`. To use all labels from 'ner', pass 'ner'.
          entity_pair_labels: A set of valid relation entity pair combinations, used as relation candidates. Specify valid entity pairs in a set of tuples of labels (<HEAD>, <TAIL>). E.g. for the `born_in` relation, only relations from 'PER' to 'LOC' make sense. Here, relations from 'PER' to 'PER' are not meaningful, so it is advised to specify the `entity_pair_labels` as `{('PER', 'ORG')}`. This setting may help to reduce the number of relation candidates. Leaving this parameter as `None` (default) disables the relation-candidate-filter, i.e. the model classifies the relation for each entity pair in the cross product of *all* entity pairs (inefficient).
          entity_threshold: Only pre-labelled entities above this threshold are taken into account by the model.
          cross_augmentation: If `True`, use cross augmentation to transform `Sentence`s into `EncodedSentenece`s. When cross augmentation is enabled, the transformation functions, e.g. `transform_corpus`, generate an encoded sentence for each entity pair in the cross product of all entities in the original sentence. When disabling cross augmentation, the transform functions only generate  encoded sentences for each gold relation annotation in the original sentence.
          encoding_strategy: An instance of a class conforming the :class:`EncodingStrategy` protocol
          zero_tag_value: The label to use for out-of-class relations
          allow_unk_tag: If `False`, removes `<unk>` from the passed label dictionary, otherwise do nothing.
          classifierargs: The remaining parameters passed to the underlying :class:`flair.models.DefaultClassifier`
      """
      # Set label type and prepare label dictionary
      self._label_type = label_type
      self._zero_tag_value = zero_tag_value
      self._allow_unk_tag = allow_unk_tag
  
      modified_label_dictionary: Dictionary = Dictionary(
          add_unk=self._allow_unk_tag
      )
      modified_label_dictionary.add_item(self._zero_tag_value)
      for label in label_dictionary.get_items():
          if label != "<unk>":
              modified_label_dictionary.add_item(label)
  
      # Initialize super default classifier
      super().__init__(
          embeddings=embeddings,
          label_dictionary=modified_label_dictionary,
          final_embedding_size=embeddings.embedding_length,
          **classifierargs,
      )
  
      if isinstance(entity_label_types, str):
          self.entity_label_types: Dict[str, Optional[Set[str]]] = {
              entity_label_types: None
          }
      elif isinstance(entity_label_types, Sequence):
          self.entity_label_types = {
              entity_label_type: None
              for entity_label_type in entity_label_types
          }
      else:
          self.entity_label_types = entity_label_types
  
      self.entity_pair_labels = entity_pair_labels
  
      self.entity_threshold = entity_threshold
      self.cross_augmentation = cross_augmentation
      self.encoding_strategy = encoding_strategy
  
      # Add the special tokens from the encoding strategy
      if (
          self.encoding_strategy.add_special_tokens
          and self.encoding_strategy.special_tokens
          and isinstance(self.embeddings, TransformerDocumentEmbeddings)
      ):
          special_tokens: List[str] = list(
              self.encoding_strategy.special_tokens
          )
          tokenizer = self.embeddings.tokenizer
          tokenizer.add_special_tokens(
              {"additional_special_tokens": special_tokens}
          )
          self.embeddings.model.resize_token_embeddings(len(tokenizer))
  
          logger.info(
              f"{self.__class__.__name__}: "
              f"Added {', '.join(special_tokens)} as additional special tokens to {self.embeddings.name}"
          )
  
      # Auto-spawn on GPU, if available
      self.to(flair.device)
  
imports: import itertools
  import logging
  import typing
  from abc import ABC, abstractmethod
  from pathlib import Path
  from typing import Any, Dict, Iterator, List, NamedTuple, Optional, Sequence, Set, Tuple, Union, cast
  import torch
  from torch.utils.data.dataset import Dataset
  import flair
  from flair.data import Corpus, Dictionary, Label, Relation, Sentence, Span, Token, _iter_dataset
  from flair.datasets import DataLoader, FlairDatapointDataset
  from flair.embeddings import DocumentEmbeddings, TransformerDocumentEmbeddings
  from flair.tokenization import SpaceTokenizer
label_desc: Use image node_id 1 to create a new RelationClassifier object from inherited base classes: flair.nn.DefaultClassifier with example: obj = RelationClassifier(embeddings, label_dictionary, label_type, entity_label_types, entity_pair_labels, entity_threshold, cross_augmentation, encoding_strategy, zero_tag_value, allow_unk_tag)