prediction-intervals
/prediction-intervals
Wyznacza przedziały predykcji dla prognoz szeregów czasowych metodą bootstrapu, konformalną lub wbudowanymi przedziałami modelu z kalibracją.
- Autor
- skforecast ↗
- Repozytorium
- skforecast ↗
- Licencja
- BSD-3-Clause
- Ostatnia zmiana repozytorium
- 11.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 1
Brak sygnałów. Repozytorium zmienione 11.11.2026, bez odwołań do wycofanych modeli i API.
BSD-3-Clause, otwarta.
Co robi i kiedy
Wyznacza przedziały predykcji dla prognoz szeregów czasowych metodą bootstrapu, konformalną lub wbudowanymi przedziałami modelu z kalibracją.
Oryginalny opis (EN)
Generates prediction intervals for time series forecasts using bootstrapping, conformal prediction, or built-in statistical model intervals. Covers interval configuration, residual management, and calibration. Use when the user needs uncertainty quantification for forecasts.
Jak działa
- When to Use
- Intervals Are Quantiles
- Stop Conditions
- Bootstrapping Method
- Conformal Prediction
- Statistical Model Intervals
- Foundation Model Intervals
- During Backtesting
- Multi-Series Intervals
- Out-of-Sample Residuals (Better Calibration)
Podgląd SKILL.md
---
name: prediction-intervals
description: >
Generates prediction intervals for time series forecasts using bootstrapping,
conformal prediction, or built-in statistical model intervals. Covers
interval configuration, residual management, and calibration.
Use when the user needs uncertainty quantification for forecasts.
---
# Prediction Intervals
## When to Use
Use prediction intervals to quantify forecast uncertainty. Skforecast offers three methods:
| Method | Forecasters | Description |
|--------|-------------|-------------|
| **Bootstrapping** | Recursive, Direct, RecursiveMultiSeries, DirectMultiVariate | Resample from training residuals |
| **Conformal** | All ML forecasters (incl. RNN, EquivalentDate) | Distribution-free intervals via conformal prediction |
| **Built-in** | ForecasterStats (ARIMA, ETS) | Parametric intervals from the statistical model |
### 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
- **Prerequisite**: `forecasting-single-series` / `forecasting-multiple-series` (have a fitted forecaster before adding intervals)
- **Prerequisite**: `hyperparameter-optimization` (interval calibration assumes a tuned point forecaster)
- **Next**: `drift-detection` (monitor whether residual assumptions still hold once the model is in production)
## Intervals Are Quantiles
`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]`.
- Mixing scales (e.g. `[0.1, 90]`) raises a `ValueError` (ambiguous scale).
- `predict_quantiles(quantiles=...)` uses the same 0-1 scale.
<details>
<summary>Old patterns: percentile intervals</summary>
Earlier versions took percentiles in `[0, 100]`, e.g. `interval=[10, 90]`.
Percentiles still work but emit a `FutureWarning` and will be removed in a
future release. Convert by dividing by 100, so `[10, 90]` becomes `[0.1, 0.9]`.
</details>
## 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.
| Rule | Symptom | Recovery |
|------|---------|----------|
| Fit with `store_in_sample_residuals=True` before `predict_interval(method='bootstrapping')` | `No in-sample residuals stored` | Refit: `forecaster.fit(y=y_train, store_in_sample_residuals=True)` |
| Multi-series forecasters default to `method='conformal'`, not `'bootstrapping'` | Bootstrapping silently not applied on `ForecasterRecursiveMultiSeries` / `ForecasterDirectMultiVariate` | Pass `method='bootstrapping'` explicitly when that is what you want |
| ML forecasters accept `interval=`; only `ForecasterStats` accepts `alpha=` | `TypeError` / unexpected argument | Use `interval=[lower, upper]` for ML forecasters |
| `interval` must be quantiles in `[0, 1]`, not percentiles | `FutureWarning` (percentiles deprecated) | Use `interval=[0.1, 0.9]` instead of `interval=[10, 90]` |
| Do not mix quantile and percentile scales in one `interval` | `ValueError`: scale is ambiguous | Use a single scale, e.g. `interval=[0.05, 0.95]` |
## Bootstrapping Method
```python
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
```python
# 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
```python
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, so no bootstrapping or conformal calibration is required.
```python
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 3.0), Moirai-2 and TiRex-2 restrict quantiles to `[0.1, 0.2, …, 0.9]`; TS-ICL restricts them to a 0.01 grid in `[0.01, 0.99]`; Timestral to 21 levels (`0.01`, `0.05`, `0.1`, ..., `0.95`, `0.99`); Chronos-2, TabICL, TabPFN-TS, TFC-T0, and Nori accept any quantile in `(0, 1)`. See the `foundation-forecasting` skill for details.
## During Backtesting
```python
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: fold, step, y_true, pred, lower_bound, upper_bound
# metric has columns: mean_absolute_error, coverage, interval_width, n_evaluated
```
When `interval` defines one interval (a float, or two quantiles optionally with
the median, such as `[0.1, 0.5, 0.9]`), `metric` also reports its empirical
`coverage` and its mean width (`interval_width`, in the units of the series),
per level and aggregated in multi-series backtesting. `backtesting_foundation`
does the same with `quantiles`. A coverage
well below the nominal level (0.8 for `[0.1, 0.9]`) is common with in-sample
residuals and complex estimators: switch to out-of-sample residuals (see below).
## Multi-Series Intervals
```python
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)
```python
# 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=predictions_bt['y_true'],
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
)
```
With binned residuals, keep an average of at least 10 out-of-sample residuals
per bin (100 residuals for the default `n_bins=10`). Below that,
`set_out_sample_residuals` issues a `ResidualsUsageWarning` and the intervals
tend to be too narrow: reduce the bins with `binner_kwargs={'n_bins': 3}` when
creating the forecaster, or predict with `use_binned_residuals=False`.
## Evaluating Interval Quality
Backtesting with one interval (two quantiles, optionally with the median) already returns `coverage` and
`interval_width` in `metric`. For predictions made outside backtesting (for
example `predict_interval` on a test set), compute it with `calculate_coverage`:
```python
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
```
To plot the interval against the true values, `plot_prediction_intervals` takes
them from the `y_true` column of the backtesting predictions. Predictions of
`predict_interval` have no `y_true`: pass the series with `y_true`. With
multiple series, filter the rows of one level first.
```python
from skforecast.plot import plot_prediction_intervals
plot_prediction_intervals(predictions) # backtesting predictions
plot_prediction_intervals(predictions, y_true=y_test) # predict_interval
```
## Beyond Intervals
For bootstrapping-capable ML forecasters (Recursive, Direct, RecursiveMultiSeries,
DirectMultiVariate), two richer probabilistic outputs build on the same residual
resampling:
```python
# 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](references/interval-compatibility.md) for the full method/forecaster support matrix.
## Common Mistakes
1. **Passing percentiles instead of quantiles**: `interval` is on the 0-1 scale. Use `interval=[0.1, 0.9]`, not `[10, 90]` (percentiles are deprecated and emit a `FutureWarning`). 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`**: in `ForecasterStats` and `backtesting_stats`, `alpha` is an alias of `interval` (`alpha=0.05` is `interval=[0.025, 0.975]`). Pass only one of them; passing both raises a `ValueError`. ML forecasters only support `interval`.
5. **Not evaluating coverage**: Always check if actual coverage matches the nominal level. Backtesting with one interval (a float `interval`, or two quantiles optionally with the median) reports it in the `coverage` column of `metric`, next to `interval_width`.
6. **Ignoring physical bounds**: neither the model nor the intervals know that a series cannot be negative (counts, sales, demand), so predictions and lower bounds can fall below zero. Clip them after predicting, e.g. `predictions.clip(lower=0)`. See the FAQ [Non-negative predictions](https://skforecast.org/latest/faq/non-negative-predictions.html).
## References
See [references/interval-compatibility.md](references/interval-compatibility.md) for the complete compatibility matrix: which forecaster supports which method, parameter differences, binned residuals support, and common error patterns.
Pliki w paczce (2)
- SKILL.md 13 KB
- references/interval-compatibility.md 8 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · skforecast/skforecast | 100 | BSD-3-Clause |
| skforecast/skforecast-ai | 100 | Apache-2.0 |
Migawka bazy z 13.11.2026 · wersja paczki 91305fb706e9 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100nixtla-uncertainty-quantifier
Określa niepewność prognoz metodą predykcji konforemnej, generując przedziały predykcji i pasma ufności dla oceny ryzyka i planowania scenariuszy. - 100forecasting-single-series
Prognozuje pojedynczy szereg czasowy z ForecasterRecursive lub ForecasterDirect: przygotowanie danych, trening, predykcja, backtesting i przedziały predykcji. - 95timesfm-forecasting
Prognozuje szeregi czasowe bez trenowania własnego modelu, np. sprzedaż lub odczyty czujników, z przedziałami predykcji. - 100conformal-methods-reviewer
Przegląda pomysły, szkice, wyniki i argumenty teoretyczne dotyczące predykcji konforemnej pod kątem poprawności, ważności gwarancji pokrycia i trafności założeń, np. wymienności danych. - 100timesfm-forecasting
Prognozuje szeregi czasowe zero-shot modelem TimesFM od Google, z prognozami punktowymi i przedziałami predykcji. - 100timesfm
Prognozuje szeregi czasowe wstępnie wytrenowanym modelem Google TimesFM bez treningu: sprzedaż, popyt, metryki serwerów, przedziały predykcji, kowariaty i anomalie względem prognozy.