<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/sts/components/smooth_seasonal.py#L312-L486) |

Formal representation of a smooth seasonal effect model.

Inherits From: [`StructuralTimeSeries`](https://www.tensorflow.org/probability/api_docs/python/tfp/sts/StructuralTimeSeries)

    tfp.sts.SmoothSeasonal(
        period,
        frequency_multipliers,
        allow_drift=True,
        drift_scale_prior=None,
        initial_state_prior=None,
        observed_time_series=None,
        name=None
    )

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:

    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:

    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:

    component = SmoothSeasonal(
        period=7,
        frequency_multipliers=[1, 2, 3],
        initial_state_prior=tfd.MultivariateNormalDiag(scale_diag=tf.ones([6])),
    )

<br />

<br />

<br />

| ## 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`](https://www.tensorflow.org/probability/api_docs/python/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'. |

<br />

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `allow_drift` | Whether the seasonal effects are allowed to drift over time. |
| `batch_shape` | Static batch shape of models represented by this component. |
| `frequency_multipliers` | Multipliers of the fundamental frequency. |
| `init_parameters` | Parameters used to instantiate this `StructuralTimeSeries`. |
| `initial_state_prior` | Prior distribution on the initial latent states. |
| `latent_size` | Python `int` dimensionality of the latent space in this model. |
| `name` | Name of this model component. |
| `parameters` | List of Parameter(name, prior, bijector) namedtuples for this model. |
| `period` | The seasonal period. |

<br />

## Methods

### `batch_shape_tensor`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/sts/structural_time_series.py#L121-L134)

    batch_shape_tensor()

Runtime batch shape of models represented by this component.

<br />

<br />

<br />

| Returns ||
|---|---|
| `batch_shape` | `int` `Tensor` giving the broadcast batch shape of all model parameters. This should match the batch shape of derived state space models, i.e., `self.make_state_space_model(...).batch_shape_tensor()`. |

<br />

### `copy`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/sts/structural_time_series.py#L179-L194)

    copy(
        **override_parameters_kwargs
    )

Creates a deep copy.

> [!NOTE]
> **Note:** the copy distribution may continue to depend on the original initialization arguments.

<br />

<br />

<br />

| Args ||
|---|---|
| `**override_parameters_kwargs` | String/value dictionary of initialization arguments to override with new values. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `copy` | A new instance of `type(self)` initialized from the union of self.init_parameters and override_parameters_kwargs, i.e., `dict(self.init_parameters, **override_parameters_kwargs)`. |

<br />

### `get_parameter`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/sts/structural_time_series.py#L86-L92)

    get_parameter(
        parameter_name
    )

Returns the parameter with the given name, or a KeyError.

### `joint_distribution`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/sts/structural_time_series.py#L263-L406)

    joint_distribution(
        observed_time_series=None,
        num_timesteps=None,
        trajectories_shape=(),
        initial_step=0,
        mask=None,
        experimental_parallelize=False
    )

Constructs the joint distribution over parameters and observed values.

<br />

<br />

<br />

| Args ||
|---|---|
| `observed_time_series` | Optional observed time series to model, as a `Tensor` or [`tfp.sts.MaskedTimeSeries`](https://www.tensorflow.org/probability/api_docs/python/tfp/sts/MaskedTimeSeries) instance having shape `concat([batch_shape, trajectories_shape, num_timesteps, 1])`. If an observed time series is provided, the `num_timesteps`, `trajectories_shape`, and `mask` arguments are ignored, and an unnormalized (pinned) distribution over parameter values is returned. Default value: `None`. |
| `num_timesteps` | scalar `int` `Tensor` number of timesteps to model. This must be specified either directly or by passing an `observed_time_series`. Default value: `0`. |
| `trajectories_shape` | `int` `Tensor` shape of sampled trajectories for each set of parameter values. Ignored if an `observed_time_series` is passed. Default value: `()`. |
| `initial_step` | Optional scalar `int` `Tensor` specifying the starting timestep. Default value: `0`. |
| `mask` | Optional `bool` `Tensor` having shape `concat([batch_shape, trajectories_shape, num_timesteps])`, in which `True` entries indicate that the series value at the corresponding step is missing and should be ignored. This argument should be passed only if `observed_time_series` is not specified or does not already contain a missingness mask; it is an error to pass both this argument and an `observed_time_series` value containing a missingness mask. Default value: `None`. |
| `experimental_parallelize` | If `True`, use parallel message passing algorithms from [`tfp.experimental.parallel_filter`](https://www.tensorflow.org/probability/api_docs/python/tfp/experimental/parallel_filter) to perform time series operations in `O(log num_timesteps)` sequential steps. The overall FLOP and memory cost may be larger than for the sequential implementations by a constant factor. Default value: `False`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `joint_distribution` | joint distribution of model parameters and observed trajectories. If no `observed_time_series` was specified, this is an instance of `tfd.JointDistributionNamedAutoBatched` with a random variable for each model parameter (with names and order matching `self.parameters`), plus a final random variable `observed_time_series` representing a trajectory(ies) conditioned on the parameters. If `observed_time_series` was specified, the return value is given by `joint_distribution.experimental_pin( observed_time_series=observed_time_series)` where `joint_distribution` is as just described, so it defines an unnormalized posterior distribution over the parameters. |

<br />

#### Example:

The joint distribution can generate prior samples of parameters and
trajectories:

    from matplotlib import pylab as plt
    import tensorflow_probability as tfp

    # Sample and plot 100 trajectories from the prior.
    model = tfp.sts.LocalLinearTrend()
    prior_samples = model.joint_distribution(num_timesteps=200).sample([100])
    plt.plot(
      tf.linalg.matrix_transpose(prior_samples['observed_time_series'][..., 0]))

It also integrates with TFP inference APIs, providing a more flexible
alternative to the STS-specific fitting utilities.

    jd = model.joint_distribution(observed_time_series)

    # Variational inference.
    surrogate_posterior = (
      tfp.experimental.vi.build_factored_surrogate_posterior(
        event_shape=jd.event_shape,
        bijector=jd.experimental_default_event_space_bijector()))
    losses = tfp.vi.fit_surrogate_posterior(
      target_log_prob_fn=jd.unnormalized_log_prob,
      surrogate_posterior=surrogate_posterior,
      optimizer=tf_keras.optimizers.Adam(0.1),
      num_steps=200)
    parameter_samples = surrogate_posterior.sample(50)

    # No U-Turn Sampler.
    samples, kernel_results = tfp.experimental.mcmc.windowed_adaptive_nuts(
      n_draws=500, joint_dist=dist)

### `joint_log_prob`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/sts/structural_time_series.py#L454-L520)

    joint_log_prob(
        observed_time_series
    )

Build the joint density `log p(params) + log p(y|params)` as a callable. (deprecated)

> [!WARNING]
> **Deprecated:** THIS FUNCTION IS DEPRECATED. It will be removed after 2022-03-01. Instructions for updating: Please use [`StructuralTimeSeries.joint_distribution(observed_time_series).log_prob`](https://www.tensorflow.org/probability/api_docs/python/tfp/sts/StructuralTimeSeries#joint_distribution)

<br />

<br />

<br />

| Args ||
|---|---|
| `observed_time_series` | Observed `Tensor` trajectories of shape `sample_shape + batch_shape + [num_timesteps, 1]` (the trailing `1` dimension is optional if `num_timesteps > 1`), where `batch_shape` should match `self.batch_shape` (the broadcast batch shape of all priors on parameters for this structural time series model). Any `NaN`s are interpreted as missing observations; missingness may be also be explicitly specified by passing a [`tfp.sts.MaskedTimeSeries`](https://www.tensorflow.org/probability/api_docs/python/tfp/sts/MaskedTimeSeries) instance. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `log_joint_fn` | A function taking a `Tensor` argument for each model parameter, in canonical order, and returning a `Tensor` log probability of shape `batch_shape`. Note that, *unlike* `tfp.Distributions` `log_prob` methods, the `log_joint` sums over the `sample_shape` from y, so that `sample_shape` does not appear in the output log_prob. This corresponds to viewing multiple samples in `y` as iid observations from a single model, which is typically the desired behavior for parameter inference. |

<br />

### `make_state_space_model`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/sts/structural_time_series.py#L219-L248)

    make_state_space_model(
        num_timesteps,
        param_vals,
        initial_state_prior=None,
        initial_step=0,
        **linear_gaussian_ssm_kwargs
    )

Instantiate this model as a Distribution over specified `num_timesteps`.

<br />

<br />

<br />

| Args ||
|---|---|
| `num_timesteps` | Python `int` number of timesteps to model. |
| `param_vals` | a list of `Tensor` parameter values in order corresponding to `self.parameters`, or a dict mapping from parameter names to values. |
| `initial_state_prior` | an optional `Distribution` instance overriding the default prior on the model's initial state. This is used in forecasting ("today's prior is yesterday's posterior"). |
| `initial_step` | optional `int` specifying the initial timestep to model. This is relevant when the model contains time-varying components, e.g., holidays or seasonality. |
| `**linear_gaussian_ssm_kwargs` | Optional additional keyword arguments to to the base `tfd.LinearGaussianStateSpaceModel` constructor. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `dist` | a `LinearGaussianStateSpaceModel` Distribution object. |

<br />

### `prior_sample`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/sts/structural_time_series.py#L408-L452)

    prior_sample(
        num_timesteps,
        initial_step=0,
        params_sample_shape=(),
        trajectories_sample_shape=(),
        seed=None
    )

Sample from the joint prior over model parameters and trajectories. (deprecated)

> [!WARNING]
> **Deprecated:** THIS FUNCTION IS DEPRECATED. It will be removed after 2022-03-01. Instructions for updating: Please use `StructuralTimeSeries.joint_distribution(...).sample()`

<br />

<br />

<br />

| Args ||
|---|---|
| `num_timesteps` | Scalar `int` `Tensor` number of timesteps to model. |
| `initial_step` | Optional scalar `int` `Tensor` specifying the starting timestep. Default value: 0. |
| `params_sample_shape` | Number of possible worlds to sample iid from the parameter prior, or more generally, `Tensor` `int` shape to fill with iid samples. Default value: `[]` (i.e., draw a single sample and don't expand the shape). |
| `trajectories_sample_shape` | For each sampled set of parameters, number of trajectories to sample, or more generally, `Tensor` `int` shape to fill with iid samples. Default value: `[]` (i.e., draw a single sample and don't expand the shape). |
| `seed` | PRNG seed; see [`tfp.random.sanitize_seed`](https://www.tensorflow.org/probability/api_docs/python/tfp/random/sanitize_seed) for details. Default value: `None`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `trajectories` | `float` `Tensor` of shape `trajectories_sample_shape + params_sample_shape + [num_timesteps, 1]` containing all sampled trajectories. |
| `param_samples` | list of sampled parameter value `Tensor`s, in order corresponding to `self.parameters`, each of shape `params_sample_shape + prior.batch_shape + prior.event_shape`. |

<br />

### `__add__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/sts/structural_time_series.py#L136-L177)

    __add__(
        other
    )

Models the sum of the series from the two components.