Przejdź do treści
Biblioteka skilli
Dane i analityka · Analiza

prediction-intervals

/prediction-intervals

Wyznacza przedziały predykcji dla prognoz szeregów czasowych metodą bootstrapu, konformalną lub wbudowanymi przedziałami modelu z kalibracją.

Repozytorium
skforecast ↗
Licencja
BSD-3-Clause
Ostatnia zmiana repozytorium
11.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 11.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

  1. When to Use
  2. Intervals Are Quantiles
  3. Stop Conditions
  4. Bootstrapping Method
  5. Conformal Prediction
  6. Statistical Model Intervals
  7. Foundation Model Intervals
  8. During Backtesting
  9. Multi-Series Intervals
  10. Out-of-Sample Residuals (Better Calibration)
Sekcje z nagłówków SKILL.md, w oryginale · 292 linii, 1 372 słów
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

RepozytoriumWynikLicencja
Ta strona · skforecast/skforecast100BSD-3-Clause
skforecast/skforecast-ai100Apache-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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.