forecasting-single-series

Forecasting a Single Time Series

When to Use

Use this workflow when you have one time series and want to predict its future values.

• ForecasterRecursive: Default choice. Uses its own predictions as inputs for multi-step forecasting. Works with any sklearn-compatible regressor.
• ForecasterDirect: Trains one model per forecast step. Better when the relationship between lags and target changes across the horizon.

Related skills

• Before: choosing-a-forecaster (decide between Recursive and Direct based on the data)
• Before: autocorrelation-and-lag-selection (pick the lags argument from ACF/PACF analysis)
• Before: feature-engineering (assemble the rolling, calendar, and exogenous features)
• After: hyperparameter-optimization (tune the forecaster once a baseline is trained)
• After: prediction-intervals (add bootstrap or conformal intervals on top of the point forecasts)

Stop Conditions

Scan before writing code. Each row lists a rule, the symptom when it is broken, and the recovery. Full pitfall catalog: the troubleshooting-common-errors skill.

Complete Workflow

import pandas as pd
from sklearn.ensemble import RandomForestRegressor
from skforecast.recursive import ForecasterRecursive
from skforecast.preprocessing import RollingFeatures
from skforecast.model_selection import backtesting_forecaster, TimeSeriesFold

# 1. Load and prepare data (MUST have DatetimeIndex with frequency)
data = pd.read_csv('data.csv', index_col='date', parse_dates=True)
data = data.asfreq('h')  # Set frequency — required

# 2. Train/test split (time-based, never random)
end_train = '2023-01-01'
y_train = data.loc[:end_train, 'target']
y_test = data.loc[end_train:, 'target']

# 3. Create forecaster with optional rolling features
rolling_features = RollingFeatures(
    stats=['mean', 'std'],
    window_sizes=24
)

forecaster = ForecasterRecursive(
    estimator=RandomForestRegressor(n_estimators=100, random_state=123),
    lags=24,
    window_features=rolling_features,
    transformer_y=None,          # e.g., StandardScaler() for scaling
    categorical_features='auto', # Auto-detect and encode non-numeric exog columns
    differentiation=None,        # e.g., 1 for first-order differencing
    dropna_from_series=False,    # True to drop NaN rows; False to keep (NaN-tolerant estimators)
)

# 4. Train
forecaster.fit(y=y_train)

# 5. Predict
predictions = forecaster.predict(steps=10)

# 6. Backtesting (proper evaluation)
cv = TimeSeriesFold(
    steps=10,
    initial_train_size=len(y_train),
    refit=False,
    fixed_train_size=False,
)

metric, predictions_bt = backtesting_forecaster(
    forecaster=forecaster,
    y=data['target'],
    cv=cv,
    metric='mean_absolute_error',
)
print(f"MAE: {metric}")

# 7. Prediction intervals
# Default interval is [0.05, 0.95] (90%). Here [0.1, 0.9] creates an 80% interval.
forecaster.fit(y=y_train, store_in_sample_residuals=True)
predictions_interval = forecaster.predict_interval(
    steps=10,
    interval=[0.1, 0.9],        # 80% prediction interval (quantiles, 0-1 scale)
    method='bootstrapping',
    n_boot=500,
)

With Exogenous Variables

# Exogenous variables must cover the forecast horizon during prediction
forecaster = ForecasterRecursive(
    estimator=RandomForestRegressor(n_estimators=100, random_state=123),
    lags=24,
)
forecaster.fit(y=y_train, exog=exog_train)
predictions = forecaster.predict(steps=10, exog=exog_test)

Using ForecasterDirect

from skforecast.direct import ForecasterDirect

# Must specify `steps` at creation — trains one model per step
forecaster = ForecasterDirect(
    estimator=RandomForestRegressor(n_estimators=100, random_state=123),
    lags=24,
    steps=10,
    categorical_features='auto',  # Auto-detect and encode non-numeric exog columns
)
forecaster.fit(y=y_train, exog=exog_train)
predictions = forecaster.predict(exog=exog_test)

Common Mistakes

1. Missing frequency on index: Always call data.asfreq('h') (or 'D', 'MS', etc.).
2. NaN in data: Forecasters reject NaN by default. Use dropna_from_series=True to drop incomplete rows, or keep dropna_from_series=False (default) with NaN-tolerant estimators (LightGBM, CatBoost, HistGradientBoosting, XGBoost hist). Alternatively, impute missing values first.
3. Exog not covering forecast horizon: The exogenous DataFrame for predict() must have rows for every future step.
4. Random train/test split: Time series must be split chronologically, never shuffled.
5. Forgetting store_in_sample_residuals=True: Required before calling predict_interval() with method='bootstrapping' on a standalone forecaster. During backtesting, residuals are computed automatically.