LevelTrend

class pymc_extras.statespace.models.structural.LevelTrend(order: int | list[int] = 2, innovations_order: int | list[int] | None = None, name: str = 'level_trend', observed_state_names: list[str] | None = None, share_states: bool = False)

Level and trend component of a structural time series model

Parameters:

• order (int) – Number of time derivatives of the trend to include in the model. For example, when order=3, the trend will be of the form y = a + b * t + c * t ** 2, where the coefficients a, b, c come from the initial state values.

• innovations_order (int or sequence of int, optional) – The number of stochastic innovations to include in the model. By default, innovations_order = order

• name (str, default "level_trend") – A name for this level-trend component. Used to label dimensions and coordinates.

• 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

This class implements the level and trend components of the general structural time series model. In the most general form, the level and trend is described by a system of two time-varying equations.

\[\begin{split}\begin{align} \mu_{t+1} &= \mu_t + \nu_t + \zeta_t \\ \nu_{t+1} &= \nu_t + \xi_t \zeta_t &\sim N(0, \sigma_\zeta) \\ \xi_t &\sim N(0, \sigma_\xi) \end{align}\end{split}\]

Where \(\mu_{t+1}\) is the mean of the timeseries at time t, and \(\nu_t\) is the drift or the slope of the process. When both innovations \(\zeta_t\) and \(\xi_t\) are included in the model, it is known as a local linear trend model. This system of two equations, corresponding to order=2, can be expanded or contracted by adding or removing equations. order=3 would add an acceleration term to the sytsem:

\[\begin{split}\begin{align} \mu_{t+1} &= \mu_t + \nu_t + \zeta_t \\ \nu_{t+1} &= \nu_t + \eta_t + \xi_t \\ \eta_{t+1} &= \eta_{t-1} + \omega_t \\ \zeta_t &\sim N(0, \sigma_\zeta) \\ \xi_t &\sim N(0, \sigma_\xi) \\ \omega_t &\sim N(0, \sigma_\omega) \end{align}\end{split}\]

After setting all innovation terms to zero and defining initial states \(\mu_0, \nu_0, \eta_0\), these equations can be collapsed to:

\[\mu_t = \mu_0 + \nu_0 \cdot t + \eta_0 \cdot t^2\]

Which clarifies how the order and initial states influence the model. In particular, the initial states are the coefficients on the intercept, slope, acceleration, and so on.

In this light, allowing for innovations can be understood as allowing these coefficients to vary over time. Each component can be individually selected for time variation by passing a list to the innovations_order argument. For example, a constant intercept with time varying trend and acceleration is specified as order=3, innovations_order=[0, 1, 1].

By choosing the order and innovations_order, a large variety of models can be obtained. Notable models include:

• Constant intercept, order=1, innovations_order=0

\[\mu_t = \mu\]

• Constant linear slope, order=2, innovations_order=0

\[\mu_t = \mu_{t-1} + \nu\]

• Gaussian Random Walk, order=1, innovations_order=1

\[\mu_t = \mu_{t-1} + \zeta_t\]

• Gaussian Random Walk with Drift, order=2, innovations_order=1

\[\mu_t = \mu_{t-1} + \nu + \zeta_t\]

• Smooth Trend, order=2, innovations_order=[0, 1]

\[\begin{split}\begin{align} \mu_t &= \mu_{t-1} + \nu_{t-1} \\ \nu_t &= \nu_{t-1} + \xi_t \end{align}\end{split}\]

• Local Level, order=2, innovations_order=2

[1] notes that the smooth trend model produces more gradually changing slopes than the full local linear trend model, and is equivalent to an “integrated trend model”.

References

[1]

Durbin, James, and Siem Jan Koopman. 2012. Time Series Analysis by State Space Methods: Second Edition. Oxford University Press.

__init__(order: int | list[int] = 2, innovations_order: int | list[int] | None = None, name: str = 'level_trend', observed_state_names: list[str] | None = None, share_states: bool = False)

Methods

__init__([order, innovations_order, 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