Baselines

polars_ts.models.baselines

Baseline forecast models for time series benchmarking.

Implements naive, seasonal naive, moving average, and FFT-based forecasts from Ch 4 of "Modern Time Series Forecasting with Python" (2nd Ed.). These serve as simple benchmarks against which more complex models are compared.

_infer_freq(times)

Infer the time frequency from a sorted datetime/date series.

_make_future_dates(last_time, freq, h)

Generate h future timestamps starting from last_time + freq.

naive_forecast(df, h, target_col='y', id_col='unique_id', time_col='ds')

Naive forecast: repeat the last observed value for h steps.

Parameters

df Input DataFrame with time series data. h Forecast horizon (number of steps ahead). target_col Column with the target values. id_col Column identifying each time series. time_col Column with timestamps for ordering.

Returns

pl.DataFrame DataFrame with columns [id_col, time_col, "y_hat"] containing h forecast rows per series.

seasonal_naive_forecast(df, h, season_length, target_col='y', id_col='unique_id', time_col='ds')

Seasonal naive forecast: repeat the last season's values cyclically.

For each forecast step i, the prediction is the observed value from season_length steps before the end of the series, cycling through the last full season.

Parameters

df Input DataFrame with time series data. h Forecast horizon. season_length Number of observations per season (e.g. 7 for daily data with weekly seasonality, 12 for monthly with yearly seasonality). target_col Column with the target values. id_col Column identifying each time series. time_col Column with timestamps for ordering.

Returns

pl.DataFrame DataFrame with columns [id_col, time_col, "y_hat"].

moving_average_forecast(df, h, window_size, target_col='y', id_col='unique_id', time_col='ds')

Forecast the mean of the last window_size observed values.

The same average is repeated for all h forecast steps (flat forecast).

Parameters

df Input DataFrame with time series data. h Forecast horizon. window_size Number of most recent observations to average. target_col Column with the target values. id_col Column identifying each time series. time_col Column with timestamps for ordering.

Returns

pl.DataFrame DataFrame with columns [id_col, time_col, "y_hat"].

fft_forecast(df, h, n_harmonics=5, target_col='y', id_col='unique_id', time_col='ds')

FFT-based forecast using dominant frequency components.

Decomposes the series via FFT, keeps the top n_harmonics frequency components, and extrapolates them forward.

Parameters

df Input DataFrame with time series data. h Forecast horizon. n_harmonics Number of dominant harmonics to retain. More harmonics capture finer detail but risk overfitting noise. target_col Column with the target values. id_col Column identifying each time series. time_col Column with timestamps for ordering.

Returns

pl.DataFrame DataFrame with columns [id_col, time_col, "y_hat"].