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: Yields all valid entity pair permutations (relation candidates).
  
  If the passed sentence contains relation annotations,
  the relation gold label will be yielded along with the participating entities.
  The permutations are constructed by a filtered cross-product
  under the specification of :py:meth:~`flair.models.RelationClassifier.entity_label_types`
  and :py:meth:~`flair.models.RelationClassifier.entity_pair_labels`.
  
  Args:
      sentence: A Sentence with entity annotations
  
  Yields:
      Tuples of (HEAD, TAIL, gold_label): The head and tail `_Entity`s` have span references to the passed sentence.
docstr_tok: ["Yields","all","valid","entity","pair","permutations","(","relation","candidates",")",".","If","the","passed","sentence","contains","relation","annotations",",","the","relation","gold","label","will","be","yielded","along","with","the","participating","entities",".","The","permutations","are","constructed","by","a","filtered","cross-product","under","the","specification","of",":","py",":","meth",":","~","`","flair.models.RelationClassifier.entity_label_types","`","and",":","py",":","meth",":","~","`","flair.models.RelationClassifier.entity_pair_labels","`",".","Args",":","sentence",":","A","Sentence","with","entity","annotations","Yields",":","Tuples","of","(","HEAD",",","TAIL",",","gold_label",")",":","The","head","and","tail","`","_Entity","`","s","`","have","span","references","to","the","passed","sentence","."]
code: def _entity_pair_permutations(
      self,
      sentence: Sentence,
  ) -> Iterator[Tuple[_Entity, _Entity, Optional[str]]]:
      """Yields all valid entity pair permutations (relation candidates).
  
      If the passed sentence contains relation annotations,
      the relation gold label will be yielded along with the participating entities.
      The permutations are constructed by a filtered cross-product
      under the specification of :py:meth:~`flair.models.RelationClassifier.entity_label_types`
      and :py:meth:~`flair.models.RelationClassifier.entity_pair_labels`.
  
      Args:
          sentence: A Sentence with entity annotations
  
      Yields:
          Tuples of (HEAD, TAIL, gold_label): The head and tail `_Entity`s` have span references to the passed sentence.
      """
      valid_entities: List[_Entity] = list(
          self._valid_entities(sentence)
      )
  
      # Use a dictionary to find gold relation annotations for a given entity pair
      relation_to_gold_label: Dict[str, str] = {
          relation.unlabeled_identifier: relation.get_label(
              self.label_type, zero_tag_value=self.zero_tag_value
          ).value
          for relation in sentence.get_relations(self.label_type)
      }
  
      # Yield head and tail entity pairs from the cross product of all entities
      for head, tail in itertools.product(valid_entities, repeat=2):
          # Remove identity relation entity pairs
          if head.span is tail.span:
              continue
  
          # Remove entity pairs with labels that do not match any
          # of the specified relations in `self.entity_pair_labels`
          if (
              self.entity_pair_labels is not None
              and (head.label.value, tail.label.value)
              not in self.entity_pair_labels
          ):
              continue
  
          # Obtain gold label, if existing
          original_relation: Relation = Relation(
              first=head.span, second=tail.span
          )
          gold_label: Optional[str] = relation_to_gold_label.get(
              original_relation.unlabeled_identifier
          )
  
          yield head, tail, gold_label
  
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 3 for calling the RelationClassifier obj's underlying member method code with example usage: obj._entity_pair_permutations(sentence) without return types