class_docstr: Formal representation of a smooth seasonal effect model.
  
  The smooth seasonal model uses a set of trigonometric terms in order to
  capture a recurring pattern whereby adjacent (in time) effects are
  similar. The model uses `frequencies` calculated via:
  
  ```python
  frequencies[j] = 2. * pi * frequency_multipliers[j] / period
  ```
  
  and then posits two latent states for each `frequency`. The two latent states
  associated with frequency `j` drift over time via:
  
  ```python
  effect[t] = (effect[t - 1] * cos(frequencies[j]) +
               auxiliary[t - 1] * sin(frequencies[j]) +
               Normal(0., drift_scale))
  
  auxiliary[t] = (-effect[t - 1] * sin(frequencies[j]) +
                  auxiliary[t - 1] * cos(frequencies[j]) +
                  Normal(0., drift_scale))
  ```
  
  where `effect` is the smooth seasonal effect and `auxiliary` only appears as a
  matter of construction. The interpretation of `auxiliary` is thus not
  particularly important.
  
  #### Examples
  
  A smooth seasonal effect model representing smooth weekly seasonality on daily
  data:
  
  ```python
  component = SmoothSeasonal(
      period=7,
      frequency_multipliers=[1, 2, 3],
      initial_state_prior=tfd.MultivariateNormalDiag(scale_diag=tf.ones([6])),
  )
  ```
class_docstr_tok: ["Formal","representation","of","a","smooth","seasonal","effect","model",".","The","smooth","seasonal","model","uses","a","set","of","trigonometric","terms","in","order","to","capture","a","recurring","pattern","whereby","adjacent","(","in","time",")","effects","are","similar",".","The","model","uses","`","frequencies","`","calculated","via",":","``","`","python","frequencies","[","j","]","=","2",".","*","pi","*","frequency_multipliers","[","j","]","\/","period","``","`","and","then","posits","two","latent","states","for","each","`","frequency","`",".","The","two","latent","states","associated","with","frequency","`","j","`","drift","over","time","via",":","``","`","python","effect","[","t","]","=","(","effect","[","t","-","1","]","*","cos","(","frequencies","[","j","]",")","+","auxiliary","[","t","-","1","]","*","sin","(","frequencies","[","j","]",")","+","Normal","(","0.",",","drift_scale",")",")","auxiliary","[","t","]","=","(","-effect","[","t","-","1","]","*","sin","(","frequencies","[","j","]",")","+","auxiliary","[","t","-","1","]","*","cos","(","frequencies","[","j","]",")","+","Normal","(","0.",",","drift_scale",")",")","``","`","where","`","effect","`","is","the","smooth","seasonal","effect","and","`","auxiliary","`","only","appears","as","a","matter","of","construction",".","The","interpretation","of","`","auxiliary","`","is","thus","not","particularly","important",".","#","#","#","#","Examples","A","smooth","seasonal","effect","model","representing","smooth","weekly","seasonality","on","daily","data",":","``","`","python","component","=","SmoothSeasonal","(","period=7",",","frequency_multipliers=","[","1",",","2",",","3","]",",","initial_state_prior=tfd.MultivariateNormalDiag","(","scale_diag=tf.ones","(","[","6","]",")",")",",",")","``","`"]
docstr: Specify a smooth seasonal effects model.
  
  Args:
    period: positive scalar `float` `Tensor` giving the number of timesteps
      required for the longest cyclic effect to repeat.
    frequency_multipliers: One-dimensional `float` `Tensor` listing the
      frequencies (cyclic components) included in the model, as multipliers of
      the base/fundamental frequency `2. * pi / period`. Each component is
      specified by the number of times it repeats per period, and adds two
      latent dimensions to the model. A smooth seasonal model that can
      represent any periodic function is given by `frequency_multipliers = [1,
      2, ..., floor(period / 2)]`. However, it is often desirable to enforce a
      smoothness assumption (and reduce the computational burden) by dropping
      some of the higher frequencies.
    allow_drift: optional Python `bool` specifying whether the seasonal
      effects can drift over time.  Setting this to `False`
      removes the `drift_scale` parameter from the model. This is
      mathematically equivalent to
      `drift_scale_prior = tfd.Deterministic(0.)`, but removing drift
      directly is preferred because it avoids the use of a degenerate prior.
      Default value: `True`.
    drift_scale_prior: optional `tfd.Distribution` instance specifying a prior
      on the `drift_scale` parameter. If `None`, a heuristic default prior is
      constructed based on the provided `observed_time_series`.
      Default value: `None`.
    initial_state_prior: instance of `tfd.MultivariateNormal` representing
      the prior distribution on the latent states. Must have event shape
      `[2 * len(frequency_multipliers)]`. If `None`, a heuristic default prior
      is constructed based on the provided `observed_time_series`.
    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: 'SmoothSeasonal'.
docstr_tok: ["Specify","a","smooth","seasonal","effects","model",".","Args",":","period",":","positive","scalar","`","float","`","`","Tensor","`","giving","the","number","of","timesteps","required","for","the","longest","cyclic","effect","to","repeat",".","frequency_multipliers",":","One-dimensional","`","float","`","`","Tensor","`","listing","the","frequencies","(","cyclic","components",")","included","in","the","model",",","as","multipliers","of","the","base\/fundamental","frequency","`","2",".","*","pi","\/","period","`",".","Each","component","is","specified","by","the","number","of","times","it","repeats","per","period",",","and","adds","two","latent","dimensions","to","the","model",".","A","smooth","seasonal","model","that","can","represent","any","periodic","function","is","given","by","`","frequency_multipliers","=","[","1",",","2",",","...",",","floor","(","period","\/","2",")","]","`",".","However",",","it","is","often","desirable","to","enforce","a","smoothness","assumption","(","and","reduce","the","computational","burden",")","by","dropping","some","of","the","higher","frequencies",".","allow_drift",":","optional","Python","`","bool","`","specifying","whether","the","seasonal","effects","can","drift","over","time",".","Setting","this","to","`","False","`","removes","the","`","drift_scale","`","parameter","from","the","model",".","This","is","mathematically","equivalent","to","`","drift_scale_prior","=","tfd.Deterministic","(","0",".",")","`",",","but","removing","drift","directly","is","preferred","because","it","avoids","the","use","of","a","degenerate","prior",".","Default","value",":","`","True","`",".","drift_scale_prior",":","optional","`","tfd.Distribution","`","instance","specifying","a","prior","on","the","`","drift_scale","`","parameter",".","If","`","None","`",",","a","heuristic","default","prior","is","constructed","based","on","the","provided","`","observed_time_series","`",".","Default","value",":","`","None","`",".","initial_state_prior",":","instance","of","`","tfd.MultivariateNormal","`","representing","the","prior","distribution","on","the","latent","states",".","Must","have","event","shape","`","[","2","*","len","(","frequency_multipliers",")","]","`",".","If","`","None","`",",","a","heuristic","default","prior","is","constructed","based","on","the","provided","`","observed_time_series","`",".","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",":","'SmoothSeasonal","'","."]
code: def __init__(
      self,
      period,
      frequency_multipliers,
      allow_drift=True,
      drift_scale_prior=None,
      initial_state_prior=None,
      observed_time_series=None,
      name=None,
  ):
      """Specify a smooth seasonal effects model.
  
      Args:
        period: positive scalar `float` `Tensor` giving the number of timesteps
          required for the longest cyclic effect to repeat.
        frequency_multipliers: One-dimensional `float` `Tensor` listing the
          frequencies (cyclic components) included in the model, as multipliers of
          the base/fundamental frequency `2. * pi / period`. Each component is
          specified by the number of times it repeats per period, and adds two
          latent dimensions to the model. A smooth seasonal model that can
          represent any periodic function is given by `frequency_multipliers = [1,
          2, ..., floor(period / 2)]`. However, it is often desirable to enforce a
          smoothness assumption (and reduce the computational burden) by dropping
          some of the higher frequencies.
        allow_drift: optional Python `bool` specifying whether the seasonal
          effects can drift over time.  Setting this to `False`
          removes the `drift_scale` parameter from the model. This is
          mathematically equivalent to
          `drift_scale_prior = tfd.Deterministic(0.)`, but removing drift
          directly is preferred because it avoids the use of a degenerate prior.
          Default value: `True`.
        drift_scale_prior: optional `tfd.Distribution` instance specifying a prior
          on the `drift_scale` parameter. If `None`, a heuristic default prior is
          constructed based on the provided `observed_time_series`.
          Default value: `None`.
        initial_state_prior: instance of `tfd.MultivariateNormal` representing
          the prior distribution on the latent states. Must have event shape
          `[2 * len(frequency_multipliers)]`. If `None`, a heuristic default prior
          is constructed based on the provided `observed_time_series`.
        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: 'SmoothSeasonal'.
  
      """
      init_parameters = dict(locals())
      with tf.name_scope(name or "SmoothSeasonal") as name:
          _, observed_stddev, observed_initial = (
              sts_util.empirical_statistics(observed_time_series)
              if observed_time_series is not None
              else (0.0, 1.0, 0.0)
          )
  
          latent_size = 2 * static_num_frequencies(
              frequency_multipliers
          )
  
          # Heuristic default priors. Overriding these may dramatically
          # change inference performance and results.
          if drift_scale_prior is None:
              drift_scale_prior = lognormal.LogNormal(
                  loc=tf.math.log(0.01 * observed_stddev), scale=3.0
              )
  
          if initial_state_prior is None:
              initial_state_scale = (
                  tf.abs(observed_initial) + observed_stddev
              )[..., tf.newaxis]
              ones = tf.ones(
                  [latent_size], dtype=drift_scale_prior.dtype
              )
              initial_state_prior = mvn_diag.MultivariateNormalDiag(
                  scale_diag=initial_state_scale * ones
              )
  
          dtype = dtype_util.common_dtype(
              [drift_scale_prior, initial_state_prior]
          )
  
          self._initial_state_prior = initial_state_prior
          self._period = period
          self._frequency_multipliers = frequency_multipliers
  
          parameters = []
          if allow_drift:
              parameters.append(
                  Parameter(
                      "drift_scale",
                      drift_scale_prior,
                      chain.Chain(
                          [
                              scale.Scale(scale=observed_stddev),
                              softplus.Softplus(
                                  low=dtype_util.eps(dtype)
                              ),
                          ]
                      ),
                  )
              )
          self._allow_drift = allow_drift
  
          super(SmoothSeasonal, self).__init__(
              parameters=parameters,
              latent_size=latent_size,
              init_parameters=init_parameters,
              name=name,
          )
  
imports: import numpy
  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.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 dtype_util
  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 SmoothSeasonal object from inherited base classes: StructuralTimeSeries with example: obj = SmoothSeasonal(period, frequency_multipliers, allow_drift, drift_scale_prior, initial_state_prior, observed_time_series, name)