FrequencySeasonality#
- class pymc_experimental.statespace.models.structural.FrequencySeasonality(season_length, n=None, name=None, innovations=True)[source]#
Seasonal component, modeled in the frequency domain
- Parameters:
season_length (float) – The number of periods in a single seasonal cycle, e.g. 12 for monthly data with annual seasonal pattern, 7 for daily data with weekly seasonal pattern, etc. Non-integer seasonal_length is also permitted, for example 365.2422 days in a (solar) year.
n (int) – Number of fourier features to include in the seasonal component. Default is
season_length // 2
, which is the maximum possible. A smaller number can be used for a more wave-like seasonal pattern.name (str, default None) – A name for this seasonal component. Used to label dimensions and coordinates. Useful when multiple seasonal components are included in the same model. Default is
f"Seasonal[s={season_length}, n={n}]"
innovations (bool, default True) – Whether to include stochastic innovations in the strength of the seasonal effect
Notes
A seasonal effect is any pattern that repeats every fixed interval. Although there are many possible ways to model seasonal effects, the implementation used here is the one described by [1] as the “canonical” frequency domain representation. The seasonal component can be expressed:
\[\begin{split}\begin{align} \gamma_t &= \sum_{j=1}^{2n} \gamma_{j,t} \\ \gamma_{j, t+1} &= \gamma_{j,t} \cos \lambda_j + \gamma_{j,t}^\star \sin \lambda_j + \omega_{j, t} \\ \gamma_{j, t}^\star &= -\gamma_{j,t} \sin \lambda_j + \gamma_{j,t}^\star \cos \lambda_j + \omega_{j,t}^\star \lambda_j &= \frac{2\pi j}{s} \end{align}\end{split}\]Where \(s\) is the
seasonal_length
.Unlike a
TimeSeasonality
component, aFrequencySeasonality
component does not require integer season length. In addition, for long seasonal periods, it is possible to obtain a more compact state space representation by choosingn << s // 2
. UsingTimeSeasonality
, an annual seasonal pattern in daily data requires 364 states, whereasFrequencySeasonality
always requires2 * n
states, regardless of theseasonal_length
. The price of this compactness is less representational power. Atn = 1
, the seasonal pattern will be a pure sine wave. Atn = s // 2
, any arbitrary pattern can be represented.One cost of the added flexibility of
FrequencySeasonality
is reduced interpretability. States of this model are coefficients \(\gamma_1, \gamma^\star_1, \gamma_2, \gamma_2^\star ..., \gamma_n, \gamma^\star_n\) associated with different frequencies in the fourier representation of the seasonal pattern. As a result, it is not possible to isolate and identify a “Monday” effect, for instance.Methods
__init__
(season_length[, n, name, innovations])build
([name, filter_type, verbose])Build a StructuralTimeSeries statespace model from the current component(s)
make_and_register_data
(name, shape[, dtype])Helper function to create a pytensor symbolic variable and register it in the _name_to_data dictionary
make_and_register_variable
(name, shape[, dtype])Helper function to create a pytensor symbolic variable and register it in the _name_to_variable dictionary
make_symbolic_graph
()populate_component_properties
()