class_docstr: Formal representation of an autoregressive model.
  
  An autoregressive (AR) model posits a latent `level` whose value at each step
  is a noisy linear combination of previous steps:
  
  ```python
  level[t+1] = (sum(coefficients * levels[t:t-order:-1]) +
                Normal(0., level_scale))
  ```
  
  The latent state is `levels[t:t-order:-1]`. We observe a noisy realization of
  the current level: `f[t] = level[t] + Normal(0., observation_noise_scale)` at
  each timestep.
  
  If `coefficients=[1.]`, the AR process is a simple random walk, equivalent to
  a `LocalLevel` model. However, a random walk's variance increases with time,
  while many AR processes (in particular, any first-order process with
  `abs(coefficient) < 1`) are *stationary*, i.e., they maintain a constant
  variance over time. This makes AR processes useful models of uncertainty.
  
  See the [Wikipedia article](
  https://en.wikipedia.org/wiki/Autoregressive_model#Definition) for details on
  stationarity and other mathematical properties of autoregressive processes.
class_docstr_tok: ["Formal","representation","of","an","autoregressive","model",".","An","autoregressive","(","AR",")","model","posits","a","latent","`","level","`","whose","value","at","each","step","is","a","noisy","linear","combination","of","previous","steps",":","``","`","python","level","[","t+1","]","=","(","sum","(","coefficients","*","levels","[","t",":","t-order",":","-1","]",")","+","Normal","(","0.",",","level_scale",")",")","``","`","The","latent","state","is","`","levels","[","t",":","t-order",":","-1","]","`",".","We","observe","a","noisy","realization","of","the","current","level",":","`","f","[","t","]","=","level","[","t","]","+","Normal","(","0.",",","observation_noise_scale",")","`","at","each","timestep",".","If","`","coefficients=","[","1",".","]","`",",","the","AR","process","is","a","simple","random","walk",",","equivalent","to","a","`","LocalLevel","`","model",".","However",",","a","random","walk","'s","variance","increases","with","time",",","while","many","AR","processes","(","in","particular",",","any","first-order","process","with","`","abs","(","coefficient",")","<","1","`",")","are","*","stationary","*",",","i.e.",",","they","maintain","a","constant","variance","over","time",".","This","makes","AR","processes","useful","models","of","uncertainty",".","See","the","[","Wikipedia","article","]","(","https",":","\/\/en.wikipedia.org\/wiki\/Autoregressive_model","#","Definition",")","for","details","on","stationarity","and","other","mathematical","properties","of","autoregressive","processes","."]
docstr: Specify an autoregressive model.
  
  Args:
    order: scalar Python positive `int` specifying the number of past
      timesteps to regress on.
    coefficients_prior: optional `tfd.Distribution` instance specifying a
      prior on the `coefficients` parameter. If `None`, a default standard
      normal (`tfd.MultivariateNormalDiag(scale_diag=tf.ones([order]))`) prior
      is used.
      Default value: `None`.
    level_scale_prior: optional `tfd.Distribution` instance specifying a prior
      on the `level_scale` parameter. If `None`, a heuristic default prior is
      constructed based on the provided `observed_time_series`.
      Default value: `None`.
    initial_state_prior: optional `tfd.Distribution` instance specifying a
      prior on the initial state, corresponding to the values of the process
      at a set of size `order` of imagined timesteps before the initial step.
      If `None`, a heuristic default prior is constructed based on the
      provided `observed_time_series`.
      Default value: `None`.
    coefficient_constraining_bijector: optional `tfb.Bijector` instance
      representing a constraining mapping for the autoregressive coefficients.
      For example, `tfb.Tanh()` constrains the coefficients to lie in
      `(-1, 1)`, while `tfb.Softplus()` constrains them to be positive, and
      `tfb.Identity()` implies no constraint. If `None`, the default behavior
      constrains the coefficients to lie in `(-1, 1)` using a `Tanh` bijector.
      Default value: `None`.
    observed_time_series: optional `float` `Tensor` of shape
      `batch_shape + [T, 1]` (omitting the trailing unit dimension is also
      supported when `T > 1`), specifying an observed time series. Any `NaN`s
      are interpreted as missing observations; missingness may be also be
      explicitly specified by passing a `tfp.sts.MaskedTimeSeries` instance.
      Any priors not explicitly set will be given default values according to
      the scale of the observed time series (or batch of time series).
      Default value: `None`.
    name: the name of this model component.
      Default value: 'Autoregressive'.
docstr_tok: ["Specify","an","autoregressive","model",".","Args",":","order",":","scalar","Python","positive","`","int","`","specifying","the","number","of","past","timesteps","to","regress","on",".","coefficients_prior",":","optional","`","tfd.Distribution","`","instance","specifying","a","prior","on","the","`","coefficients","`","parameter",".","If","`","None","`",",","a","default","standard","normal","(","`","tfd.MultivariateNormalDiag","(","scale_diag=tf.ones","(","[","order","]",")",")","`",")","prior","is","used",".","Default","value",":","`","None","`",".","level_scale_prior",":","optional","`","tfd.Distribution","`","instance","specifying","a","prior","on","the","`","level_scale","`","parameter",".","If","`","None","`",",","a","heuristic","default","prior","is","constructed","based","on","the","provided","`","observed_time_series","`",".","Default","value",":","`","None","`",".","initial_state_prior",":","optional","`","tfd.Distribution","`","instance","specifying","a","prior","on","the","initial","state",",","corresponding","to","the","values","of","the","process","at","a","set","of","size","`","order","`","of","imagined","timesteps","before","the","initial","step",".","If","`","None","`",",","a","heuristic","default","prior","is","constructed","based","on","the","provided","`","observed_time_series","`",".","Default","value",":","`","None","`",".","coefficient_constraining_bijector",":","optional","`","tfb.Bijector","`","instance","representing","a","constraining","mapping","for","the","autoregressive","coefficients",".","For","example",",","`","tfb.Tanh","(",")","`","constrains","the","coefficients","to","lie","in","`","(","-1",",","1",")","`",",","while","`","tfb.Softplus","(",")","`","constrains","them","to","be","positive",",","and","`","tfb.Identity","(",")","`","implies","no","constraint",".","If","`","None","`",",","the","default","behavior","constrains","the","coefficients","to","lie","in","`","(","-1",",","1",")","`","using","a","`","Tanh","`","bijector",".","Default","value",":","`","None","`",".","observed_time_series",":","optional","`","float","`","`","Tensor","`","of","shape","`","batch_shape","+","[","T",",","1","]","`","(","omitting","the","trailing","unit","dimension","is","also","supported","when","`","T",">","1","`",")",",","specifying","an","observed","time","series",".","Any","`","NaN","`","s","are","interpreted","as","missing","observations",";","missingness","may","be","also","be","explicitly","specified","by","passing","a","`","tfp.sts.MaskedTimeSeries","`","instance",".","Any","priors","not","explicitly","set","will","be","given","default","values","according","to","the","scale","of","the","observed","time","series","(","or","batch","of","time","series",")",".","Default","value",":","`","None","`",".","name",":","the","name","of","this","model","component",".","Default","value",":","'Autoregressive","'","."]
code: def __init__(
      self,
      order,
      coefficients_prior=None,
      level_scale_prior=None,
      initial_state_prior=None,
      coefficient_constraining_bijector=None,
      observed_time_series=None,
      name=None,
  ):
      """Specify an autoregressive model.
  
      Args:
        order: scalar Python positive `int` specifying the number of past
          timesteps to regress on.
        coefficients_prior: optional `tfd.Distribution` instance specifying a
          prior on the `coefficients` parameter. If `None`, a default standard
          normal (`tfd.MultivariateNormalDiag(scale_diag=tf.ones([order]))`) prior
          is used.
          Default value: `None`.
        level_scale_prior: optional `tfd.Distribution` instance specifying a prior
          on the `level_scale` parameter. If `None`, a heuristic default prior is
          constructed based on the provided `observed_time_series`.
          Default value: `None`.
        initial_state_prior: optional `tfd.Distribution` instance specifying a
          prior on the initial state, corresponding to the values of the process
          at a set of size `order` of imagined timesteps before the initial step.
          If `None`, a heuristic default prior is constructed based on the
          provided `observed_time_series`.
          Default value: `None`.
        coefficient_constraining_bijector: optional `tfb.Bijector` instance
          representing a constraining mapping for the autoregressive coefficients.
          For example, `tfb.Tanh()` constrains the coefficients to lie in
          `(-1, 1)`, while `tfb.Softplus()` constrains them to be positive, and
          `tfb.Identity()` implies no constraint. If `None`, the default behavior
          constrains the coefficients to lie in `(-1, 1)` using a `Tanh` bijector.
          Default value: `None`.
        observed_time_series: optional `float` `Tensor` of shape
          `batch_shape + [T, 1]` (omitting the trailing unit dimension is also
          supported when `T > 1`), specifying an observed time series. Any `NaN`s
          are interpreted as missing observations; missingness may be also be
          explicitly specified by passing a `tfp.sts.MaskedTimeSeries` instance.
          Any priors not explicitly set will be given default values according to
          the scale of the observed time series (or batch of time series).
          Default value: `None`.
        name: the name of this model component.
          Default value: 'Autoregressive'.
      """
      init_parameters = dict(locals())
      with tf.name_scope(name or "Autoregressive") as name:
          masked_time_series = None
          if observed_time_series is not None:
              masked_time_series = (
                  sts_util.canonicalize_observed_time_series_with_mask(
                      observed_time_series
                  )
              )
  
          dtype = dtype_util.common_dtype(
              [
                  (
                      masked_time_series.time_series
                      if masked_time_series is not None
                      else None
                  ),
                  coefficients_prior,
                  level_scale_prior,
                  initial_state_prior,
              ],
              dtype_hint=tf.float32,
          )
  
          if observed_time_series is not None:
              (
                  _,
                  observed_stddev,
                  observed_initial,
              ) = sts_util.empirical_statistics(masked_time_series)
          else:
              observed_stddev, observed_initial = (
                  tf.convert_to_tensor(value=1.0, dtype=dtype),
                  tf.convert_to_tensor(value=0.0, dtype=dtype),
              )
          batch_ones = tf.ones(
              ps.concat(
                  [ps.shape(observed_initial), [order]],  # Batch shape
                  axis=0,
              ),
              dtype=dtype,
          )
  
          # Heuristic default priors. Overriding these may dramatically
          # change inference performance and results.
          if coefficients_prior is None:
              coefficients_prior = mvn_diag.MultivariateNormalDiag(
                  scale_diag=batch_ones
              )
          if level_scale_prior is None:
              level_scale_prior = lognormal.LogNormal(
                  loc=tf.math.log(0.05 * observed_stddev), scale=3.0
              )
  
          if (
              coefficients_prior.event_shape.is_fully_defined()
              and order != coefficients_prior.event_shape[0]
          ):
              raise ValueError(
                  "Prior dimension {} doesn't match order {}.".format(
                      coefficients_prior.event_shape[0], order
                  )
              )
  
          if initial_state_prior is None:
              initial_state_prior = mvn_diag.MultivariateNormalDiag(
                  loc=observed_initial[..., tf.newaxis] * batch_ones,
                  scale_diag=(
                      tf.abs(observed_initial) + observed_stddev
                  )[..., tf.newaxis]
                  * batch_ones,
              )
  
          self._order = order
          self._coefficients_prior = coefficients_prior
          self._level_scale_prior = level_scale_prior
          self._initial_state_prior = initial_state_prior
  
          if coefficient_constraining_bijector is None:
              coefficient_constraining_bijector = tanh.Tanh()
          super(Autoregressive, self).__init__(
              parameters=[
                  Parameter(
                      "coefficients",
                      coefficients_prior,
                      coefficient_constraining_bijector,
                  ),
                  Parameter(
                      "level_scale",
                      level_scale_prior,
                      chain.Chain(
                          [
                              scale.Scale(scale=observed_stddev),
                              softplus.Softplus(
                                  low=dtype_util.eps(dtype)
                              ),
                          ]
                      ),
                  ),
              ],
              latent_size=order,
              init_parameters=init_parameters,
              name=name,
          )
  
imports: import tensorflow.compat.v2
  from tensorflow_probability.python.bijectors import chain
  from tensorflow_probability.python.bijectors import scale
  from tensorflow_probability.python.bijectors import softplus
  from tensorflow_probability.python.bijectors import tanh
  from tensorflow_probability.python.distributions import linear_gaussian_ssm
  from tensorflow_probability.python.distributions import lognormal
  from tensorflow_probability.python.distributions import mvn_diag
  from tensorflow_probability.python.internal import distribution_util
  from tensorflow_probability.python.internal import dtype_util
  from tensorflow_probability.python.internal import prefer_static
  from tensorflow_probability.python.sts.internal import util
  from tensorflow_probability.python.sts.structural_time_series import Parameter
  from tensorflow_probability.python.sts.structural_time_series import StructuralTimeSeries
label_desc: Use image node_id 1 to create a new Autoregressive object from inherited base classes: StructuralTimeSeries with example: obj = Autoregressive(order, coefficients_prior, level_scale_prior, initial_state_prior, coefficient_constraining_bijector, observed_time_series, name)