pymc-extras 0.3.1__py3-none-any.whl → 0.4.1__py3-none-any.whl

pymc_extras/statespace/models/structural/components/cycle.py

@@ -0,0 +1,325 @@
+import numpy as np
+
+from pytensor import tensor as pt
+from pytensor.tensor.slinalg import block_diag
+
+from pymc_extras.statespace.models.structural.core import Component
+from pymc_extras.statespace.models.structural.utils import _frequency_transition_block
+
+
+class CycleComponent(Component):
+    r"""
+    A component for modeling longer-term cyclical effects
+
+    Supports both univariate and multivariate time series. For multivariate time series,
+    each endogenous variable gets its own independent cycle component with separate
+    cosine/sine states and optional variable-specific innovation variances.
+
+    Parameters
+    ----------
+    name: str
+        Name of the component. Used in generated coordinates and state names. If None, a descriptive name will be
+        used.
+
+    cycle_length: int, optional
+        The length of the cycle, in the calendar units of your data. For example, if your data is monthly, and you
+        want to model a 12-month cycle, use ``cycle_length=12``. You cannot specify both ``cycle_length`` and
+        ``estimate_cycle_length``.
+
+    estimate_cycle_length: bool, default False
+        Whether to estimate the cycle length. If True, an additional parameter, ``cycle_length`` will be added to the
+        model. You cannot specify both ``cycle_length`` and ``estimate_cycle_length``.
+
+    dampen: bool, default False
+        Whether to dampen the cycle by multiplying by a dampening factor :math:`\rho` at every timestep. If true,
+        an additional parameter, ``dampening_factor`` will be added to the model.
+
+    innovations: bool, default True
+        Whether to include stochastic innovations in the strength of the seasonal effect. If True, an additional
+        parameter, ``sigma_{name}`` will be added to the model.
+        For multivariate time series, this is a vector (variable-specific innovation variances).
+
+    observed_state_names: list[str], optional
+        Names of the observed state variables. For univariate time series, defaults to ``["data"]``.
+        For multivariate time series, specify a list of names for each endogenous variable.
+
+    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
+    -----
+    The cycle component is very similar in implementation to the frequency domain seasonal component, expect that it
+    is restricted to n=1. The cycle component can be expressed:
+
+    .. math::
+        \begin{align}
+            \gamma_t &= \rho \gamma_{t-1} \cos \lambda + \rho \gamma_{t-1}^\star \sin \lambda + \omega_{t} \\
+            \gamma_{t}^\star &= -\rho \gamma_{t-1} \sin \lambda + \rho \gamma_{t-1}^\star \cos \lambda + \omega_{t}^\star \\
+            \lambda &= \frac{2\pi}{s}
+        \end{align}
+
+    Where :math:`s` is the ``cycle_length``. [1] recommend that this component be used for longer term cyclical
+    effects, such as business cycles, and that the seasonal component be used for shorter term effects, such as
+    weekly or monthly seasonality.
+
+    Unlike a FrequencySeasonality component, the length of a CycleComponent can be estimated.
+
+    **Multivariate Support:**
+    For multivariate time series with k endogenous variables, the component creates:
+    - 2k states (cosine and sine components for each variable)
+    - Block diagonal transition and selection matrices
+    - Variable-specific innovation variances (optional)
+    - Proper parameter shapes: (k, 2) for initial states, (k,) for innovation variances
+
+    Examples
+    --------
+    **Univariate Example:**
+    Estimate a business cycle with length between 6 and 12 years:
+
+    .. code:: python
+
+        from pymc_extras.statespace import structural as st
+        import pymc as pm
+        import pytensor.tensor as pt
+        import pandas as pd
+        import numpy as np
+
+        data = np.random.normal(size=(100, 1))
+
+        # Build the structural model
+        grw = st.LevelTrendComponent(order=1, innovations_order=1)
+        cycle = st.CycleComponent(
+            "business_cycle", cycle_length=12, estimate_cycle_length=False, innovations=True, dampen=True
+        )
+        ss_mod = (grw + cycle).build()
+
+        # Estimate with PyMC
+        with pm.Model(coords=ss_mod.coords) as model:
+            P0 = pm.Deterministic('P0', pt.eye(ss_mod.k_states), dims=ss_mod.param_dims['P0'])
+
+            initial_level_trend = pm.Normal('initial_level_trend', dims=ss_mod.param_dims['initial_level_trend'])
+            sigma_level_trend = pm.HalfNormal('sigma_level_trend', dims=ss_mod.param_dims['sigma_level_trend'])
+
+            business_cycle = pm.Normal("business_cycle", dims=ss_mod.param_dims["business_cycle"])
+            dampening = pm.Beta("dampening_factor_business_cycle", 2, 2)
+            sigma_cycle = pm.HalfNormal("sigma_business_cycle", sigma=1)
+
+            ss_mod.build_statespace_graph(data)
+            idata = pm.sample(
+                nuts_sampler="nutpie", nuts_sampler_kwargs={"backend": "JAX", "gradient_backend": "JAX"}
+            )
+
+    **Multivariate Example:**
+    Model cycles for multiple economic indicators with variable-specific innovation variances:
+
+    .. code:: python
+
+        # Multivariate cycle component
+        cycle = st.CycleComponent(
+            name='business_cycle',
+            cycle_length=12,
+            estimate_cycle_length=False,
+            innovations=True,
+            dampen=True,
+            observed_state_names=['gdp', 'unemployment', 'inflation']
+        )
+        ss_mod = cycle.build()
+
+        with pm.Model(coords=ss_mod.coords) as model:
+            P0 = pm.Deterministic("P0", pt.eye(ss_mod.k_states), dims=ss_mod.param_dims["P0"])
+            # Initial states: shape (3, 2) for 3 variables, 2 states each
+            business_cycle = pm.Normal('business_cycle', dims=ss_mod.param_dims["business_cycle"])
+
+            # Dampening factor: scalar (shared across variables)
+            dampening = pm.Beta("dampening_factor_business_cycle", 2, 2)
+
+            # Innovation variances: shape (3,) for variable-specific variances
+            sigma_cycle = pm.HalfNormal(
+                "sigma_business_cycle", dims=ss_mod.param_dims["sigma_business_cycle"]
+            )
+
+            ss_mod.build_statespace_graph(data)
+            idata = pm.sample(
+                nuts_sampler="nutpie", nuts_sampler_kwargs={"backend": "JAX", "gradient_backend": "JAX"}
+            )
+
+    References
+    ----------
+    .. [1] Durbin, James, and Siem Jan Koopman. 2012.
+        Time Series Analysis by State Space Methods: Second Edition.
+        Oxford University Press.
+    """
+
+    def __init__(
+        self,
+        name: str | None = None,
+        cycle_length: int | None = None,
+        estimate_cycle_length: bool = False,
+        dampen: bool = False,
+        innovations: bool = True,
+        observed_state_names: list[str] | None = None,
+        share_states: bool = False,
+    ):
+        if observed_state_names is None:
+            observed_state_names = ["data"]
+
+        if cycle_length is None and not estimate_cycle_length:
+            raise ValueError("Must specify cycle_length if estimate_cycle_length is False")
+        if cycle_length is not None and estimate_cycle_length:
+            raise ValueError("Cannot specify cycle_length if estimate_cycle_length is True")
+        if name is None:
+            cycle = int(cycle_length) if cycle_length is not None else "Estimate"
+            name = f"Cycle[s={cycle}, dampen={dampen}, innovations={innovations}]"
+
+        self.share_states = share_states
+        self.estimate_cycle_length = estimate_cycle_length
+        self.cycle_length = cycle_length
+        self.innovations = innovations
+        self.dampen = dampen
+        self.n_coefs = 1
+
+        k_endog = len(observed_state_names)
+
+        k_states = 2 if share_states else 2 * k_endog
+        k_posdef = 2 if share_states else 2 * k_endog
+
+        obs_state_idx = np.zeros(k_states)
+        obs_state_idx[slice(0, k_states, 2)] = 1
+
+        super().__init__(
+            name=name,
+            k_endog=k_endog,
+            k_states=k_states,
+            k_posdef=k_posdef,
+            measurement_error=False,
+            combine_hidden_states=True,
+            obs_state_idxs=obs_state_idx,
+            observed_state_names=observed_state_names,
+            share_states=share_states,
+        )
+
+    def make_symbolic_graph(self) -> None:
+        k_endog = self.k_endog
+        k_endog_effective = 1 if self.share_states else k_endog
+
+        Z = np.array([1.0, 0.0]).reshape((1, -1))
+        design_matrix = block_diag(*[Z for _ in range(k_endog_effective)])
+        self.ssm["design", :, :] = pt.as_tensor_variable(design_matrix)
+
+        # selection matrix R defines structure of innovations (always identity for cycle components)
+        # when innovations=False, state cov Q=0, hence R @ Q @ R.T = 0
+        R = np.eye(2)  # 2x2 identity for each cycle component
+        selection_matrix = block_diag(*[R for _ in range(k_endog_effective)])
+        self.ssm["selection", :, :] = pt.as_tensor_variable(selection_matrix)
+
+        init_state = self.make_and_register_variable(
+            f"params_{self.name}",
+            shape=(k_endog_effective, 2) if k_endog_effective > 1 else (self.k_states,),
+        )
+        self.ssm["initial_state", :] = init_state.ravel()
+
+        if self.estimate_cycle_length:
+            lamb = self.make_and_register_variable(f"length_{self.name}", shape=())
+        else:
+            lamb = self.cycle_length
+
+        if self.dampen:
+            rho = self.make_and_register_variable(f"dampening_factor_{self.name}", shape=())
+        else:
+            rho = 1
+
+        T = rho * _frequency_transition_block(lamb, j=1)
+        transition = block_diag(*[T for _ in range(k_endog_effective)])
+        self.ssm["transition"] = pt.specify_shape(transition, (self.k_states, self.k_states))
+
+        if self.innovations:
+            if k_endog_effective == 1:
+                sigma_cycle = self.make_and_register_variable(f"sigma_{self.name}", shape=())
+                self.ssm["state_cov", :, :] = pt.eye(self.k_posdef) * sigma_cycle**2
+            else:
+                sigma_cycle = self.make_and_register_variable(
+                    f"sigma_{self.name}", shape=(k_endog_effective,)
+                )
+                state_cov = block_diag(
+                    *[pt.eye(2) * sigma_cycle[i] ** 2 for i in range(k_endog_effective)]
+                )
+                self.ssm["state_cov"] = pt.specify_shape(state_cov, (self.k_states, self.k_states))
+        else:
+            # explicitly set state cov to 0 when no innovations
+            self.ssm["state_cov", :, :] = pt.zeros((self.k_posdef, self.k_posdef))
+
+    def populate_component_properties(self):
+        k_endog = self.k_endog
+        k_endog_effective = 1 if self.share_states else k_endog
+
+        base_names = [f"{f}_{self.name}" for f in ["Cos", "Sin"]]
+
+        if self.share_states:
+            self.state_names = [f"{name}[shared]" for name in base_names]
+        else:
+            self.state_names = [
+                f"{name}[{var_name}]" if k_endog_effective > 1 else name
+                for var_name in self.observed_state_names
+                for name in base_names
+            ]
+
+        self.param_names = [f"params_{self.name}"]
+
+        if k_endog_effective == 1:
+            self.param_dims = {f"params_{self.name}": (f"state_{self.name}",)}
+            self.coords = {f"state_{self.name}": base_names}
+            self.param_info = {
+                f"params_{self.name}": {
+                    "shape": (2,),
+                    "constraints": None,
+                    "dims": (f"state_{self.name}",),
+                }
+            }
+        else:
+            self.param_dims = {f"params_{self.name}": (f"endog_{self.name}", f"state_{self.name}")}
+            self.coords = {
+                f"state_{self.name}": [f"Cos_{self.name}", f"Sin_{self.name}"],
+                f"endog_{self.name}": self.observed_state_names,
+            }
+            self.param_info = {
+                f"params_{self.name}": {
+                    "shape": (k_endog_effective, 2),
+                    "constraints": None,
+                    "dims": (f"endog_{self.name}", f"state_{self.name}"),
+                }
+            }
+
+        if self.estimate_cycle_length:
+            self.param_names += [f"length_{self.name}"]
+            self.param_info[f"length_{self.name}"] = {
+                "shape": () if k_endog_effective == 1 else (k_endog_effective,),
+                "constraints": "Positive, non-zero",
+                "dims": None if k_endog_effective == 1 else (f"endog_{self.name}",),
+            }
+
+        if self.dampen:
+            self.param_names += [f"dampening_factor_{self.name}"]
+            self.param_info[f"dampening_factor_{self.name}"] = {
+                "shape": () if k_endog_effective == 1 else (k_endog_effective,),
+                "constraints": "0 < x ≤ 1",
+                "dims": None if k_endog_effective == 1 else (f"endog_{self.name}",),
+            }
+
+        if self.innovations:
+            self.param_names += [f"sigma_{self.name}"]
+            if k_endog_effective == 1:
+                self.param_info[f"sigma_{self.name}"] = {
+                    "shape": (),
+                    "constraints": "Positive",
+                    "dims": None,
+                }
+            else:
+                self.param_dims[f"sigma_{self.name}"] = (f"endog_{self.name}",)
+                self.param_info[f"sigma_{self.name}"] = {
+                    "shape": (k_endog_effective,),
+                    "constraints": "Positive",
+                    "dims": (f"endog_{self.name}",),
+                }
+            self.shock_names = self.state_names.copy()

pymc_extras/statespace/models/structural/components/level_trend.py

@@ -0,0 +1,289 @@
+import numpy as np
+import pytensor.tensor as pt
+
+from pymc_extras.statespace.models.structural.core import Component
+from pymc_extras.statespace.models.structural.utils import order_to_mask
+from pymc_extras.statespace.utils.constants import POSITION_DERIVATIVE_NAMES
+
+
+class LevelTrendComponent(Component):
+    r"""
+    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.
+
+    .. math::
+        \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}
+
+    Where :math:`\mu_{t+1}` is the mean of the timeseries at time t, and :math:`\nu_t` is the drift or the slope of
+    the process. When both innovations :math:`\zeta_t` and :math:`\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:
+
+    .. math::
+        \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}
+
+    After setting all innovation terms to zero and defining initial states :math:`\mu_0, \nu_0, \eta_0`, these equations
+    can be collapsed to:
+
+    .. math::
+        \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``
+
+    .. math::
+        \mu_t = \mu
+
+    * Constant linear slope, ``order=2, innovations_order=0``
+
+    .. math::
+        \mu_t = \mu_{t-1} + \nu
+
+    * Gaussian Random Walk, ``order=1, innovations_order=1``
+
+    .. math::
+        \mu_t = \mu_{t-1} + \zeta_t
+
+    * Gaussian Random Walk with Drift, ``order=2, innovations_order=1``
+
+    .. math::
+        \mu_t = \mu_{t-1} + \nu + \zeta_t
+
+    * Smooth Trend, ``order=2, innovations_order=[0, 1]``
+
+    .. math::
+        \begin{align}
+            \mu_t &= \mu_{t-1} + \nu_{t-1} \\
+            \nu_t &= \nu_{t-1} + \xi_t
+        \end{align}
+
+    * 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.
+
+    """
+
+    def __init__(
+        self,
+        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,
+    ):
+        self.share_states = share_states
+
+        if innovations_order is None:
+            innovations_order = order
+
+        if observed_state_names is None:
+            observed_state_names = ["data"]
+        k_endog = len(observed_state_names)
+
+        self._order_mask = order_to_mask(order)
+        max_state = np.flatnonzero(self._order_mask)[-1].item() + 1
+
+        # If the user passes excess zeros, raise an error. The alternative is to prune them, but this would cause
+        # the shape of the state to be different to what the user expects.
+        if len(self._order_mask) > max_state:
+            raise ValueError(
+                f"order={order} is invalid. The highest derivative should not be set to zero. If you want a "
+                f"lower order model, explicitly omit the zeros."
+            )
+        k_states = max_state
+
+        if isinstance(innovations_order, int):
+            n = innovations_order
+            innovations_order = order_to_mask(k_states)
+            if n > 0:
+                innovations_order[n:] = False
+            else:
+                innovations_order[:] = False
+        else:
+            innovations_order = order_to_mask(innovations_order)
+
+        self.innovations_order = innovations_order[:max_state]
+        k_posdef = int(sum(innovations_order))
+
+        super().__init__(
+            name,
+            k_endog=k_endog,
+            k_states=k_states * k_endog if not share_states else k_states,
+            k_posdef=k_posdef * k_endog if not share_states else k_posdef,
+            observed_state_names=observed_state_names,
+            measurement_error=False,
+            combine_hidden_states=False,
+            obs_state_idxs=np.tile(
+                np.array([1.0] + [0.0] * (k_states - 1)), k_endog if not share_states else 1
+            ),
+            share_states=share_states,
+        )
+
+    def populate_component_properties(self):
+        k_endog = self.k_endog
+        k_endog_effective = 1 if self.share_states else k_endog
+
+        k_states = self.k_states // k_endog_effective
+        k_posdef = self.k_posdef // k_endog_effective
+
+        name_slice = POSITION_DERIVATIVE_NAMES[:k_states]
+        self.param_names = [f"initial_{self.name}"]
+        base_names = [name for name, mask in zip(name_slice, self._order_mask) if mask]
+
+        if self.share_states:
+            self.state_names = [f"{name}[{self.name}_shared]" for name in base_names]
+        else:
+            self.state_names = [
+                f"{name}[{obs_name}]"
+                for obs_name in self.observed_state_names
+                for name in base_names
+            ]
+
+        self.param_dims = {f"initial_{self.name}": (f"state_{self.name}",)}
+        self.coords = {f"state_{self.name}": base_names}
+
+        if k_endog > 1:
+            self.coords[f"endog_{self.name}"] = self.observed_state_names
+
+        if k_endog_effective > 1:
+            self.param_dims[f"state_{self.name}"] = (
+                f"endog_{self.name}",
+                f"state_{self.name}",
+            )
+            self.param_dims = {f"initial_{self.name}": (f"endog_{self.name}", f"state_{self.name}")}
+
+        shape = (k_endog_effective, k_states) if k_endog_effective > 1 else (k_states,)
+        self.param_info = {f"initial_{self.name}": {"shape": shape, "constraints": None}}
+
+        if self.k_posdef > 0:
+            self.param_names += [f"sigma_{self.name}"]
+
+            base_shock_names = [
+                name for name, mask in zip(name_slice, self.innovations_order) if mask
+            ]
+
+            if self.share_states:
+                self.shock_names = [f"{name}[{self.name}_shared]" for name in base_shock_names]
+            else:
+                self.shock_names = [
+                    f"{name}[{obs_name}]"
+                    for obs_name in self.observed_state_names
+                    for name in base_shock_names
+                ]
+
+            self.param_dims[f"sigma_{self.name}"] = (
+                (f"shock_{self.name}",)
+                if k_endog_effective == 1
+                else (f"endog_{self.name}", f"shock_{self.name}")
+            )
+            self.coords[f"shock_{self.name}"] = base_shock_names
+            self.param_info[f"sigma_{self.name}"] = {
+                "shape": (k_posdef,) if k_endog_effective == 1 else (k_endog_effective, k_posdef),
+                "constraints": "Positive",
+            }
+
+        for name in self.param_names:
+            self.param_info[name]["dims"] = self.param_dims[name]
+
+    def make_symbolic_graph(self) -> None:
+        k_endog = self.k_endog
+        k_endog_effective = 1 if self.share_states else k_endog
+
+        k_states = self.k_states // k_endog_effective
+        k_posdef = self.k_posdef // k_endog_effective
+
+        initial_trend = self.make_and_register_variable(
+            f"initial_{self.name}",
+            shape=(k_states,) if k_endog_effective == 1 else (k_endog, k_states),
+        )
+        self.ssm["initial_state", :] = initial_trend.ravel()
+
+        triu_idx = pt.triu_indices(k_states)
+        T = pt.zeros((k_states, k_states))[triu_idx[0], triu_idx[1]].set(1)
+
+        self.ssm["transition", :, :] = pt.specify_shape(
+            pt.linalg.block_diag(*[T for _ in range(k_endog_effective)]),
+            (self.k_states, self.k_states),
+        )
+
+        R = np.eye(k_states)
+        R = R[:, self.innovations_order]
+
+        self.ssm["selection", :, :] = pt.specify_shape(
+            pt.linalg.block_diag(*[R for _ in range(k_endog_effective)]),
+            (self.k_states, self.k_posdef),
+        )
+
+        Z = np.array([1.0] + [0.0] * (k_states - 1)).reshape((1, -1))
+
+        if self.share_states:
+            self.ssm["design", :, :] = pt.specify_shape(
+                pt.join(0, *[Z for _ in range(k_endog)]), (self.k_endog, self.k_states)
+            )
+        else:
+            self.ssm["design", :, :] = pt.specify_shape(
+                pt.linalg.block_diag(*[Z for _ in range(k_endog)]), (self.k_endog, self.k_states)
+            )
+
+        if k_posdef > 0:
+            sigma_trend = self.make_and_register_variable(
+                f"sigma_{self.name}",
+                shape=(k_posdef,) if k_endog_effective == 1 else (k_endog, k_posdef),
+            )
+            diag_idx = np.diag_indices(k_posdef * k_endog_effective)
+            idx = np.s_["state_cov", diag_idx[0], diag_idx[1]]
+            self.ssm[idx] = (sigma_trend**2).ravel()