class_docstr: Hidden Markov model distribution.
  
  The `HiddenMarkovModel` distribution implements a (batch of) discrete hidden
  Markov models where the initial states, transition probabilities
  and observed states are all given by user-provided distributions.
  
  In this model, there is a sequence of integer-valued hidden states:
  `z[0], z[1], ..., z[num_steps - 1]` and a sequence of observed states:
  `x[0], ..., x[num_steps - 1]`.
  The distribution of `z[0]` is given by `initial_distribution`.
  The conditional probability of `z[i  +  1]` given `z[i]` is described by
  the batch of distributions in `transition_distribution`.
  For a batch of hidden Markov models, the coordinates before the rightmost one
  of the `transition_distribution` batch correspond to indices into the hidden
  Markov model batch. The rightmost coordinate of the batch is used to select
  which distribution `z[i + 1]` is drawn from.  The distributions corresponding
  to the probability of `z[i + 1]` conditional on `z[i] == k` is given by the
  elements of the batch whose rightmost coordinate is `k`.
  Similarly, the conditional distribution of `x[i]` given `z[i]` is given by
  the batch of `observation_distribution`.
  When the rightmost coordinate of `observation_distribution` is `k` it
  gives the conditional probabilities of `x[i]` given `z[i] == k`.
  The probability distribution associated with the `HiddenMarkovModel`
  distribution is the marginal distribution of `x[0],...,x[num_steps - 1]`.
  
  #### Examples
  
  ```python
  tfd = tfp.distributions
  
  # A simple weather model.
  
  # Represent a cold day with 0 and a hot day with 1.
  # Suppose the first day of a sequence has a 0.8 chance of being cold.
  # We can model this using the categorical distribution:
  
  initial_distribution = tfd.Categorical(probs=[0.8, 0.2])
  
  # Suppose a cold day has a 30% chance of being followed by a hot day
  # and a hot day has a 20% chance of being followed by a cold day.
  # We can model this as:
  
  transition_distribution = tfd.Categorical(probs=[[0.7, 0.3],
                                                   [0.2, 0.8]])
  
  # Suppose additionally that on each day the temperature is
  # normally distributed with mean and standard deviation 0 and 5 on
  # a cold day and mean and standard deviation 15 and 10 on a hot day.
  # We can model this with:
  
  observation_distribution = tfd.Normal(loc=[0., 15.], scale=[5., 10.])
  
  # We can combine these distributions into a single week long
  # hidden Markov model with:
  
  model = tfd.HiddenMarkovModel(
      initial_distribution=initial_distribution,
      transition_distribution=transition_distribution,
      observation_distribution=observation_distribution,
      num_steps=7)
  
  # The expected temperatures for each day are given by:
  
  model.mean()  # shape [7], elements approach 9.0
  
  # The log pdf of a week of temperature 0 is:
  
  model.log_prob(tf.zeros(shape=[7]))
  ```
  
  #### References
  [1] https://en.wikipedia.org/wiki/Hidden_Markov_model
class_docstr_tok: ["Hidden","Markov","model","distribution",".","The","`","HiddenMarkovModel","`","distribution","implements","a","(","batch","of",")","discrete","hidden","Markov","models","where","the","initial","states",",","transition","probabilities","and","observed","states","are","all","given","by","user-provided","distributions",".","In","this","model",",","there","is","a","sequence","of","integer-valued","hidden","states",":","`","z","[","0","]",",","z","[","1","]",",","...",",","z","[","num_steps","-","1","]","`","and","a","sequence","of","observed","states",":","`","x","[","0","]",",","...",",","x","[","num_steps","-","1","]","`",".","The","distribution","of","`","z","[","0","]","`","is","given","by","`","initial_distribution","`",".","The","conditional","probability","of","`","z","[","i","+","1","]","`","given","`","z","[","i","]","`","is","described","by","the","batch","of","distributions","in","`","transition_distribution","`",".","For","a","batch","of","hidden","Markov","models",",","the","coordinates","before","the","rightmost","one","of","the","`","transition_distribution","`","batch","correspond","to","indices","into","the","hidden","Markov","model","batch",".","The","rightmost","coordinate","of","the","batch","is","used","to","select","which","distribution","`","z","[","i","+","1","]","`","is","drawn","from",".","The","distributions","corresponding","to","the","probability","of","`","z","[","i","+","1","]","`","conditional","on","`","z","[","i","]","==","k","`","is","given","by","the","elements","of","the","batch","whose","rightmost","coordinate","is","`","k","`",".","Similarly",",","the","conditional","distribution","of","`","x","[","i","]","`","given","`","z","[","i","]","`","is","given","by","the","batch","of","`","observation_distribution","`",".","When","the","rightmost","coordinate","of","`","observation_distribution","`","is","`","k","`","it","gives","the","conditional","probabilities","of","`","x","[","i","]","`","given","`","z","[","i","]","==","k","`",".","The","probability","distribution","associated","with","the","`","HiddenMarkovModel","`","distribution","is","the","marginal","distribution","of","`","x","[","0","]",",","...",",","x","[","num_steps","-","1","]","`",".","#","#","#","#","Examples","``","`","python","tfd","=","tfp.distributions","#","A","simple","weather","model",".","#","Represent","a","cold","day","with","0","and","a","hot","day","with","1",".","#","Suppose","the","first","day","of","a","sequence","has","a","0.8","chance","of","being","cold",".","#","We","can","model","this","using","the","categorical","distribution",":","initial_distribution","=","tfd.Categorical","(","probs=","[","0.8",",","0.2","]",")","#","Suppose","a","cold","day","has","a","30","%","chance","of","being","followed","by","a","hot","day","#","and","a","hot","day","has","a","20","%","chance","of","being","followed","by","a","cold","day",".","#","We","can","model","this","as",":","transition_distribution","=","tfd.Categorical","(","probs=","[","[","0.7",",","0.3","]",",","[","0.2",",","0.8","]","]",")","#","Suppose","additionally","that","on","each","day","the","temperature","is","#","normally","distributed","with","mean","and","standard","deviation","0","and","5","on","#","a","cold","day","and","mean","and","standard","deviation","15","and","10","on","a","hot","day",".","#","We","can","model","this","with",":","observation_distribution","=","tfd.Normal","(","loc=","[","0.",",","15",".","]",",","scale=","[","5.",",","10",".","]",")","#","We","can","combine","these","distributions","into","a","single","week","long","#","hidden","Markov","model","with",":","model","=","tfd.HiddenMarkovModel","(","initial_distribution=initial_distribution",",","transition_distribution=transition_distribution",",","observation_distribution=observation_distribution",",","num_steps=7",")","#","The","expected","temperatures","for","each","day","are","given","by",":","model.mean","(",")","#","shape","[","7","]",",","elements","approach","9.0","#","The","log","pdf","of","a","week","of","temperature","0","is",":","model.log_prob","(","tf.zeros","(","shape=","[","7","]",")",")","``","`","#","#","#","#","References","[","1","]","https",":","\/\/en.wikipedia.org\/wiki\/Hidden_Markov_model"]
docstr: Compute marginal posterior distribution for each state.
  
  This function computes, for each time step, the marginal conditional
  probability that the hidden Markov model was in each possible state given
  the observations that were made at each time step.
  
  So if the hidden states are `z[0],...,z[num_steps - 1]` and
  the observations are `x[0], ..., x[num_steps - 1]`, then
  this function computes `P(z[i] | x[0], ..., x[num_steps - 1])`
  for all `i` from `0` to `num_steps - 1`.
  
  This operation is sometimes called smoothing. It uses a form
  of the forward-backward algorithm.
  
  Note: the behavior of this function is undefined if the
  `observations` argument represents impossible observations
  from the model.
  
  Args:
    observations: A tensor representing a batch of observations made on the
      hidden Markov model.  The rightmost dimensions of this tensor correspond
      to the dimensions of the observation distributions of the underlying
      Markov chain, if the observations are non-scalar.  The next dimension
      from the right indexes the steps in a sequence of observations from a
      single sample from the hidden Markov model.  The size of this dimension
      should match the `num_steps` parameter of the hidden Markov model
      object.  The other dimensions are the dimensions of the batch and these
      are broadcast with the hidden Markov model's parameters.
    mask: optional bool-type `tensor` with rightmost dimension matching
      `num_steps`, indicating which observations should be ignored
      (not conditioned on). When the mask has value `True`, the corresponding
      observations aren't used. If no mask is specified (`mask` and
      `self.mask` are both `None`) then all of the observations are used. The
      leftmost dimensions `shape(mask)[:-1]` must broadcast with
      `self.batch_shape`.
      Default value: `None` (falls back to `self.mask`).
    name: Python `str` name prefixed to Ops created by this class.
      Default value: "HiddenMarkovModel".
  
  Returns:
    posterior_marginal: A `Categorical` distribution object representing the
      marginal probability of the hidden Markov model being in each state at
      each step. The rightmost dimension of the `Categorical` distributions
      batch will equal the `num_steps` parameter providing one marginal
      distribution for each step. The other dimensions are the dimensions
      corresponding to the batch of observations.
  
  Raises:
    ValueError: if rightmost dimension of `observations` does not
    have size `num_steps`.
docstr_tok: ["Compute","marginal","posterior","distribution","for","each","state",".","This","function","computes",",","for","each","time","step",",","the","marginal","conditional","probability","that","the","hidden","Markov","model","was","in","each","possible","state","given","the","observations","that","were","made","at","each","time","step",".","So","if","the","hidden","states","are","`","z","[","0","]",",","...",",","z","[","num_steps","-","1","]","`","and","the","observations","are","`","x","[","0","]",",","...",",","x","[","num_steps","-","1","]","`",",","then","this","function","computes","`","P","(","z","[","i","]","|","x","[","0","]",",","...",",","x","[","num_steps","-","1","]",")","`","for","all","`","i","`","from","`","0","`","to","`","num_steps","-","1","`",".","This","operation","is","sometimes","called","smoothing",".","It","uses","a","form","of","the","forward-backward","algorithm",".","Note",":","the","behavior","of","this","function","is","undefined","if","the","`","observations","`","argument","represents","impossible","observations","from","the","model",".","Args",":","observations",":","A","tensor","representing","a","batch","of","observations","made","on","the","hidden","Markov","model",".","The","rightmost","dimensions","of","this","tensor","correspond","to","the","dimensions","of","the","observation","distributions","of","the","underlying","Markov","chain",",","if","the","observations","are","non-scalar",".","The","next","dimension","from","the","right","indexes","the","steps","in","a","sequence","of","observations","from","a","single","sample","from","the","hidden","Markov","model",".","The","size","of","this","dimension","should","match","the","`","num_steps","`","parameter","of","the","hidden","Markov","model","object",".","The","other","dimensions","are","the","dimensions","of","the","batch","and","these","are","broadcast","with","the","hidden","Markov","model","'s","parameters",".","mask",":","optional","bool-type","`","tensor","`","with","rightmost","dimension","matching","`","num_steps","`",",","indicating","which","observations","should","be","ignored","(","not","conditioned","on",")",".","When","the","mask","has","value","`","True","`",",","the","corresponding","observations","are","n't","used",".","If","no","mask","is","specified","(","`","mask","`","and","`","self.mask","`","are","both","`","None","`",")","then","all","of","the","observations","are","used",".","The","leftmost","dimensions","`","shape","(","mask",")","[",":","-1","]","`","must","broadcast","with","`","self.batch_shape","`",".","Default","value",":","`","None","`","(","falls","back","to","`","self.mask","`",")",".","name",":","Python","`","str","`","name","prefixed","to","Ops","created","by","this","class",".","Default","value",":","``","HiddenMarkovModel","''",".","Returns",":","posterior_marginal",":","A","`","Categorical","`","distribution","object","representing","the","marginal","probability","of","the","hidden","Markov","model","being","in","each","state","at","each","step",".","The","rightmost","dimension","of","the","`","Categorical","`","distributions","batch","will","equal","the","`","num_steps","`","parameter","providing","one","marginal","distribution","for","each","step",".","The","other","dimensions","are","the","dimensions","corresponding","to","the","batch","of","observations",".","Raises",":","ValueError",":","if","rightmost","dimension","of","`","observations","`","does","not","have","size","`","num_steps","`","."]
code: def posterior_marginals(
      self, observations, mask=None, name="posterior_marginals"
  ):
      """Compute marginal posterior distribution for each state.
  
      This function computes, for each time step, the marginal conditional
      probability that the hidden Markov model was in each possible state given
      the observations that were made at each time step.
  
      So if the hidden states are `z[0],...,z[num_steps - 1]` and
      the observations are `x[0], ..., x[num_steps - 1]`, then
      this function computes `P(z[i] | x[0], ..., x[num_steps - 1])`
      for all `i` from `0` to `num_steps - 1`.
  
      This operation is sometimes called smoothing. It uses a form
      of the forward-backward algorithm.
  
      Note: the behavior of this function is undefined if the
      `observations` argument represents impossible observations
      from the model.
  
      Args:
        observations: A tensor representing a batch of observations made on the
          hidden Markov model.  The rightmost dimensions of this tensor correspond
          to the dimensions of the observation distributions of the underlying
          Markov chain, if the observations are non-scalar.  The next dimension
          from the right indexes the steps in a sequence of observations from a
          single sample from the hidden Markov model.  The size of this dimension
          should match the `num_steps` parameter of the hidden Markov model
          object.  The other dimensions are the dimensions of the batch and these
          are broadcast with the hidden Markov model's parameters.
        mask: optional bool-type `tensor` with rightmost dimension matching
          `num_steps`, indicating which observations should be ignored
          (not conditioned on). When the mask has value `True`, the corresponding
          observations aren't used. If no mask is specified (`mask` and
          `self.mask` are both `None`) then all of the observations are used. The
          leftmost dimensions `shape(mask)[:-1]` must broadcast with
          `self.batch_shape`.
          Default value: `None` (falls back to `self.mask`).
        name: Python `str` name prefixed to Ops created by this class.
          Default value: "HiddenMarkovModel".
  
      Returns:
        posterior_marginal: A `Categorical` distribution object representing the
          marginal probability of the hidden Markov model being in each state at
          each step. The rightmost dimension of the `Categorical` distributions
          batch will equal the `num_steps` parameter providing one marginal
          distribution for each step. The other dimensions are the dimensions
          corresponding to the batch of observations.
  
      Raises:
        ValueError: if rightmost dimension of `observations` does not
        have size `num_steps`.
      """
      with self._name_and_control_scope(name):
          num_states = (
              self.transition_distribution.batch_shape_tensor()[-1]
          )
          log_transition = _extract_log_probs(
              num_states,
              self.transition_distribution,
              move_time_dimension=self._time_varying_transition_distribution,
          )
  
          forward_log_probs, observation_log_probs = self._forward_pass(
              observations, mask, log_transition
          )
          total_log_prob = tf.reduce_logsumexp(
              forward_log_probs[-1], axis=-1
          )
          backward_log_adjoint_probs = self._backward_pass(
              observation_log_probs, log_transition
          )
          log_likelihoods = (
              forward_log_probs + backward_log_adjoint_probs
          )
  
          marginal_log_probs = distribution_util.move_dimension(
              log_likelihoods - total_log_prob[..., tf.newaxis], 0, -2
          )
  
          return categorical.Categorical(logits=marginal_log_probs)
  
imports: import numpy
  import tensorflow.compat.v2
  from tensorflow_probability.python.distributions import categorical
  from tensorflow_probability.python.distributions import distribution
  from tensorflow_probability.python.internal import assert_util
  from tensorflow_probability.python.internal import distribution_util
  from tensorflow_probability.python.internal import dtype_util
  from tensorflow_probability.python.internal import parameter_properties
  from tensorflow_probability.python.internal import prefer_static
  from tensorflow_probability.python.internal import reparameterization
  from tensorflow_probability.python.internal import samplers
  from tensorflow_probability.python.internal import tensor_util
  from tensorflow_probability.python.internal import tensorshape_util
label_desc: Use image node_id 21 for calling the HiddenMarkovModel obj's underlying member method code with example usage: obj.posterior_marginals(observations, mask, name) and returns: categorical