class_docstr: Basic implementation of node piece decomposition [galkin2021]_.
  
  .. math ::
      x_e = agg(\{T[t] \mid t \in tokens(e) \})
  
  where $T$ are token representations, $tokens$ selects a fixed number of $k$ tokens for each entity, and $agg$ is
  an aggregation function, which aggregates the individual token representations to a single entity representation.
  
  ---
  name: NodePiece
  citation:
      author: Galkin
      year: 2021
      link: https://arxiv.org/abs/2106.12144
      github: https://github.com/migalkin/NodePiece
class_docstr_tok: ["Basic","implementation","of","node","piece","decomposition","[","galkin2021","]","_",".","..","math",":",":","x_e","=","agg","(","\\","{","T","[","t","]","\\mid","t","\\in","tokens","(","e",")","\\","}",")","where","$","T","$","are","token","representations",",","$","tokens","$","selects","a","fixed","number","of","$","k","$","tokens","for","each","entity",",","and","$","agg","$","is","an","aggregation","function",",","which","aggregates","the","individual","token","representations","to","a","single","entity","representation",".","--","-","name",":","NodePiece","citation",":","author",":","Galkin","year",":","2021","link",":","https",":","\/\/arxiv.org\/abs\/2106.12144","github",":","https",":","\/\/github.com\/migalkin\/NodePiece"]
docstr: Initialize the representation.
  
  :param triples_factory:
      the triples factory
  :param token_representations:
      the token representation specification, or pre-instantiated representation module.
  :param token_representations_kwargs:
      additional keyword-based parameters
  :param tokenizers:
      the tokenizer to use, cf. `pykeen.nn.node_piece.tokenizer_resolver`.
  :param tokenizers_kwargs:
      additional keyword-based parameters passed to the tokenizer upon construction.
  :param num_tokens:
      the number of tokens for each entity.
  :param aggregation:
      aggregation of multiple token representations to a single entity representation. By default,
      this uses :func:`torch.mean`. If a string is provided, the module assumes that this refers to a top-level
      torch function, e.g. "mean" for :func:`torch.mean`, or "sum" for func:`torch.sum`. An aggregation can
      also have trainable parameters, .e.g., ``MLP(mean(MLP(tokens)))`` (cf. DeepSets from [zaheer2017]_). In
      this case, the module has to be created outside of this component.
  
      We could also have aggregations which result in differently shapes output, e.g. a concatenation of all
      token embeddings resulting in shape ``(num_tokens * d,)``. In this case, `shape` must be provided.
  
      The aggregation takes two arguments: the (batched) tensor of token representations, in shape
      ``(*, num_tokens, *dt)``, and the index along which to aggregate.
  :param max_id:
      Only pass this to check if the number of entities in the triples factories is the same
  :param kwargs:
      additional keyword-based parameters passed to :meth:`CombinedRepresentation.__init__`
docstr_tok: ["Initialize","the","representation",".",":","param","triples_factory",":","the","triples","factory",":","param","token_representations",":","the","token","representation","specification",",","or","pre-instantiated","representation","module",".",":","param","token_representations_kwargs",":","additional","keyword-based","parameters",":","param","tokenizers",":","the","tokenizer","to","use",",","cf",".","`","pykeen.nn.node_piece.tokenizer_resolver","`",".",":","param","tokenizers_kwargs",":","additional","keyword-based","parameters","passed","to","the","tokenizer","upon","construction",".",":","param","num_tokens",":","the","number","of","tokens","for","each","entity",".",":","param","aggregation",":","aggregation","of","multiple","token","representations","to","a","single","entity","representation",".","By","default",",","this","uses",":","func",":","`","torch.mean","`",".","If","a","string","is","provided",",","the","module","assumes","that","this","refers","to","a","top-level","torch","function",",","e.g",".","``","mean","''","for",":","func",":","`","torch.mean","`",",","or","``","sum","''","for","func",":","`","torch.sum","`",".","An","aggregation","can","also","have","trainable","parameters",",",".e.g.",",","``","MLP","(","mean","(","MLP","(","tokens",")",")",")","``","(","cf",".","DeepSets","from","[","zaheer2017","]","_",")",".","In","this","case",",","the","module","has","to","be","created","outside","of","this","component",".","We","could","also","have","aggregations","which","result","in","differently","shapes","output",",","e.g",".","a","concatenation","of","all","token","embeddings","resulting","in","shape","``","(","num_tokens","*","d",",",")","``",".","In","this","case",",","`","shape","`","must","be","provided",".","The","aggregation","takes","two","arguments",":","the","(","batched",")","tensor","of","token","representations",",","in","shape","``","(","*",",","num_tokens",",","*","dt",")","``",",","and","the","index","along","which","to","aggregate",".",":","param","max_id",":","Only","pass","this","to","check","if","the","number","of","entities","in","the","triples","factories","is","the","same",":","param","kwargs",":","additional","keyword-based","parameters","passed","to",":","meth",":","`","CombinedRepresentation.__init__","`"]
code: def __init__(
      self,
      *,
      triples_factory: CoreTriplesFactory,
      token_representations: OneOrManyHintOrType[Representation] = None,
      token_representations_kwargs: OneOrManyOptionalKwargs = None,
      tokenizers: OneOrManyHintOrType[Tokenizer] = None,
      tokenizers_kwargs: OneOrManyOptionalKwargs = None,
      num_tokens: OneOrSequence[int] = 2,
      aggregation: Union[
          None,
          str,
          Callable[[torch.FloatTensor, int], torch.FloatTensor],
      ] = None,
      max_id: Optional[int] = None,
      **kwargs,
  ):
      """
      Initialize the representation.
  
      :param triples_factory:
          the triples factory
      :param token_representations:
          the token representation specification, or pre-instantiated representation module.
      :param token_representations_kwargs:
          additional keyword-based parameters
      :param tokenizers:
          the tokenizer to use, cf. `pykeen.nn.node_piece.tokenizer_resolver`.
      :param tokenizers_kwargs:
          additional keyword-based parameters passed to the tokenizer upon construction.
      :param num_tokens:
          the number of tokens for each entity.
      :param aggregation:
          aggregation of multiple token representations to a single entity representation. By default,
          this uses :func:`torch.mean`. If a string is provided, the module assumes that this refers to a top-level
          torch function, e.g. "mean" for :func:`torch.mean`, or "sum" for func:`torch.sum`. An aggregation can
          also have trainable parameters, .e.g., ``MLP(mean(MLP(tokens)))`` (cf. DeepSets from [zaheer2017]_). In
          this case, the module has to be created outside of this component.
  
          We could also have aggregations which result in differently shapes output, e.g. a concatenation of all
          token embeddings resulting in shape ``(num_tokens * d,)``. In this case, `shape` must be provided.
  
          The aggregation takes two arguments: the (batched) tensor of token representations, in shape
          ``(*, num_tokens, *dt)``, and the index along which to aggregate.
      :param max_id:
          Only pass this to check if the number of entities in the triples factories is the same
      :param kwargs:
          additional keyword-based parameters passed to :meth:`CombinedRepresentation.__init__`
      """
      if max_id:
          assert max_id == triples_factory.num_entities
  
      # normalize triples
      mapped_triples = triples_factory.mapped_triples
      if triples_factory.create_inverse_triples:
          # inverse triples are created afterwards implicitly
          mapped_triples = mapped_triples[
              mapped_triples[:, 1] < triples_factory.real_num_relations
          ]
  
      (
          token_representations,
          token_representations_kwargs,
          num_tokens,
      ) = broadcast_upgrade_to_sequences(
          token_representations,
          token_representations_kwargs,
          num_tokens,
      )
  
      # tokenize
      token_representations = [
          TokenizationRepresentation.from_tokenizer(
              tokenizer=tokenizer_inst,
              num_tokens=num_tokens_,
              token_representation=token_representation,
              token_representation_kwargs=token_representation_kwargs,
              mapped_triples=mapped_triples,
              num_entities=triples_factory.num_entities,
              num_relations=triples_factory.real_num_relations,
          )
          for tokenizer_inst, token_representation, token_representation_kwargs, num_tokens_ in zip(
              tokenizer_resolver.make_many(
                  queries=tokenizers, kwargs=tokenizers_kwargs
              ),
              token_representations,
              token_representations_kwargs,
              num_tokens,
          )
      ]
  
      # Create an MLP for string aggregation
      if aggregation == "mlp":
          # note: the token representations' shape includes the number of tokens as leading dim
          embedding_dim = token_representations[0].shape[1]
          aggregation = ConcatMLP(
              input_dim=embedding_dim * sum(num_tokens),
              output_dim=embedding_dim,
          )
  
      super().__init__(
          max_id=triples_factory.num_entities,
          base=token_representations,
          combination=ConcatAggregationCombination,
          combination_kwargs=dict(
              aggregation=aggregation,
              dim=-len(token_representations[0].shape),
          ),
          **kwargs,
      )
  
imports: import logging
  import pathlib
  from typing import Callable, Iterable, List, NamedTuple, Optional, Union
  import torch
  from class_resolver import HintOrType, OneOrManyHintOrType, OneOrManyOptionalKwargs, OptionalKwargs
  from docdata import parse_docdata
  from .tokenization import Tokenizer, tokenizer_resolver
  from ..combination import ConcatAggregationCombination
  from ..perceptron import ConcatMLP
  from ..representation import CombinedRepresentation, Representation
  from ..utils import ShapeError
  from ...triples import CoreTriplesFactory
  from ...typing import MappedTriples, OneOrSequence
  from ...utils import broadcast_upgrade_to_sequences
label_desc: Use image node_id 1 to create a new NodePieceRepresentation object from inherited base classes: CombinedRepresentation with example: obj = NodePieceRepresentation()