class_docstr: Knowledge graph embedding application.
  
  Given a knowledge graph, it embeds each entity and relation into a continuous vector representation respectively.
  The learned embeddings can be used for analysis of knowledge graphs.
  e.g. **entity prediction**, **link prediction**.
  The likelihood of edges can be predicted by computing the score function over embeddings of triplets.
  
  Supported Models:
      - TransE (`Translating Embeddings for Modeling Multi-relational Data`_)
      - DistMult (`Embedding Entities and Relations for Learning and Inference in Knowledge Bases`_)
      - ComplEx (`Complex Embeddings for Simple Link Prediction`_)
      - SimplE (`SimplE Embedding for Link Prediction in Knowledge Graphs`_)
      - RotatE (`RotatE: Knowledge Graph Embedding by Relational Rotation in Complex Space`_)
      - QuatE (`Quaternion Knowledge Graph Embeddings`)
  
  .. _Translating Embeddings for Modeling Multi-relational Data:
      http://papers.nips.cc/paper/5071-translating-embeddings-for-modeling-multi-relational-data.pdf
  .. _Embedding Entities and Relations for Learning and Inference in Knowledge Bases:
      https://arxiv.org/pdf/1412.6575.pdf
  .. _Complex Embeddings for Simple Link Prediction:
      http://proceedings.mlr.press/v48/trouillon16.pdf
  .. _SimplE Embedding for Link Prediction in Knowledge Graphs:
      https://papers.nips.cc/paper/7682-simple-embedding-for-link-prediction-in-knowledge-graphs.pdf
  .. _RotatE\: Knowledge Graph Embedding by Relational Rotation in Complex Space:
      https://arxiv.org/pdf/1902.10197.pdf
  .. _Quaternion Knowledge Graph Embeddings:
      https://papers.nips.cc/paper/8541-quaternion-knowledge-graph-embeddings.pdf
  
  Parameters:
      dim (int): dimension of embeddings
      gpus (list of int, optional): GPU ids, default is all GPUs
      cpu_per_gpu (int, optional): number of CPU threads per GPU, default is all CPUs
      float_type (dtype, optional): type of parameters
      index_type (dtype, optional): type of graph indexes
  
  Note:
      The implementation of TransE, DistMult, ComplEx, SimplE and QuatE are slightly different from their original
      papers.
      The loss function and the regularization term generally follow `this repo`_.
      Self-adversarial negative sampling is also adopted in these models like RotatE.
  
  .. _this repo: https://github.com/DeepGraphLearning/KnowledgeGraphEmbedding
  
  See also:
      :class:`KnowledgeGraph <graphvite.graph.KnowledgeGraph>`,
      :class:`KnowledgeGraphSolver <graphvite.solver.KnowledgeGraphSolver>`
class_docstr_tok: ["Knowledge","graph","embedding","application",".","Given","a","knowledge","graph",",","it","embeds","each","entity","and","relation","into","a","continuous","vector","representation","respectively",".","The","learned","embeddings","can","be","used","for","analysis","of","knowledge","graphs",".","e.g",".","*","*","entity","prediction","*","*",",","*","*","link","prediction","*","*",".","The","likelihood","of","edges","can","be","predicted","by","computing","the","score","function","over","embeddings","of","triplets",".","Supported","Models",":","-","TransE","(","`","Translating","Embeddings","for","Modeling","Multi-relational","Data","`","_",")","-","DistMult","(","`","Embedding","Entities","and","Relations","for","Learning","and","Inference","in","Knowledge","Bases","`","_",")","-","ComplEx","(","`","Complex","Embeddings","for","Simple","Link","Prediction","`","_",")","-","SimplE","(","`","SimplE","Embedding","for","Link","Prediction","in","Knowledge","Graphs","`","_",")","-","RotatE","(","`","RotatE",":","Knowledge","Graph","Embedding","by","Relational","Rotation","in","Complex","Space","`","_",")","-","QuatE","(","`","Quaternion","Knowledge","Graph","Embeddings","`",")","..","_Translating","Embeddings","for","Modeling","Multi-relational","Data",":","http",":","\/\/papers.nips.cc\/paper\/5071-translating-embeddings-for-modeling-multi-relational-data.pdf","..","_Embedding","Entities","and","Relations","for","Learning","and","Inference","in","Knowledge","Bases",":","https",":","\/\/arxiv.org\/pdf\/1412.6575.pdf","..","_Complex","Embeddings","for","Simple","Link","Prediction",":","http",":","\/\/proceedings.mlr.press\/v48\/trouillon16.pdf","..","_SimplE","Embedding","for","Link","Prediction","in","Knowledge","Graphs",":","https",":","\/\/papers.nips.cc\/paper\/7682-simple-embedding-for-link-prediction-in-knowledge-graphs.pdf","..","_RotatE\\",":","Knowledge","Graph","Embedding","by","Relational","Rotation","in","Complex","Space",":","https",":","\/\/arxiv.org\/pdf\/1902.10197.pdf","..","_Quaternion","Knowledge","Graph","Embeddings",":","https",":","\/\/papers.nips.cc\/paper\/8541-quaternion-knowledge-graph-embeddings.pdf","Parameters",":","dim","(","int",")",":","dimension","of","embeddings","gpus","(","list","of","int",",","optional",")",":","GPU","ids",",","default","is","all","GPUs","cpu_per_gpu","(","int",",","optional",")",":","number","of","CPU","threads","per","GPU",",","default","is","all","CPUs","float_type","(","dtype",",","optional",")",":","type","of","parameters","index_type","(","dtype",",","optional",")",":","type","of","graph","indexes","Note",":","The","implementation","of","TransE",",","DistMult",",","ComplEx",",","SimplE","and","QuatE","are","slightly","different","from","their","original","papers",".","The","loss","function","and","the","regularization","term","generally","follow","`","this","repo","`","_",".","Self-adversarial","negative","sampling","is","also","adopted","in","these","models","like","RotatE",".","..","_this","repo",":","https",":","\/\/github.com\/DeepGraphLearning\/KnowledgeGraphEmbedding","See","also",":",":","class",":","`","KnowledgeGraph","<","graphvite.graph.KnowledgeGraph",">","`",",",":","class",":","`","KnowledgeGraphSolver","<","graphvite.solver.KnowledgeGraphSolver",">","`"]
docstr: Evaluate knowledge graph embeddings on link prediction task.
  
  Parameters:
      H (list of str, optional): names of head entities
      R (list of str, optional): names of relations
      T (list of str, optional): names of tail entities
      file_name (str, optional): file of triplets (e.g. validation set)
      filter_H (list of str, optional): names of head entities to filter out
      filter_R (list of str, optional): names of relations to filter out
      filter_T (list of str, optional): names of tail entities to filter out
      filter_files (str, optional): files of triplets to filter out (e.g. training / validation / test set)
      target (str, optional): 'head', 'tail' or 'both'
      fast_mode (int, optional): if specified, only that number of samples will be evaluated
      backend (str, optional): 'graphvite' or 'torch'
  
  Returns:
      dict: MR, MRR, HITS\@1, HITS\@3 & HITS\@10 of link prediction
docstr_tok: ["Evaluate","knowledge","graph","embeddings","on","link","prediction","task",".","Parameters",":","H","(","list","of","str",",","optional",")",":","names","of","head","entities","R","(","list","of","str",",","optional",")",":","names","of","relations","T","(","list","of","str",",","optional",")",":","names","of","tail","entities","file_name","(","str",",","optional",")",":","file","of","triplets","(","e.g",".","validation","set",")","filter_H","(","list","of","str",",","optional",")",":","names","of","head","entities","to","filter","out","filter_R","(","list","of","str",",","optional",")",":","names","of","relations","to","filter","out","filter_T","(","list","of","str",",","optional",")",":","names","of","tail","entities","to","filter","out","filter_files","(","str",",","optional",")",":","files","of","triplets","to","filter","out","(","e.g",".","training","\/","validation","\/","test","set",")","target","(","str",",","optional",")",":","'head","'",",","'tail","'","or","'both'","fast_mode","(","int",",","optional",")",":","if","specified",",","only","that","number","of","samples","will","be","evaluated","backend","(","str",",","optional",")",":","'graphvite","'","or","'torch'","Returns",":","dict",":","MR",",","MRR",",","HITS\\","@","1",",","HITS\\","@","3","&","HITS\\","@","10","of","link","prediction"]
code: def link_prediction(
      self,
      H=None,
      R=None,
      T=None,
      filter_H=None,
      filter_R=None,
      filter_T=None,
      file_name=None,
      filter_files=None,
      target="both",
      fast_mode=None,
      backend=cfg.backend,
  ):
      """
      Evaluate knowledge graph embeddings on link prediction task.
  
      Parameters:
          H (list of str, optional): names of head entities
          R (list of str, optional): names of relations
          T (list of str, optional): names of tail entities
          file_name (str, optional): file of triplets (e.g. validation set)
          filter_H (list of str, optional): names of head entities to filter out
          filter_R (list of str, optional): names of relations to filter out
          filter_T (list of str, optional): names of tail entities to filter out
          filter_files (str, optional): files of triplets to filter out (e.g. training / validation / test set)
          target (str, optional): 'head', 'tail' or 'both'
          fast_mode (int, optional): if specified, only that number of samples will be evaluated
          backend (str, optional): 'graphvite' or 'torch'
  
      Returns:
          dict: MR, MRR, HITS\@1, HITS\@3 & HITS\@10 of link prediction
      """
  
      def torch_predict():
          import torch
  
          entity_embeddings = SharedNDArray(
              self.solver.entity_embeddings
          )
          relation_embeddings = SharedNDArray(
              self.solver.relation_embeddings
          )
  
          num_gpu = (
              len(self.gpus) if self.gpus else torch.cuda.device_count()
          )
          work_load = (fast_mode + num_gpu - 1) // num_gpu
          settings = []
  
          for i in range(num_gpu):
              work_H = H[work_load * i : work_load * (i + 1)]
              work_R = R[work_load * i : work_load * (i + 1)]
              work_T = T[work_load * i : work_load * (i + 1)]
              settings.append(
                  (
                      entity_embeddings,
                      relation_embeddings,
                      work_H,
                      work_R,
                      work_T,
                      exclude_H,
                      exclude_T,
                      target,
                      None,
                      self.solver.model,
                      self.solver.margin,
                  )
              )
  
          results = self.gpu_map(triplet_prediction, settings)
          return np.concatenate(results)
  
      def graphvite_predict():
          num_entity = len(entity2id)
          if target == "both":
              batch_size = self.get_batch_size(num_entity * 2)
          else:
              batch_size = self.get_batch_size(num_entity)
          rankings = []
  
          for i in range(0, fast_mode, batch_size):
              batch_h = H[i : i + batch_size]
              batch_r = R[i : i + batch_size]
              batch_t = T[i : i + batch_size]
              batch = self.generate_one_vs_rest(
                  batch_h, batch_r, batch_t, num_entity, target
              )
              masks = self.generate_mask(
                  batch_h,
                  batch_r,
                  batch_t,
                  exclude_H,
                  exclude_T,
                  num_entity,
                  target,
              )
              if target == "head":
                  positives = batch_h
              if target == "tail":
                  positives = batch_t
              if target == "both":
                  positives = np.asarray([batch_h, batch_t]).transpose()
                  positives = positives.ravel()
  
              scores = self.solver.predict(batch)
              scores = scores.reshape(-1, num_entity)
              truths = scores[range(len(positives)), positives]
              ranking = np.sum(
                  (scores >= truths[:, np.newaxis]) * masks, axis=1
              )
              rankings.append(ranking)
  
          return np.concatenate(rankings)
  
      assert_in(["head", "tail", "both"], target=target)
      assert_in(["graphvite", "torch"], backend=backend)
  
      if backend == "torch":
          self.solver.clear()
  
      if file_name:
          if not (H is None and R is None and T is None):
              raise ValueError(
                  "Evaluation data and file should not be provided at the same time"
              )
          H = []
          R = []
          T = []
          with open(file_name, "r") as fin:
              for i, line in enumerate(fin):
                  tokens = self.tokenize(line)
                  if len(tokens) == 0:
                      continue
                  if 3 <= len(tokens) <= 4:
                      h, r, t = tokens[:3]
                  else:
                      raise ValueError(
                          "Invalid line format at line %d in %s"
                          % (i + 1, file_name)
                      )
                  H.append(h)
                  R.append(r)
                  T.append(t)
      if H is None or R is None or T is None:
          raise ValueError(
              "Either evaluation data or file should be provided"
          )
  
      if filter_files:
          if not (
              filter_H is None and filter_R is None and filter_T is None
          ):
              raise ValueError(
                  "Filter data and file should not be provided at the same time"
              )
          filter_H = []
          filter_R = []
          filter_T = []
          for filter_file in filter_files:
              with open(filter_file, "r") as fin:
                  for i, line in enumerate(fin):
                      tokens = self.tokenize(line)
                      if len(tokens) == 0:
                          continue
                      if 3 <= len(tokens) <= 4:
                          h, r, t = tokens[:3]
                      else:
                          raise ValueError(
                              "Invalid line format at line %d in %s"
                              % (i + 1, filter_file)
                          )
                      filter_H.append(h)
                      filter_R.append(r)
                      filter_T.append(t)
      elif filter_H is None:
          filter_H = []
          filter_R = []
          filter_T = []
  
      entity2id = self.graph.entity2id
      relation2id = self.graph.relation2id
      new_H, new_R, new_T = self.name_map(
          (entity2id, relation2id, entity2id), (H, R, T)
      )
      logger.info("effective triplets: %d / %d" % (len(new_H), len(H)))
      H = np.asarray(new_H, dtype=np.uint32)
      R = np.asarray(new_R, dtype=np.uint32)
      T = np.asarray(new_T, dtype=np.uint32)
      new_H, new_R, new_T = self.name_map(
          (entity2id, relation2id, entity2id),
          (filter_H, filter_R, filter_T),
      )
      logger.info(
          "effective filter triplets: %d / %d"
          % (len(new_H), len(filter_H))
      )
      filter_H = np.asarray(new_H, dtype=np.uint32)
      filter_R = np.asarray(new_R, dtype=np.uint32)
      filter_T = np.asarray(new_T, dtype=np.uint32)
  
      exclude_H = defaultdict(set)
      exclude_T = defaultdict(set)
      for h, r, t in zip(filter_H, filter_R, filter_T):
          exclude_H[(t, r)].add(h)
          exclude_T[(h, r)].add(t)
  
      num_sample = len(H)
      fast_mode = fast_mode or num_sample
      indexes = np.random.permutation(num_sample)[:fast_mode]
      H = H[indexes]
      R = R[indexes]
      T = T[indexes]
  
      if backend == "graphvite":
          rankings = graphvite_predict()
      elif backend == "torch":
          rankings = torch_predict()
  
      return {
          "MR": np.mean(rankings),
          "MRR": np.mean(1 / rankings),
          "HITS@1": np.mean(rankings <= 1),
          "HITS@3": np.mean(rankings <= 3),
          "HITS@10": np.mean(rankings <= 10),
      }
  
imports: from __future__ import print_function, absolute_import, unicode_literals, division
  import os
  import re
  import pickle
  import logging
  import multiprocessing
  from collections import defaultdict
  from future.builtins import str, map, range
  from easydict import EasyDict
  import numpy
  from ..None import lib, cfg, auto
  from ..None import graph, solver
  from ..util import assert_in, monitor, SharedNDArray
label_desc: Use image node_id 5 for calling the KnowledgeGraphApplication obj's underlying member method code with example usage: obj.link_prediction(H, R, T, filter_H, filter_R, filter_T, file_name, filter_files, target, fast_mode, backend) and returns: dict, np, np