UnobservedComponentsResult.forecast#

UnobservedComponentsResult.forecast(steps)[source]#

Out-of-sample forecasts with honest standard errors.

Filters the estimation sample to the last state, then propagates mean and covariance through the fitted system,

\[a_{n+h} = T a_{n+h-1}, \qquad P_{n+h} = T P_{n+h-1} T' + R Q R', \qquad \hat y_{n+h} = Z a_{n+h}, \quad \operatorname{Var}(y_{n+h}) = Z P_{n+h} Z' + \sigma^2_\varepsilon.\]

A local level forecasts flat at the last filtered level; a trend with a slope extrapolates it; a cycle decays at \(\rho\) per step; a seasonal repeats its last pattern. The standard errors grow without bound for the unit-root components.

Parameters:

steps (int) – Horizons ahead, at least 1.

Return type:

tuple[NDArray[double], NDArray[double]]

Returns:

(mean, std) arrays of length steps; the standard errors include state uncertainty and the irregular, but not parameter uncertainty.

Raises:

SpecificationError – If steps is not positive.

Example

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> y = np.cumsum(0.2 * rng.standard_normal(200)) + rng.standard_normal(200)
>>> res = UnobservedComponents(y).fit()
>>> mean, std = res.forecast(5)
>>> mean.shape, bool(np.allclose(mean, mean[0])), bool(std[-1] > std[0])
((5,), True, True)
>>> bool(std[0] ** 2 > res.sigma2_irregular)
True
>>> res.forecast(0)
Traceback (most recent call last):
cultivars.exceptions.SpecificationError: steps must be at least 1; got 0.