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: Initialize hidden Markov model.
  
  Args:
    initial_distribution: A `Categorical`-like instance.
      Determines probability of first hidden state in Markov chain.
      The number of categories must match the number of categories of
      `transition_distribution` as well as both the rightmost batch
      dimension of `transition_distribution` and the rightmost batch
      dimension of `observation_distribution`.
    transition_distribution: A `Categorical`-like instance.
      The rightmost batch dimension indexes the probability distribution
      of each hidden state conditioned on the previous hidden state.
    observation_distribution: A `tfp.distributions.Distribution`-like
      instance.  The rightmost batch dimension indexes the distribution
      of each observation conditioned on the corresponding hidden state.
    num_steps: The number of steps taken in Markov chain. An integer valued
      tensor. The number of transitions is `num_steps - 1`.
    validate_args: Python `bool`, default `False`. When `True` distribution
      parameters are checked for validity despite possibly degrading runtime
      performance. When `False` invalid inputs may silently render incorrect
      outputs.
      Default value: `False`.
    allow_nan_stats: Python `bool`, default `True`. When `True`, statistics
      (e.g., mean, mode, variance) use the value "`NaN`" to indicate the
      result is undefined. When `False`, an exception is raised if one or
      more of the statistic's batch members are undefined.
      Default value: `True`.
    time_varying_transition_distribution: Python `bool`, default `False`.
      When `True`, the transition_distribution has an additional batch
      dimension that indexes the distribution of each observation conditioned
      on the corresponding timestep. This dimension size should always match
      `num_steps -1` and is the second-to-last batch axis in the batch
      dimensions (just to the left of the dimension for the number of states).
      Because transitions only happen between steps, the number of transitions
      is one less than num_steps.
    time_varying_observation_distribution: Python `bool`, default `False`.
      When `True`, the observation_distribution has an additional batch
      dimension that indexes the distribution of each observation conditioned
      on the corresponding timestep. This dimension size should always match
      num_steps and is the second-to-last batch axis in the batch dimensions
      (just to the left of the dimension for the number of states).
    mask: optional bool-type `tensor` with rightmost dimension matching
      `num_steps`, indicating which observations should be ignored
      (not conditioned on) for posterior inference and `log_prob` evaluation.
      This may be overridden by passing the `mask` arg to individual methods.
      When the mask has value `True`, the corresponding observations aren't
      used. If `mask` is `None` then all of the observations are used.
      Default value: `None`.
    name: Python `str` name prefixed to Ops created by this class.
      Default value: "HiddenMarkovModel".
  
  Raises:
    ValueError: if `num_steps` is not at least 1.
    ValueError: if `initial_distribution` does not have scalar `event_shape`.
    ValueError: if `transition_distribution` does not have scalar
      `event_shape.`
    ValueError: if `transition_distribution` and `observation_distribution`
      are fully defined but don't have matching rightmost dimension.
docstr_tok: ["Initialize","hidden","Markov","model",".","Args",":","initial_distribution",":","A","`","Categorical","`","-like","instance",".","Determines","probability","of","first","hidden","state","in","Markov","chain",".","The","number","of","categories","must","match","the","number","of","categories","of","`","transition_distribution","`","as","well","as","both","the","rightmost","batch","dimension","of","`","transition_distribution","`","and","the","rightmost","batch","dimension","of","`","observation_distribution","`",".","transition_distribution",":","A","`","Categorical","`","-like","instance",".","The","rightmost","batch","dimension","indexes","the","probability","distribution","of","each","hidden","state","conditioned","on","the","previous","hidden","state",".","observation_distribution",":","A","`","tfp.distributions.Distribution","`","-like","instance",".","The","rightmost","batch","dimension","indexes","the","distribution","of","each","observation","conditioned","on","the","corresponding","hidden","state",".","num_steps",":","The","number","of","steps","taken","in","Markov","chain",".","An","integer","valued","tensor",".","The","number","of","transitions","is","`","num_steps","-","1","`",".","validate_args",":","Python","`","bool","`",",","default","`","False","`",".","When","`","True","`","distribution","parameters","are","checked","for","validity","despite","possibly","degrading","runtime","performance",".","When","`","False","`","invalid","inputs","may","silently","render","incorrect","outputs",".","Default","value",":","`","False","`",".","allow_nan_stats",":","Python","`","bool","`",",","default","`","True","`",".","When","`","True","`",",","statistics","(","e.g.",",","mean",",","mode",",","variance",")","use","the","value","``","`","NaN","`","``","to","indicate","the","result","is","undefined",".","When","`","False","`",",","an","exception","is","raised","if","one","or","more","of","the","statistic","'s","batch","members","are","undefined",".","Default","value",":","`","True","`",".","time_varying_transition_distribution",":","Python","`","bool","`",",","default","`","False","`",".","When","`","True","`",",","the","transition_distribution","has","an","additional","batch","dimension","that","indexes","the","distribution","of","each","observation","conditioned","on","the","corresponding","timestep",".","This","dimension","size","should","always","match","`","num_steps","-1","`","and","is","the","second-to-last","batch","axis","in","the","batch","dimensions","(","just","to","the","left","of","the","dimension","for","the","number","of","states",")",".","Because","transitions","only","happen","between","steps",",","the","number","of","transitions","is","one","less","than","num_steps",".","time_varying_observation_distribution",":","Python","`","bool","`",",","default","`","False","`",".","When","`","True","`",",","the","observation_distribution","has","an","additional","batch","dimension","that","indexes","the","distribution","of","each","observation","conditioned","on","the","corresponding","timestep",".","This","dimension","size","should","always","match","num_steps","and","is","the","second-to-last","batch","axis","in","the","batch","dimensions","(","just","to","the","left","of","the","dimension","for","the","number","of","states",")",".","mask",":","optional","bool-type","`","tensor","`","with","rightmost","dimension","matching","`","num_steps","`",",","indicating","which","observations","should","be","ignored","(","not","conditioned","on",")","for","posterior","inference","and","`","log_prob","`","evaluation",".","This","may","be","overridden","by","passing","the","`","mask","`","arg","to","individual","methods",".","When","the","mask","has","value","`","True","`",",","the","corresponding","observations","aren't","used",".","If","`","mask","`","is","`","None","`","then","all","of","the","observations","are","used",".","Default","value",":","`","None","`",".","name",":","Python","`","str","`","name","prefixed","to","Ops","created","by","this","class",".","Default","value",":","``","HiddenMarkovModel","''",".","Raises",":","ValueError",":","if","`","num_steps","`","is","not","at","least","1",".","ValueError",":","if","`","initial_distribution","`","does","not","have","scalar","`","event_shape","`",".","ValueError",":","if","`","transition_distribution","`","does","not","have","scalar","`","event_shape.","`","ValueError",":","if","`","transition_distribution","`","and","`","observation_distribution","`","are","fully","defined","but","do","n't","have","matching","rightmost","dimension","."]
code: def __init__(
      self,
      initial_distribution,
      transition_distribution,
      observation_distribution,
      num_steps,
      validate_args=False,
      allow_nan_stats=True,
      time_varying_transition_distribution=False,
      time_varying_observation_distribution=False,
      mask=None,
      name="HiddenMarkovModel",
  ):
      """Initialize hidden Markov model.
  
      Args:
        initial_distribution: A `Categorical`-like instance.
          Determines probability of first hidden state in Markov chain.
          The number of categories must match the number of categories of
          `transition_distribution` as well as both the rightmost batch
          dimension of `transition_distribution` and the rightmost batch
          dimension of `observation_distribution`.
        transition_distribution: A `Categorical`-like instance.
          The rightmost batch dimension indexes the probability distribution
          of each hidden state conditioned on the previous hidden state.
        observation_distribution: A `tfp.distributions.Distribution`-like
          instance.  The rightmost batch dimension indexes the distribution
          of each observation conditioned on the corresponding hidden state.
        num_steps: The number of steps taken in Markov chain. An integer valued
          tensor. The number of transitions is `num_steps - 1`.
        validate_args: Python `bool`, default `False`. When `True` distribution
          parameters are checked for validity despite possibly degrading runtime
          performance. When `False` invalid inputs may silently render incorrect
          outputs.
          Default value: `False`.
        allow_nan_stats: Python `bool`, default `True`. When `True`, statistics
          (e.g., mean, mode, variance) use the value "`NaN`" to indicate the
          result is undefined. When `False`, an exception is raised if one or
          more of the statistic's batch members are undefined.
          Default value: `True`.
        time_varying_transition_distribution: Python `bool`, default `False`.
          When `True`, the transition_distribution has an additional batch
          dimension that indexes the distribution of each observation conditioned
          on the corresponding timestep. This dimension size should always match
          `num_steps -1` and is the second-to-last batch axis in the batch
          dimensions (just to the left of the dimension for the number of states).
          Because transitions only happen between steps, the number of transitions
          is one less than num_steps.
        time_varying_observation_distribution: Python `bool`, default `False`.
          When `True`, the observation_distribution has an additional batch
          dimension that indexes the distribution of each observation conditioned
          on the corresponding timestep. This dimension size should always match
          num_steps and is the second-to-last batch axis in the batch dimensions
          (just to the left of the dimension for the number of states).
        mask: optional bool-type `tensor` with rightmost dimension matching
          `num_steps`, indicating which observations should be ignored
          (not conditioned on) for posterior inference and `log_prob` evaluation.
          This may be overridden by passing the `mask` arg to individual methods.
          When the mask has value `True`, the corresponding observations aren't
          used. If `mask` is `None` then all of the observations are used.
          Default value: `None`.
        name: Python `str` name prefixed to Ops created by this class.
          Default value: "HiddenMarkovModel".
  
      Raises:
        ValueError: if `num_steps` is not at least 1.
        ValueError: if `initial_distribution` does not have scalar `event_shape`.
        ValueError: if `transition_distribution` does not have scalar
          `event_shape.`
        ValueError: if `transition_distribution` and `observation_distribution`
          are fully defined but don't have matching rightmost dimension.
      """
  
      parameters = dict(locals())
  
      # pylint: disable=protected-access
      with tf.name_scope(name) as name:
          self._num_steps = tensor_util.convert_nonref_to_tensor(
              num_steps, as_shape_tensor=True
          )
          self._initial_distribution = initial_distribution
          self._observation_distribution = observation_distribution
          self._transition_distribution = transition_distribution
          self._time_varying_observation_distribution = (
              time_varying_observation_distribution
          )
          self._time_varying_transition_distribution = (
              time_varying_transition_distribution
          )
          self._mask = tensor_util.convert_nonref_to_tensor(
              mask, dtype_hint=tf.bool, name="mask"
          )
  
          num_steps_ = tf.get_static_value(num_steps)
          if num_steps_ is not None:
              if np.ndim(num_steps_) != 0:
                  raise ValueError(
                      "`num_steps` must be a scalar but it has rank {}".format(
                          np.ndim(num_steps_)
                      )
                  )
              else:
                  self._static_event_shape = tf.TensorShape(
                      [num_steps_]
                  ).concatenate(
                      self._observation_distribution.event_shape
                  )
          else:
              self._static_event_shape = tf.TensorShape(
                  [None]
              ).concatenate(self._observation_distribution.event_shape)
  
          observation_batch_shape = (
              self._observation_distribution.batch_shape[:-2]
              if self._time_varying_observation_distribution
              else self._observation_distribution.batch_shape[:-1]
          )
          self._static_batch_shape = tf.broadcast_static_shape(
              self._initial_distribution.batch_shape,
              tf.broadcast_static_shape(
                  self._transition_distribution.batch_shape[:-2]
                  if self._time_varying_transition_distribution
                  else self._transition_distribution.batch_shape[:-1],
                  observation_batch_shape,
              ),
          )
  
          # pylint: disable=protected-access
          super(HiddenMarkovModel, self).__init__(
              dtype=self._observation_distribution.dtype,
              reparameterization_type=reparameterization.NOT_REPARAMETERIZED,
              validate_args=validate_args,
              allow_nan_stats=allow_nan_stats,
              parameters=parameters,
              name=name,
          )
          # pylint: enable=protected-access
  
          self._parameters = parameters
  
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 1 to create a new HiddenMarkovModel object from inherited base classes: distribution with example: obj = HiddenMarkovModel(initial_distribution, transition_distribution, observation_distribution, num_steps, validate_args, allow_nan_stats, time_varying_transition_distribution, time_varying_observation_distribution, mask, name)