A state space model (SSM) posits a set of latent (unobserved) variables that
evolve over time with dynamics specified by a probabilistic transition model
p(z[t+1] | z[t]). At each timestep, we observe a value sampled from an
observation model conditioned on the current state, p(x[t] | z[t]). The
special case where both the transition and observation models are Gaussians
with mean specified as a linear function of the inputs, is known as a linear
Gaussian state space model and supports tractable exact probabilistic
calculations; see tfd_linear_gaussian_state_space_model for
details.
sts_seasonal_state_space_model(
num_timesteps,
num_seasons,
drift_scale,
initial_state_prior,
observation_noise_scale = 0,
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.
A seasonal effect model is a special case of a linear Gaussian SSM. The latent states represent an unknown effect from each of several 'seasons'; these are generally not meteorological seasons, but represent regular recurring patterns such as hour-of-day or day-of-week effects. The effect of each season drifts from one occurrence to the next, following a Gaussian random walk:
effects[season, occurrence[i]] = (effects[season, occurrence[i-1]] + Normal(loc=0., scale=drift_scale))
The latent state has dimension num_seasons, containing one effect for each
seasonal component. The parameters drift_scale and
observation_noise_scale are each (a batch of) scalars. The batch shape of
this Distribution is the broadcast batch shape of these parameters and of
the initial_state_prior.
Note: there is no requirement that the effects sum to zero.
Mathematical Details
The seasonal effect model implements a tfd_linear_gaussian_state_space_model with
latent_size = num_seasons and observation_size = 1. The latent state
is organized so that the current seasonal effect is always in the first
(zeroth) dimension. The transition model rotates the latent state to shift
to a new effect at the end of each season:
transition_matrix[t] = (permutation_matrix([1, 2, ..., num_seasons-1, 0])
if season_is_changing(t)
else eye(num_seasons)
transition_noise[t] ~ Normal(loc=0., scale_diag=(
[drift_scale, 0, ..., 0]
if season_is_changing(t)
else [0, 0, ..., 0]))
where season_is_changing(t) is True if t `mod` sum(num_steps_per_season) is in
the set of final days for each season, given by cumsum(num_steps_per_season) - 1.
The observation model always picks out the effect for the current season, i.e.,
the first element of the latent state:
observation_matrix = [[1., 0., ..., 0.]] observation_noise ~ Normal(loc=0, scale=observation_noise_scale)
Other sts:
sts_additive_state_space_model(),
sts_autoregressive_state_space_model(),
sts_autoregressive(),
sts_constrained_seasonal_state_space_model(),
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(),
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()