class_docstr: A hierarchical encoder that stacks basic RNN encoders into two layers.
  Can be used to encode long, structured sequences, e.g. paragraphs, dialog
  history, etc.
  
  Args:
      encoder_major (optional): An instance of subclass of
          :class:`~texar.tf.modules.RNNEncoderBase`
          The high-level encoder taking final
          states from low-level encoder as its
          inputs. If not specified, an encoder
          is created as specified in
          :attr:`hparams["encoder_major"]`.
      encoder_minor (optional): An instance of subclass of
          :class:`~texar.tf.modules.RNNEncoderBase`
          The low-level encoder. If not
          specified, an encoder is created as specified
          in :attr:`hparams["encoder_minor"]`.
      hparams (dict or HParams, optional): Hyperparameters. Missing
          hyperparamerter will be set to default values. See
          :meth:`default_hparams` for the hyperparameter sturcture and
          default values.
  
  See :meth:`_build` for the inputs and outputs of the encoder.
  
  .. document private functions
  .. automethod:: _build
docstr: Encodes the inputs.
  
  Args:
      inputs: A 4-D tensor of shape `[B, T, U, dim]`, where
  
          - B: batch_size
          - T: the max length of high-level sequences. E.g., the max                 number of utterances in dialog history.
          - U: the max length of low-level sequences. E.g., the max                 length of each utterance in dialog history.
          - dim: embedding dimension
  
          The order of first three dimensions can be changed
          according to :attr:`order`.
  
      order: A 3-char string containing 'b', 't', and 'u',
          that specifies the order of inputs dimensions above.
          Following four can be accepted:
  
              - **'btu'**: None of the encoders are time-major.
              - **'utb'**: Both encoders are time-major.
              - **'tbu'**: The major encoder is time-major.
              - **'ubt'**: The minor encoder is time-major.
  
      medium (optional): A list of callables that subsequently process the
          final states of minor encoder and obtain the inputs
          for the major encoder.
          If not specified, :meth:`flatten` is used for processing
          the minor's final states.
      sequence_length_major (optional): The `sequence_length` argument
          sent to major encoder. This is a 1-D Tensor of shape
          `[B]`.
      sequence_length_minor (optional): The `sequence_length` argument
          sent to minor encoder. It can be either a 1-D Tensor of shape
          `[B*T]`, or a 2-D Tensor of shape `[B, T]` or `[T, B]`
          according to :attr:`order`.
      **kwargs: Other keyword arguments for the major and minor encoders,
          such as `initial_state`, etc.
          Note that `sequence_length`, and `time_major`
          must not be included here.
          `time_major` is derived from :attr:`order` automatically.
          By default, arguments will be sent to both major and minor
          encoders. To specify which encoder an argument should be sent
          to, add '_minor'/'_major' as its suffix.
  
          Note that `initial_state_minor` must have a batch dimension
          of size `B*T`. If you have an initial state of batch dimension
          = `T`, use :meth:`tile_initial_state_minor` to tile it
          according to `order`.
  
  Returns:
      A tuple `(outputs, final_state)` by the major encoder.
  
      See
      the return values of `_build()` method of respective encoder class
      for details.
docstr_tok: ["Encodes","the","inputs",".","Args",":","inputs",":","A","4-D","tensor","of","shape","`","[","B",",","T",",","U",",","dim","]","`",",","where","-","B",":","batch_size","-","T",":","the","max","length","of","high-level","sequences",".","E.g.",",","the","max","number","of","utterances","in","dialog","history",".","-","U",":","the","max","length","of","low-level","sequences",".","E.g.",",","the","max","length","of","each","utterance","in","dialog","history",".","-","dim",":","embedding","dimension","The","order","of","first","three","dimensions","can","be","changed","according","to",":","attr",":","`","order","`",".","order",":","A","3-char","string","containing","'","b","'",",","'t","'",",","and","'","u","'",",","that","specifies","the","order","of","inputs","dimensions","above",".","Following","four","can","be","accepted",":","-","*","*","'btu","'","*","*",":","None","of","the","encoders","are","time-major",".","-","*","*","'utb","'","*","*",":","Both","encoders","are","time-major",".","-","*","*","'tbu","'","*","*",":","The","major","encoder","is","time-major",".","-","*","*","'ubt","'","*","*",":","The","minor","encoder","is","time-major",".","medium","(","optional",")",":","A","list","of","callables","that","subsequently","process","the","final","states","of","minor","encoder","and","obtain","the","inputs","for","the","major","encoder",".","If","not","specified",",",":","meth",":","`","flatten","`","is","used","for","processing","the","minor","'s","final","states",".","sequence_length_major","(","optional",")",":","The","`","sequence_length","`","argument","sent","to","major","encoder",".","This","is","a","1-D","Tensor","of","shape","`","[","B","]","`",".","sequence_length_minor","(","optional",")",":","The","`","sequence_length","`","argument","sent","to","minor","encoder",".","It","can","be","either","a","1-D","Tensor","of","shape","`","[","B","*","T","]","`",",","or","a","2-D","Tensor","of","shape","`","[","B",",","T","]","`","or","`","[","T",",","B","]","`","according","to",":","attr",":","`","order","`",".","*","*","kwargs",":","Other","keyword","arguments","for","the","major","and","minor","encoders",",","such","as","`","initial_state","`",",","etc",".","Note","that","`","sequence_length","`",",","and","`","time_major","`","must","not","be","included","here",".","`","time_major","`","is","derived","from",":","attr",":","`","order","`","automatically",".","By","default",",","arguments","will","be","sent","to","both","major","and","minor","encoders",".","To","specify","which","encoder","an","argument","should","be","sent","to",",","add","'_minor'\/'_major","'","as","its","suffix",".","Note","that","`","initial_state_minor","`","must","have","a","batch","dimension","of","size","`","B","*","T","`",".","If","you","have","an","initial","state","of","batch","dimension","=","`","T","`",",","use",":","meth",":","`","tile_initial_state_minor","`","to","tile","it","according","to","`","order","`",".","Returns",":","A","tuple","`","(","outputs",",","final_state",")","`","by","the","major","encoder",".","See","the","return","values","of","`","_build","(",")","`","method","of","respective","encoder","class","for","details","."]
code: def _build(
      self,
      inputs,
      order="btu",
      medium=None,
      sequence_length_major=None,
      sequence_length_minor=None,
      **kwargs,
  ):
      """Encodes the inputs.
  
          Args:
              inputs: A 4-D tensor of shape `[B, T, U, dim]`, where
  
                  - B: batch_size
                  - T: the max length of high-level sequences. E.g., the max \
                  number of utterances in dialog history.
                  - U: the max length of low-level sequences. E.g., the max \
                  length of each utterance in dialog history.
                  - dim: embedding dimension
  
                  The order of first three dimensions can be changed
                  according to :attr:`order`.
  
              order: A 3-char string containing 'b', 't', and 'u',
                  that specifies the order of inputs dimensions above.
                  Following four can be accepted:
  
                      - **'btu'**: None of the encoders are time-major.
                      - **'utb'**: Both encoders are time-major.
                      - **'tbu'**: The major encoder is time-major.
                      - **'ubt'**: The minor encoder is time-major.
  
              medium (optional): A list of callables that subsequently process the
                  final states of minor encoder and obtain the inputs
                  for the major encoder.
                  If not specified, :meth:`flatten` is used for processing
                  the minor's final states.
              sequence_length_major (optional): The `sequence_length` argument
                  sent to major encoder. This is a 1-D Tensor of shape
                  `[B]`.
              sequence_length_minor (optional): The `sequence_length` argument
                  sent to minor encoder. It can be either a 1-D Tensor of shape
                  `[B*T]`, or a 2-D Tensor of shape `[B, T]` or `[T, B]`
                  according to :attr:`order`.
              **kwargs: Other keyword arguments for the major and minor encoders,
                  such as `initial_state`, etc.
                  Note that `sequence_length`, and `time_major`
                  must not be included here.
                  `time_major` is derived from :attr:`order` automatically.
                  By default, arguments will be sent to both major and minor
                  encoders. To specify which encoder an argument should be sent
                  to, add '_minor'/'_major' as its suffix.
  
                  Note that `initial_state_minor` must have a batch dimension
                  of size `B*T`. If you have an initial state of batch dimension
                  = `T`, use :meth:`tile_initial_state_minor` to tile it
                  according to `order`.
  
          Returns:
              A tuple `(outputs, final_state)` by the major encoder.
  
              See
              the return values of `_build()` method of respective encoder class
              for details.
          """
  
      def _kwargs_split(kwargs):
          kwargs_minor, kwargs_major = {}, {}
          for k, v in kwargs.items():
              if len(k) >= 6 and k[-6:] == ["_minor"]:
                  kwargs_minor[k[:-6]] = v
              if len(k) >= 6 and k[-6:] == ["_major"]:
                  kwargs_major[k[:-6]] = v
          return kwargs_minor, kwargs_major
  
      kwargs_minor, kwargs_major = _kwargs_split(kwargs)
      if sequence_length_minor is not None:
          sequence_length_minor = tf.reshape(
              sequence_length_minor, [-1]
          )
      kwargs_minor["sequence_length"] = sequence_length_minor
      kwargs_major["sequence_length"] = sequence_length_major
  
      expand, shape = self._get_flatten_order(
          order, kwargs_minor, kwargs_major, tf.shape(inputs)
      )
  
      inputs = tf.reshape(inputs, shape + [inputs.shape[3]])
  
      _, states_minor = self._encoder_minor(inputs, **kwargs_minor)
  
      self.states_minor_before_medium = states_minor
  
      if medium is None:
          states_minor = self.flatten(states_minor)
      else:
          if not isinstance(medium, collections.Sequence):
              medium = [medium]
          for fn in medium:
              if isinstance(fn, str) and fn == "flatten":
                  states_minor = self.flatten(states_minor)
              else:
                  states_minor = fn(states_minor)
  
      self.states_minor_after_medium = states_minor
  
      states_minor = tf.reshape(
          states_minor,
          tf.concat([expand, tf.shape(states_minor)[1:]], 0),
      )
  
      outputs_major, states_major = self._encoder_major(
          states_minor, **kwargs_major
      )
  
      # Add trainable variables of `self._cell` which may be constructed
      # externally
      if not self._built:
          self._add_trainable_variable(
              self._encoder_minor.trainable_variables
          )
          self._add_trainable_variable(
              self._encoder_major.trainable_variables
          )
          self._built = True
  
      return outputs_major, states_major
  
file_path: texar/texar/tf/modules/encoders/hierarchical_encoders.py
imports: import collections
  import tensorflow
  from tensorflow.contrib.rnn import LSTMStateTuple
  from tensorflow.python.util import nest
  from texar.tf.modules.encoders.encoder_base import EncoderBase
  from texar.tf.utils import utils
label_desc: Use image node_id 3 for calling the HierarchicalRNNEncoder obj's underlying member method code with example usage: obj._build(inputs, order, medium, sequence_length_major, sequence_length_minor) and returns: outputs_major,  states_major, kwargs_minor,  kwargs_major