Seasonal state space model with effects constrained to sum to zero.

  observation_noise_scale = 1e-04,
  num_steps_per_season = 1,
  initial_step = 0,
  validate_args = FALSE,
  allow_nan_stats = TRUE,
  name = NULL



Scalar integer tensor number of timesteps to model with this distribution.


Scalar integer number of seasons.


Scalar (any additional dimensions are treated as batch dimensions) float tensor indicating the standard deviation of the change in effect between consecutive occurrences of a given season. This is assumed to be the same for all seasons.


instance of tfd_multivariate_normal representing the prior distribution on latent states; must have event shape [num_seasons].


Scalar (any additional dimensions are treated as batch dimensions) float tensor indicating the standard deviation of the observation noise.


integer number of steps in each season. This may be either a scalar (shape []), in which case all seasons have the same length, or an array of shape [num_seasons], in which seasons have different length, but remain constant around different cycles, or an array of shape [num_cycles, num_seasons], in which num_steps_per_season for each season also varies in different cycle (e.g., a 4 years cycle with leap day). Default value: 1.


Optional scalar integer tensor specifying the starting timestep. Default value: 0.


logical. Whether to validate input with asserts. If validate_args is FALSE, and the inputs are invalid, correct behavior is not guaranteed. Default value: FALSE.


logical. If FALSE, raise an exception if a statistic (e.g. mean/mode/etc...) is undefined for any batch member. If TRUE, batch members with valid parameters leading to undefined statistics will return NaN for this statistic. Default value: TRUE.


string prefixed to ops created by this class. Default value: "SeasonalStateSpaceModel".


an instance of LinearGaussianStateSpaceModel.

See also


Mathematical details

The constrained model implements a reparameterization of the naive SeasonalStateSpaceModel. Instead of directly representing the seasonal effects in the latent space, the latent space of the constrained model represents the difference between each effect and the mean effect. The following discussion assumes familiarity with the mathematical details of SeasonalStateSpaceModel.

Reparameterization and constraints: let the seasonal effects at a given timestep be E = [e_1, ..., e_N]. The difference between each effect e_i and the mean effect is z_i = e_i - sum_i(e_i)/N. By itself, this transformation is not invertible because recovering the absolute effects requires that we know the mean as well. To fix this, we'll define z_N = sum_i(e_i)/N as the mean effect. It's easy to see that this is invertible: given the mean effect and the differences of the first N - 1 effects from the mean, it's easy to solve for all N effects. Formally, we've defined the invertible linear reparameterization Z = R E, where

R = [1 - 1/N, -1/N,    ..., -1/N
     -1/N,    1 - 1/N, ..., -1/N,
     1/N,     1/N,     ...,  1/N]

represents the change of basis from 'effect coordinates' E to 'residual coordinates' Z. The Zs form the latent space of the ConstrainedSeasonalStateSpaceModel. To constrain the mean effect z_N to zero, we fix the prior to zero, p(z_N) ~ N(0., 0), and after the transition at each timestep we project z_N back to zero. Note that this projection is linear: to set the Nth dimension to zero, we simply multiply by the identity matrix with a missing element in the bottom right, i.e., Z_constrained = P Z, where P = eye(N) - scatter((N-1, N-1), 1).

Model: concretely, suppose a naive seasonal effect model has initial state prior N(m, S), transition matrix F and noise covariance Q, and observation matrix H. Then the corresponding constrained seasonal effect model has initial state prior N(P R m, P R S R' P'), transition matrix P R F R^-1 and noise covariance F R Q R' F', and observation matrix H R^-1, where the change-of-basis matrix R and constraint projection matrix P are as defined above. This follows directly from applying the reparameterization Z = R E, and then enforcing the zero-sum constraint on the prior and transition noise covariances. In practice, because the sum of effects z_N is constrained to be zero, it will never contribute a term to any linear operation on the latent space, so we can drop that dimension from the model entirely. ConstrainedSeasonalStateSpaceModel does this, so that it implements the N - 1 dimension latent space z_1, ..., z_[N-1]. Note that since we constrained the mean effect to be zero, the latent z_i's now recover their interpretation as the actual effects, z_i = e_i for i = 1, ..., N - 1, even though they were originally defined as residuals. The Nth effect is represented only implicitly, as the nonzero mean of the first N - 1effects. Although the computational represention is not symmetric across allNeffects, we derived theConstrainedSeasonalStateSpaceModelby starting with a symmetric representation and imposing only a symmetric constraint (the zero-sum constraint), so the probability model remains symmetric over allN` seasonal effects.

Other sts: sts_additive_state_space_model(), sts_autoregressive_state_space_model(), sts_autoregressive(), sts_dynamic_linear_regression_state_space_model(), sts_dynamic_linear_regression(), sts_linear_regression(), sts_local_level_state_space_model(), sts_local_level(), sts_local_linear_trend_state_space_model(), sts_local_linear_trend(), sts_seasonal_state_space_model(), sts_seasonal(), sts_semi_local_linear_trend_state_space_model(), sts_semi_local_linear_trend(), sts_smooth_seasonal_state_space_model(), sts_smooth_seasonal(), sts_sparse_linear_regression(), sts_sum()