FrequencySeasonality

class pymc_extras.statespace.models.structural.FrequencySeasonality(season_length: int | float, n: int | None = None, name: str | None = None, innovations: bool = True, observed_state_names: Sequence[str] | None = None, share_states: bool = False)

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

• observed_state_names (list[str] | None, default None) – List of strings for observed state labels. If None, defaults to [“data”].

• share_states (bool, default False) – Whether latent states are shared across the observed states. If True, there will be only one set of latent states, which are observed by all observed states. If False, each observed state has its own set of latent states. This argument has no effect if k_endog is 1.

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, a FrequencySeasonality 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 choosing n << s // 2. Using TimeSeasonality, an annual seasonal pattern in daily data requires 364 states, whereas FrequencySeasonality always requires 2 * n states, regardless of the seasonal_length. The price of this compactness is less representational power. At n = 1, the seasonal pattern will be a pure sine wave. At n = 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.

__init__(season_length: int | float, n: int | None = None, name: str | None = None, innovations: bool = True, observed_state_names: Sequence[str] | None = None, share_states: bool = False)

Methods

__init__(season_length[, n, name, ...])
build([name, filter_type, verbose, mode])	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()
set_coords()	Set default coordinate specifications.
set_data_info()	Set default data specifications.
set_parameters()	Set component parameter specifications.
set_shocks()	Set default shock specifications based on the number of sources of innovations in the component.
set_states()	Set default state specification based on number of states and endogenous variables in the component.

Attributes

coords
data_names
exog_names
k_endog
k_posdef
k_states
n_timesteps
needs_exog_data
observed_state_names
param_dims
param_info
param_names
shock_names
state_names