prediction-intervals

Prediction Intervals

When to Use

Use prediction intervals to quantify forecast uncertainty. Skforecast offers three methods:

Choosing a method

• Conformal: distribution-free, fast, and gives a single symmetric coverage guarantee. The default for multi-series forecasters and the only option for ForecasterRnn / ForecasterEquivalentDate. Prefer it when you need a quick, well-calibrated interval and do not need the full predictive distribution.
• Bootstrapping: resamples residuals to build the full predictive distribution, so it also powers predict_quantiles() and predict_dist(). Prefer it when you need arbitrary quantiles, a fitted distribution, or asymmetric intervals. Needs enough stored residuals to be reliable.
• Built-in: parametric intervals from the statistical model itself (ForecasterStats). No residual management required.

Related skills

• Before: forecasting-single-series / forecasting-multiple-series (have a fitted forecaster before adding intervals)
• Before: hyperparameter-optimization (interval calibration assumes a tuned point forecaster)
• After: drift-detection (monitor whether residual assumptions still hold once the model is in production)

Intervals Are Quantiles (Changed in 0.23.0)

Since skforecast 0.23.0, interval is expressed as quantiles in [0, 1], not percentiles in [0, 100]. For example, an 80% interval is interval=[0.1, 0.9] (the default is [0.05, 0.95] = 90%).

• interval also accepts a single float as nominal coverage: interval=0.95 is equivalent to interval=[0.025, 0.975].
• Passing percentiles (e.g. [10, 90]) still works but emits a FutureWarning and will be removed in skforecast 0.25.0.
• Mixing scales (e.g. [0.1, 90]) raises a ValueError (ambiguous scale).
• predict_quantiles(quantiles=...) was already on the 0-1 scale and is unchanged.

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.

Bootstrapping Method

from skforecast.recursive import ForecasterRecursive
from sklearn.ensemble import RandomForestRegressor

forecaster = ForecasterRecursive(
    estimator=RandomForestRegressor(n_estimators=100, random_state=123),
    lags=24,
)

# IMPORTANT: store_in_sample_residuals=True is required for bootstrapping
forecaster.fit(y=y_train, store_in_sample_residuals=True)

predictions = forecaster.predict_interval(
    steps=10,
    interval=[0.1, 0.9],             # Quantiles → 80% interval (default is [0.05, 0.95] = 90%)
    method='bootstrapping',
    n_boot=250,                      # Number of bootstrap samples (default)
    use_in_sample_residuals=True,    # Use training residuals
    use_binned_residuals=True,       # Better calibration: residuals binned by prediction level
    random_state=123,
)
# Returns: DataFrame with columns [pred, lower_bound, upper_bound]

Conformal Prediction

# IMPORTANT: store_in_sample_residuals=True is also required for conformal
forecaster.fit(y=y_train, store_in_sample_residuals=True)

predictions = forecaster.predict_interval(
    steps=10,
    interval=[0.1, 0.9],
    method='conformal',
    use_in_sample_residuals=True,    # Uses in_sample_residuals_ stored during fit
    use_binned_residuals=True,
)

Statistical Model Intervals

from skforecast.recursive import ForecasterStats
from skforecast.stats import Arima

forecaster = ForecasterStats(
    estimator=Arima(order=(1, 1, 1), seasonal_order=(1, 1, 1), m=12)
)
forecaster.fit(y=y_train)

# Uses parametric intervals from statsmodels — different interface
predictions = forecaster.predict_interval(
    steps=12,
    interval=[0.1, 0.9],       # Quantiles → 80% interval. Equivalently, alpha=0.2
)

Foundation Model Intervals

ForecasterFoundation returns intervals and quantiles directly from the underlying foundation model's native quantile output — no bootstrapping or conformal calibration required.

from skforecast.foundation import FoundationModel, ForecasterFoundation

forecaster = ForecasterFoundation(
    estimator=FoundationModel(model_id='autogluon/chronos-2-small')
)
forecaster.fit(series=y_train)

predictions = forecaster.predict_interval(steps=24, interval=[0.1, 0.9])
predictions = forecaster.predict_quantiles(
    steps=24, quantiles=[0.1, 0.5, 0.9]
)

TimesFM 2.5 and Moirai-2 restrict quantiles to [0.1, 0.2, …, 0.9]; Chronos-2, TabICL, TabPFN-TS and TFC-T0 accept any quantile in (0, 1). See the foundation-forecasting skill for details.

During Backtesting

from skforecast.model_selection import backtesting_forecaster, TimeSeriesFold

cv = TimeSeriesFold(
    steps=10,
    initial_train_size=len(y_train),
    refit=False,
)

metric, predictions = backtesting_forecaster(
    forecaster=forecaster,
    y=data['target'],
    cv=cv,
    metric='mean_absolute_error',
    interval=[0.1, 0.9],
    interval_method='bootstrapping',   # or 'conformal'
    n_boot=250,
    use_in_sample_residuals=True,
    use_binned_residuals=True,
)
# predictions has columns: pred, lower_bound, upper_bound

Multi-Series Intervals

from skforecast.recursive import ForecasterRecursiveMultiSeries

# NOTE: default method for multi-series is 'conformal', not 'bootstrapping'
predictions = forecaster_multi.predict_interval(
    steps=10,
    levels=['series_1', 'series_2'],
    interval=[0.1, 0.9],
    method='conformal',
)

Out-of-Sample Residuals (Better Calibration)

# For better interval calibration, use out-of-sample residuals
# First, compute them via backtesting
metric, predictions_bt = backtesting_forecaster(
    forecaster=forecaster,
    y=data['target'],
    cv=cv,
    metric='mean_absolute_error',
)

# Set out-of-sample residuals on the forecaster
forecaster.set_out_sample_residuals(
    y_true=data['target'].loc[predictions_bt.index],
    y_pred=predictions_bt['pred'],
)

# Now use them for intervals
predictions = forecaster.predict_interval(
    steps=10,
    interval=[0.1, 0.9],
    method='bootstrapping',
    use_in_sample_residuals=False,  # Use out-of-sample residuals
)

Evaluating Interval Quality

from skforecast.metrics import calculate_coverage

coverage = calculate_coverage(
    y_true=y_test,
    lower_bound=predictions['lower_bound'],
    upper_bound=predictions['upper_bound'],
)
print(f"Coverage: {coverage:.2%}")  # Should be close to 0.80 for [0.1, 0.9] interval

Beyond Intervals

For bootstrapping-capable ML forecasters (Recursive, Direct, RecursiveMultiSeries, DirectMultiVariate), two richer probabilistic outputs build on the same residual resampling:

# Arbitrary quantiles — returns one column per quantile (q_0.05, q_0.5, q_0.95)
predictions = forecaster.predict_quantiles(
    steps=10,
    quantiles=[0.05, 0.5, 0.95],
    n_boot=250,
)

# Fit a scipy distribution to the bootstrapped predictions
from scipy.stats import norm

predictions = forecaster.predict_dist(
    steps=10,
    distribution=norm,   # any scipy.stats distribution
    n_boot=250,
)

See references/interval-compatibility.md for the full method/forecaster support matrix.

Common Mistakes

1. Passing percentiles instead of quantiles: Since 0.23.0, interval is on the 0-1 scale. Use interval=[0.1, 0.9], not [10, 90] (percentiles are deprecated and emit a FutureWarning, removed in 0.25.0). Mixing scales, e.g. [0.1, 90], raises a ValueError.
2. Forgetting store_in_sample_residuals=True: Required in fit() before using predict_interval(method='bootstrapping').
3. Wrong default method for multi-series: ForecasterRecursiveMultiSeries and ForecasterDirectMultiVariate default to method='conformal', not 'bootstrapping'.
4. Mixing alpha and interval: ForecasterStats supports both alpha (e.g., alpha=0.05 for 95% interval) and interval=[lo, hi] (quantiles). ML forecasters only support interval.
5. Not evaluating coverage: Always check if actual coverage matches nominal interval width.

References

See references/interval-compatibility.md for the complete compatibility matrix: which forecaster supports which method, parameter differences, binned residuals support, and common error patterns.