This guide explains how to build, evaluate and compare time-series forecasting models in Python without data leakage. It complements the reusable code, benchmark CLI and notebooks in this repository.
Time-series forecasting estimates future values from observations ordered over time. Common applications include demand forecasting, sales forecasting, financial forecasting, traffic prediction, energy-load forecasting, capacity planning, inventory planning and anomaly detection.
A forecasting workflow should define:
- target variable;
- sampling frequency;
- forecast horizon;
- seasonal period;
- missing-value policy;
- retraining frequency;
- evaluation metric;
- operational acceptance threshold.
Simple baselines are essential because they reveal whether a complex model adds real value.
The next value is predicted as the latest observed value. This is often competitive for random-walk-like series.
The forecast repeats the value from the previous seasonal cycle. It is a strong baseline for weekly, monthly, quarterly and annual seasonal data.
The model extends the average historical slope into the future.
The forecast uses a recent rolling average to smooth local noise.
Autoregressive models predict future values from lagged observations. They are useful when recent values contain predictive information and the series is sufficiently stable.
Exponential-smoothing models are effective for level, trend and repeated seasonality. Holt-Winters forecasting can model additive or multiplicative seasonal patterns.
ARIMA combines autoregression, differencing and moving-average errors. SARIMA extends ARIMA with seasonal terms. These models should be selected with residual diagnostics, chronological validation and explicit seasonal assumptions.
Machine-learning models convert a time series into supervised learning features such as:
- lagged values;
- rolling means and standard deviations;
- calendar features;
- trend indicators;
- holiday and event variables;
- external regressors.
The repository currently includes regularized lag regression. Future extensions may include gradient boosting and other tabular forecasting models.
LSTM, GRU, N-BEATS, N-HiTS, Temporal Fusion Transformer and PatchTST can be useful for large or multivariate datasets. They should still be compared with strong simple baselines and evaluated for latency, stability, retraining cost and reproducibility.
Random train-test splitting is inappropriate for forecasting because it allows future observations to influence training.
Use one of these approaches:
Train on the earliest observations and test on the most recent block.
Repeatedly train on past data and evaluate on the next forecast window.
The training window grows over time while the test horizon moves forward.
A fixed-length training window moves through time, which is useful when older data becomes less relevant.
Mean absolute error is easy to interpret and less sensitive to large errors than RMSE.
Root mean squared error penalizes large misses more heavily.
Mean absolute percentage error is intuitive but unstable when actual values are zero or close to zero.
Symmetric mean absolute percentage error reduces some MAPE asymmetry and is useful for comparing relative errors.
No single metric is sufficient for every forecasting problem.
Point forecasts do not communicate uncertainty. Production systems should often include prediction intervals, quantile forecasts, calibration analysis and coverage metrics.
Anomalies can be identified when observed values fall outside expected forecast intervals or produce unusually large residuals. Thresholds should account for seasonality, changing variance and business impact.
- Understand frequency, horizon, trend, seasonality and missing values.
- Establish naive and seasonal-naive baselines.
- Add autoregression or exponential smoothing.
- Add leakage-safe lag-based machine learning.
- Evaluate through walk-forward or expanding-window backtesting.
- Compare MAE, RMSE and sMAPE.
- Inspect residuals and failure periods.
- Introduce advanced models only when they produce repeatable improvement.
../README.md— project overview and quick start.BENCHMARK_LEADERBOARD.md— cross-dataset model rankings.BENCHMARK_METHODOLOGY.md— evaluation protocol.FAQ.md— common forecasting questions.GLOSSARY.md— forecasting terminology.TROUBLESHOOTING.md— installation and runtime help.
This guide is relevant to Python time-series forecasting, forecasting backtesting, walk-forward validation, rolling-origin evaluation, ARIMA, SARIMA, Holt-Winters, autoregression, machine-learning forecasting, LSTM forecasting, GRU forecasting, N-BEATS, PatchTST, demand forecasting, probabilistic forecasting and forecast-based anomaly detection.