class_docstr: Simple word embedder that maps indexes into embeddings. The indexes
  can be soft (e.g., distributions over vocabulary).
  
  Either :attr:`init_value` or :attr:`vocab_size` is required. If both are
  given, there must be ``init_value.shape[0]==vocab_size``.
  
  Args:
      init_value (optional): A Tensor or numpy array that contains the
          initial value of embeddings. It is typically of shape
          ``[vocab_size] + embedding-dim``. Embedding can have dimensionality
          > 1.
  
          If `None`, embedding is initialized as specified in
          ``hparams["initializer"]``. Otherwise, the
          ``"initializer"`` and ``"dim"`` hyperparameters in
          :attr:`hparams` are ignored.
      vocab_size (int, optional): The vocabulary size. Required if
          :attr:`init_value` is not given.
      hparams (dict, optional): Embedder hyperparameters. Missing
          hyperparamerter will be set to default values. See
          :meth:`default_hparams` for the hyperparameter structure and
          default values.
  
  See :meth:`_build` for the inputs and outputs of the embedder.
  
  Example:
  
      .. code-block:: python
  
          ids = tf.random_uniform(shape=[32, 10], maxval=10, dtype=tf.int64)
          soft_ids = tf.random_uniform(shape=[32, 10, 100])
  
          embedder = WordEmbedder(vocab_size=100, hparams={'dim': 256})
          ids_emb = embedder(ids=ids) # shape: [32, 10, 256]
          soft_ids_emb = embedder(soft_ids=soft_ids) # shape: [32, 10, 256]
  
      .. code-block:: python
  
          # Use with Texar data module
          hparams={
              'dataset': {
                  'embedding_init': {'file': 'word2vec.txt'}
                  ...
              },
          }
          data = MonoTextData(data_params)
          iterator = DataIterator(data)
          batch = iterator.get_next()
  
          # Use data vocab size
          embedder_1 = WordEmbedder(vocab_size=data.vocab.size)
          emb_1 = embedder_1(batch['text_ids'])
  
          # Use pre-trained embedding
          embedder_2 = WordEmbedder(init_value=data.embedding_init_value)
          emb_2 = embedder_2(batch['text_ids'])
  
  
  .. document private functions
  .. automethod:: _build
class_docstr_tok: ["Simple","word","embedder","that","maps","indexes","into","embeddings",".","The","indexes","can","be","soft","(","e.g.",",","distributions","over","vocabulary",")",".","Either",":","attr",":","`","init_value","`","or",":","attr",":","`","vocab_size","`","is","required",".","If","both","are","given",",","there","must","be","``","init_value.shape","[","0","]","==vocab_size","``",".","Args",":","init_value","(","optional",")",":","A","Tensor","or","numpy","array","that","contains","the","initial","value","of","embeddings",".","It","is","typically","of","shape","``","[","vocab_size","]","+","embedding-dim","``",".","Embedding","can","have","dimensionality",">","1",".","If","`","None","`",",","embedding","is","initialized","as","specified","in","``","hparams","[","``","initializer","''","]","``",".","Otherwise",",","the","``","``","initializer","''","``","and","``","``","dim","''","``","hyperparameters","in",":","attr",":","`","hparams","`","are","ignored",".","vocab_size","(","int",",","optional",")",":","The","vocabulary","size",".","Required","if",":","attr",":","`","init_value","`","is","not","given",".","hparams","(","dict",",","optional",")",":","Embedder","hyperparameters",".","Missing","hyperparamerter","will","be","set","to","default","values",".","See",":","meth",":","`","default_hparams","`","for","the","hyperparameter","structure","and","default","values",".","See",":","meth",":","`","_build","`","for","the","inputs","and","outputs","of","the","embedder",".","Example",":","..","code-block",":",":","python","ids","=","tf.random_uniform","(","shape=","[","32",",","10","]",",","maxval=10",",","dtype=tf.int64",")","soft_ids","=","tf.random_uniform","(","shape=","[","32",",","10",",","100","]",")","embedder","=","WordEmbedder","(","vocab_size=100",",","hparams=","{","'dim","'",":","256","}",")","ids_emb","=","embedder","(","ids=ids",")","#","shape",":","[","32",",","10",",","256","]","soft_ids_emb","=","embedder","(","soft_ids=soft_ids",")","#","shape",":","[","32",",","10",",","256","]","..","code-block",":",":","python","#","Use","with","Texar","data","module","hparams=","{","'dataset","'",":","{","'embedding_init","'",":","{","'file","'",":","'word2vec.txt","'","}","...","}",",","}","data","=","MonoTextData","(","data_params",")","iterator","=","DataIterator","(","data",")","batch","=","iterator.get_next","(",")","#","Use","data","vocab","size","embedder_1","=","WordEmbedder","(","vocab_size=data.vocab.size",")","emb_1","=","embedder_1","(","batch","[","'text_ids","'","]",")","#","Use","pre-trained","embedding","embedder_2","=","WordEmbedder","(","init_value=data.embedding_init_value",")","emb_2","=","embedder_2","(","batch","[","'text_ids","'","]",")","..","document","private","functions","..","automethod",":",":","_build"]
docstr: Embeds (soft) ids.
  
  Either :attr:`ids` or :attr:`soft_ids` must be given, and they
  must not be given at the same time.
  
  Args:
      ids (optional): An integer tensor containing the ids to embed.
      soft_ids (optional): A tensor of weights (probabilities) used to
          mix the embedding vectors.
      mode (optional): A tensor taking value in
          :tf_main:`tf.estimator.ModeKeys <estimator/ModeKeys>`, including
          `TRAIN`, `EVAL`, and `PREDICT`. If `None`, dropout is
          controlled by :func:`texar.tf.global_mode`.
      kwargs: Additional keyword arguments for
          :tf_main:`tf.nn.embedding_lookup <nn/embedding_lookup>` besides
          :attr:`params` and :attr:`ids`.
  
  Returns:
      If :attr:`ids` is given, returns a Tensor of shape
      ``shape(ids) + embedding-dim``. For example,
      if ``shape(ids) = [batch_size, max_time]``
      and ``shape(embedding) = [vocab_size, emb_dim]``, then the return
      tensor has shape ``[batch_size, max_time, emb_dim]``.
  
      If :attr:`soft_ids` is given, returns a Tensor of shape
      ``shape(soft_ids)[:-1] + embdding-dim``. For example,
      if ``shape(soft_ids) = [batch_size, max_time, vocab_size]``
      and ``shape(embedding) = [vocab_size, emb_dim]``, then the return
      tensor has shape ``[batch_size, max_time, emb_dim]``.
docstr_tok: ["Embeds","(","soft",")","ids",".","Either",":","attr",":","`","ids","`","or",":","attr",":","`","soft_ids","`","must","be","given",",","and","they","must","not","be","given","at","the","same","time",".","Args",":","ids","(","optional",")",":","An","integer","tensor","containing","the","ids","to","embed",".","soft_ids","(","optional",")",":","A","tensor","of","weights","(","probabilities",")","used","to","mix","the","embedding","vectors",".","mode","(","optional",")",":","A","tensor","taking","value","in",":","tf_main",":","`","tf.estimator.ModeKeys","<","estimator\/ModeKeys",">","`",",","including","`","TRAIN","`",",","`","EVAL","`",",","and","`","PREDICT","`",".","If","`","None","`",",","dropout","is","controlled","by",":","func",":","`","texar.tf.global_mode","`",".","kwargs",":","Additional","keyword","arguments","for",":","tf_main",":","`","tf.nn.embedding_lookup","<","nn\/embedding_lookup",">","`","besides",":","attr",":","`","params","`","and",":","attr",":","`","ids","`",".","Returns",":","If",":","attr",":","`","ids","`","is","given",",","returns","a","Tensor","of","shape","``","shape","(","ids",")","+","embedding-dim","``",".","For","example",",","if","``","shape","(","ids",")","=","[","batch_size",",","max_time","]","``","and","``","shape","(","embedding",")","=","[","vocab_size",",","emb_dim","]","``",",","then","the","return","tensor","has","shape","``","[","batch_size",",","max_time",",","emb_dim","]","``",".","If",":","attr",":","`","soft_ids","`","is","given",",","returns","a","Tensor","of","shape","``","shape","(","soft_ids",")","[",":","-1","]","+","embdding-dim","``",".","For","example",",","if","``","shape","(","soft_ids",")","=","[","batch_size",",","max_time",",","vocab_size","]","``","and","``","shape","(","embedding",")","=","[","vocab_size",",","emb_dim","]","``",",","then","the","return","tensor","has","shape","``","[","batch_size",",","max_time",",","emb_dim","]","``","."]
code: def _build(self, ids=None, soft_ids=None, mode=None, **kwargs):
      r"""Embeds (soft) ids.
  
      Either :attr:`ids` or :attr:`soft_ids` must be given, and they
      must not be given at the same time.
  
      Args:
          ids (optional): An integer tensor containing the ids to embed.
          soft_ids (optional): A tensor of weights (probabilities) used to
              mix the embedding vectors.
          mode (optional): A tensor taking value in
              :tf_main:`tf.estimator.ModeKeys <estimator/ModeKeys>`, including
              `TRAIN`, `EVAL`, and `PREDICT`. If `None`, dropout is
              controlled by :func:`texar.tf.global_mode`.
          kwargs: Additional keyword arguments for
              :tf_main:`tf.nn.embedding_lookup <nn/embedding_lookup>` besides
              :attr:`params` and :attr:`ids`.
  
      Returns:
          If :attr:`ids` is given, returns a Tensor of shape
          ``shape(ids) + embedding-dim``. For example,
          if ``shape(ids) = [batch_size, max_time]``
          and ``shape(embedding) = [vocab_size, emb_dim]``, then the return
          tensor has shape ``[batch_size, max_time, emb_dim]``.
  
          If :attr:`soft_ids` is given, returns a Tensor of shape
          ``shape(soft_ids)[:-1] + embdding-dim``. For example,
          if ``shape(soft_ids) = [batch_size, max_time, vocab_size]``
          and ``shape(embedding) = [vocab_size, emb_dim]``, then the return
          tensor has shape ``[batch_size, max_time, emb_dim]``.
      """
      if ids is not None:
          if soft_ids is not None:
              raise ValueError(
                  "Must not specify `ids` and `soft_ids` at the same time."
              )
          ids_rank = get_rank(ids)
      elif soft_ids is not None:
          ids_rank = get_rank(soft_ids) - 1
      else:
          raise ValueError("Either `ids` or `soft_ids` must be given.")
  
      embedding = self._embedding
  
      is_training = is_train_mode(mode)
      if self._hparams.dropout_strategy == "item_type":
          dropout_layer = self._get_dropout_layer(self._hparams)
          if dropout_layer:
              embedding = dropout_layer.apply(
                  inputs=embedding, training=is_training
              )
  
      if ids is not None:
          outputs = tf.nn.embedding_lookup(embedding, ids, **kwargs)
      else:
          outputs = embedder_utils.soft_embedding_lookup(
              embedding, soft_ids
          )
  
      if self._hparams.dropout_strategy != "item_type":
          dropout_layer = self._get_dropout_layer(
              self._hparams, ids_rank=ids_rank, dropout_input=outputs
          )
          if dropout_layer:
              outputs = dropout_layer.apply(
                  inputs=outputs, training=is_training
              )
  
      return outputs
  
file_path: texar/texar/tf/modules/embedders/embedders.py
imports: import tensorflow
  from texar.tf.modules.embedders.embedder_base import EmbedderBase
  from texar.tf.modules.embedders import embedder_utils
  from texar.tf.utils.mode import is_train_mode
  from texar.tf.utils.shapes import get_rank
label_desc: Use image node_id 3 for calling the WordEmbedder obj's underlying member method code with example usage: obj._build(ids, soft_ids, mode) and returns: outputs