Skip to content

Bsts

polars_ts.bayesian.bsts

Bayesian Structural Time Series (BSTS).

A flexible state-space framework that decomposes a time series into structural components (level, trend, seasonality, regression) and estimates them via the Kalman filter/smoother.

The state vector is assembled by stacking component sub-states:

x_t = [level_t, trend_t, season_t(1), ..., season_t(s-1), beta ...]
References

Scott & Varian (2014). Predicting the Present with Bayesian Structural Time Series.

BSTSResult dataclass

Container for BSTS fit / forecast output.

Attributes

kalman_result Full Kalman filter/smoother result. level Smoothed level component of shape (T,). trend Smoothed trend component of shape (T,) or None. seasonal Smoothed seasonal component of shape (T,) or None. regression Smoothed regression component of shape (T,) or None. forecast Point forecast of shape (h,) or None. forecast_var Forecast variance of shape (h,) or None.

BSTS

Bayesian Structural Time Series model.

Assembles a state-space model from structural components and estimates states via the Kalman filter/smoother.

Parameters

trend Trend type: "level" (random walk) or "local_linear" (random walk + drift). seasonal Number of seasons. None to disable seasonality. sigma_obs Observation noise standard deviation. sigma_level Level component noise standard deviation. sigma_trend Trend component noise standard deviation (only for trend="local_linear"). sigma_seasonal Seasonal component noise standard deviation.

_build_system()

Assemble full system matrices from components.

fit(y)

Fit the BSTS model to observed data.

Parameters

y Observations of shape (T,). Use np.nan for missing.

Returns

BSTSResult Decomposed components and Kalman filter/smoother result.

forecast(y, h)

Fit the model and produce h-step-ahead forecasts.

Parameters

y Observations of shape (T,). h Number of steps to forecast.

Returns

BSTSResult Components plus forecast and forecast_var arrays.

_build_local_level(sigma_level)

Return (F, H, Q) blocks for a local-level component.

_build_local_linear_trend(sigma_level, sigma_trend)

Return (F, H, Q) blocks for a local linear trend.

_build_seasonal(n_seasons, sigma_seasonal)

Return (F, H, Q) blocks for a dummy seasonal component.

State dimension is n_seasons - 1. The constraint is that seasonal effects sum to zero over a full cycle.

_block_diag(*blocks)

Build a block-diagonal matrix from sub-blocks.

bsts_fit(df, trend='local_linear', seasonal=None, sigma_obs=1.0, sigma_level=0.1, sigma_trend=0.01, sigma_seasonal=0.01, id_col='unique_id', target_col='y')

Fit a BSTS model to each time series in a panel.

Parameters

df DataFrame with columns id_col and target_col. trend "level" or "local_linear". seasonal Number of seasons (e.g. 12 for monthly, 24 for hourly). None to disable. sigma_obs, sigma_level, sigma_trend, sigma_seasonal Noise standard deviations for each component. id_col Column identifying each time series. target_col Column with the observed values.

Returns

dict[str, BSTSResult] Mapping from series ID to the fit result.

bsts_forecast(df, h, trend='local_linear', seasonal=None, sigma_obs=1.0, sigma_level=0.1, sigma_trend=0.01, sigma_seasonal=0.01, id_col='unique_id', target_col='y')

Fit a BSTS model and produce h-step-ahead forecasts.

Parameters

df DataFrame with columns id_col and target_col. h Forecast horizon. trend, seasonal, sigma_obs, sigma_level, sigma_trend, sigma_seasonal Model configuration (see :class:BSTS). id_col Column identifying each time series. target_col Column with the observed values.

Returns

dict[str, BSTSResult] Mapping from series ID to the fit+forecast result.