docs: enhance conformal prediction tutorial for SEO (#1053)

Author: khuyentran1401

nbs/docs/tutorials/ConformalPrediction.ipynb

@@ -28,61 +28,96 @@
    "source": [
     "# Conformal Prediction\n",
     "\n",
-    "> In this example, we'll implement conformal prediction"
+    "> Learn how to generate calibrated prediction intervals for any forecasting model using conformal prediction, a distribution-free method for uncertainty quantification in Python."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "::: {.callout-warning collapse=\"true\"}\n",
+    "## What You'll Learn\n",
     "\n",
-    "## Prerequisites\n",
+    "In this tutorial, you'll discover how to:\n",
+    "\n",
+    "- Generate **calibrated prediction intervals** without distributional assumptions\n",
+    "- Apply conformal prediction to any forecasting model in Python\n",
+    "- Implement uncertainty quantification with StatsForecast's `ConformalIntervals`\n",
+    "- Compare conformal prediction with traditional uncertainty methods\n",
+    "- Evaluate prediction interval coverage and calibration\n",
     "\n",
-    "This tutorial assumes basic familiarity with StatsForecast. For a minimal example visit the [Quick Start](../getting-started/1_Getting_Started_short)\n",
+    "## Prerequisites\n",
     "\n",
-    ":::"
+    "This tutorial assumes basic familiarity with StatsForecast. For a minimal example visit the [Quick Start](../getting-started/1_Getting_Started_short)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Introduction \n",
+    "## What is Conformal Prediction?\n",
+    "\n",
+    "**Conformal prediction** is a distribution-free framework for generating prediction intervals with guaranteed coverage properties. Unlike traditional methods that assume normally distributed errors, conformal prediction works with any forecasting model and provides **well-calibrated uncertainty estimates** without making distributional assumptions.\n",
+    "\n",
+    "### Why Use Conformal Prediction for Time Series?\n",
+    "\n",
+    "When generating forecasts, a point forecast alone doesn't convey uncertainty. **Prediction intervals** quantify this uncertainty by providing a range of values where future observations are likely to fall. A properly calibrated 95% prediction interval should contain the actual value 95% of the time.\n",
+    "\n",
+    "The challenge: many forecasting models either don't provide prediction intervals, or generate intervals that are poorly calibrated. Traditional statistical methods also assume normality, which often doesn't hold in practice.\n",
     "\n",
-    "When we generate a forecast, we usually produce a single value known as the point forecast. This value, however, doesn't tell us anything about the uncertainty associated with the forecast. To have a measure of this uncertainty, we need **prediction intervals**. \n",
+    "**Conformal prediction solves this by:**\n",
     "\n",
-    "A prediction interval is a range of values that the forecast can take with a given probability. Hence, a 95% prediction interval should contain a range of values that include the actual future value with probability 95%. Probabilistic forecasting aims to generate the full forecast distribution. Point forecasting, on the other hand, usually returns the mean or the median or said distribution. However, in real-world scenarios, it is better to forecast not only the most probable future outcome, but many alternative outcomes as well. \n",
+    "- Working with any forecasting model (model-agnostic)\n",
+    "- Requiring no distributional assumptions\n",
+    "- Using cross-validation to generate calibrated intervals\n",
+    "- Providing theoretical coverage guarantees\n",
+    "- Treating the forecasting model as a black box\n",
     "\n",
-    "The problem is that some timeseries models provide forecast distributions, but some other ones only provide point forecasts. How can we then estimate the uncertainty of predictions? "
+    "### Conformal Prediction vs. Traditional Methods\n",
+    "\n",
+    "| Method | Distributional Assumption | Model-Agnostic | Calibration Guarantee |\n",
+    "|--------|---------------------------|----------------|----------------------|\n",
+    "| **Conformal Prediction** | None | ✓ | ✓ |\n",
+    "| Bootstrap | Parametric assumptions | ✓ | ~ |\n",
+    "| Quantile Regression | None | ✓ | ~ |\n",
+    "| Statistical Models (ARIMA, ETS) | Normal errors | ✗ | ~ |\n",
+    "\n",
+    "<Note>For a video introduction, see the [PyData Seattle presentation](https://www.youtube.com/watch?v=Bj1U-Rrxk48). More resources available in [Valery Manokhin's curated list](https://github.com/valeman/awesome-conformal-prediction).</Note>"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "::: {.callout-important}\n",
-    "## Prediction Intervals\n",
-    "For models that already provide the forecast distribution, check [Prediction Intervals](./UncertaintyIntervals).\n",
+    "## Models with Native Prediction Intervals\n",
     "\n",
-    ":::"
+    "For models that already provide forecast distributions (like AutoARIMA, AutoETS), check [Prediction Intervals](./UncertaintyIntervals). Conformal prediction is particularly useful for models that only produce point forecasts, or when you want distribution-free intervals."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Conformal Prediction\n",
+    "## How Conformal Prediction Works\n",
+    "\n",
+    "Conformal prediction uses **cross-validation** to generate prediction intervals:\n",
     "\n",
-    "For a video introduction, see the [PyData Seattle presentation](https://www.youtube.com/watch?v=Bj1U-Rrxk48).\n",
+    "1. **Split the training data** into multiple windows\n",
+    "2. **Train the model** on each window and forecast the next period\n",
+    "3. **Calculate residuals** (prediction errors) on the held-out data\n",
+    "4. **Construct intervals** using the distribution of these residuals\n",
     "\n",
-    "Multi-quantile losses and statistical models can provide provide prediction intervals, but the problem is that these are uncalibrated, meaning that the actual frequency of observations falling within the interval does not align with the confidence level associated with it. For example, a calibrated 95% prediction interval should contain the true value 95% of the time in repeated sampling. An uncalibrated 95% prediction interval, on the other hand, might contain the true value only 80% of the time, or perhaps 99% of the time. In the first case, the interval is too narrow and underestimates the uncertainty, while in the second case, it is too wide and overestimates the uncertainty. \n",
+    "The key insight: by studying how the model performs on historical data through cross-validation, we can quantify uncertainty for future predictions without assuming any particular error distribution.\n",
     "\n",
-    "Statistical methods also assume normality. Here, we talk about another method called conformal prediction that doesn't require any distributional assumptions. More information on the approach can be found in [this repo owned by Valery Manokhin](https://github.com/valeman/awesome-conformal-prediction).\n",
+    "### Real-World Applications\n",
     "\n",
-    "Conformal prediction intervals use cross-validation on a point forecaster model to generate the intervals. This means that no prior probabilities are needed, and the output is well-calibrated. No additional training is needed, and the model is treated as a black box. The approach is compatible with any model.\n",
+    "Conformal prediction is particularly valuable for:\n",
     "\n",
-    "[Statsforecast](../../index) now supports Conformal Prediction on all available models."
+    "- **Demand forecasting**: Inventory planning with quantified uncertainty\n",
+    "- **Energy prediction**: Load forecasting with reliable confidence bounds\n",
+    "- **Financial forecasting**: Risk management with calibrated intervals\n",
+    "- **Production models**: Any black-box forecasting model requiring uncertainty quantification\n",
+    "\n",
+    "[StatsForecast](../../index) implements conformal prediction for all available models, making it easy to add calibrated prediction intervals to any forecasting pipeline."
    ]
   },
   {
@@ -282,15 +317,26 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Train models\n",
+    "## Implementing Conformal Prediction in Python\n",
+    "\n",
+    "StatsForecast makes it simple to add conformal prediction to any forecasting model. We'll demonstrate with models that don't natively provide prediction intervals:\n",
+    "\n",
+    "- **[SeasonalExponentialSmoothing](../models/SimpleExponentialSmoothing)**: A simple smoothing model\n",
+    "- **[ADIDA](../models/ADIDA)**: Aggregation method for intermittent demand\n",
+    "- **[ARIMA](../models/ARIMA)**: Traditional statistical model (to show distribution-free intervals)\n",
     "\n",
-    "StatsForecast can train multiple [models](../../models/) on different time series efficiently. Most of these models can generate a probabilistic forecast, which means that they can produce both point forecasts and prediction intervals. \n",
+    "### Setting Up Conformal Intervals\n",
     "\n",
-    "For this example, we'll use [SimpleExponentialSmoothing](../models/SimpleExponentialSmoothing) and [ADIDA](../models/ADIDA) which do not provide a prediction interval natively. Thus, it makes sense to use Conformal Prediction to generate the prediction interval. \n",
+    "The key is the `ConformalIntervals` class, which requires two parameters:\n",
     "\n",
-    "We'll also show using it with [ARIMA](../models/ARIMA) to provide prediction intervals that don't assume normality.\n",
+    "- `h`: Forecast horizon (how many steps ahead to predict)\n",
+    "- `n_windows`: Number of cross-validation windows for calibration\n",
     "\n",
-    "To use these models, we first need to import them from `statsforecast.models` and then we need to instantiate them."
+    "### Parameter Requirements\n",
+    "\n",
+    "- `n_windows * h` must be less than your time series length\n",
+    "- `n_windows` should be at least 2 for reliable calibration\n",
+    "- Larger `n_windows` improves calibration but increases computation time"
    ]
   },
   {
@@ -339,10 +385,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now we're ready to generate the forecasts and the prediction intervals. To do this, we'll use the `forecast` method, which takes two arguments: \n",
+    "## Generating Forecasts with Prediction Intervals\n",
+    "\n",
+    "The `forecast` method generates both point forecasts and conformal prediction intervals:\n",
+    "\n",
+    "- `h`: Forecast horizon (number of steps ahead)\n",
+    "- `level`: List of confidence levels (e.g., `[80, 90]` for 80% and 90% intervals)\n",
     "\n",
-    "- `h`: An integer that represent the forecasting horizon. In this case, we'll forecast the next 24 hours. \n",
-    "- `level`: A list of floats with the confidence levels of the prediction intervals. For example, `level=[95]` means that the range of values should include the actual future value with probability 95%. "
+    "The output includes columns for each model's forecast and corresponding prediction interval bounds (`model-lo-{level}`, `model-hi-{level}`)."
    ]
   },
   {
@@ -541,16 +591,18 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Plot prediction intervals\n",
+    "## Visualizing Calibrated Prediction Intervals\n",
     "\n",
-    "Here we'll plot the different intervals for one timeseries. "
+    "Let's examine the prediction intervals for each model to understand their characteristics and calibration quality."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The prediction interval with the SeasonalExponentialSmoothing seen below. Even if the model generates a point forecast, we are able to get a prediction interval. The 80% prediction interval does not cross the 90% prediction interval, which is a sign that the intervals are calibrated."
+    "### SeasonalExponentialSmoothing: Well-Calibrated Intervals\n",
+    "\n",
+    "The conformal prediction intervals show proper nesting: the 80% interval is contained within the 90% interval, indicating well-calibrated uncertainty quantification. Even though this model only produces point forecasts, conformal prediction successfully generates meaningful prediction intervals."
    ]
   },
   {
@@ -578,7 +630,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For weaker fitting models, the conformal prediction interval can be larger. A better model corresponds to a narrower interval."
+    "### ADIDA: Wider Intervals for Weaker Models\n",
+    "\n",
+    "Models with higher prediction errors produce wider conformal intervals. This is a feature, not a bug: the interval width honestly reflects the model's uncertainty. A better-fitting model will produce narrower, more informative intervals."
    ]
   },
   {
@@ -606,7 +660,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "ARIMA is an example of a model that provides a forecast distribution, but we can still use conformal prediction to generate the prediction interval. As mentioned earlier, this method has the benefit of not assuming normality."
+    "### ARIMA: Distribution-Free Alternative\n",
+    "\n",
+    "ARIMA models typically provide prediction intervals assuming normally distributed errors. By using conformal prediction, we get distribution-free intervals that don't rely on this assumption, which is valuable when the normality assumption is questionable."
    ]
   },
   {
@@ -634,9 +690,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## StatsForecast Object\n",
+    "## Alternative: Setting Conformal Intervals on StatsForecast Object\n",
     "\n",
-    "Alternatively, the prediction interval can be defined on the StatsForecast object. This will apply to all models that don't have the `prediction_intervals` defined."
+    "You can apply conformal prediction to all models at once by specifying `prediction_intervals` in the `StatsForecast` object. This is convenient when you want the same conformal setup for multiple models."
    ]
   },
   {
@@ -783,11 +839,29 @@
     "\n",
     "- Exploring larger datasets\n",
     "- Incorporating industry-specific examples\n",
-    "- Investigating specialized methods like the jackknife+ that are closely related to conformal prediction (for details on the jackknife+ see [here](https://valeman.medium.com/jackknife-a-swiss-knife-of-conformal-prediction-for-regression-ce3b56432f4f)).\n",
+    "- Investigating specialized methods like the jackknife+ that are closely related to conformal prediction (for details on the jackknife+ see [here](https://valeman.medium.com/jackknife-a-swiss-knife-of-conformal-prediction-for-regression-ce3b56432f4f))\n",
     "\n",
     "If you're interested in any of these, or in any other related topic, please let us know by opening an issue on [GitHub](https://github.com/Nixtla/statsforecast/issues)\n",
     "\n",
+    "## Key Takeaways\n",
+    "\n",
+    "### Summary: Conformal Prediction for Time Series\n",
+    "\n",
+    "- **Model-agnostic**: Works with any forecasting model in Python  \n",
+    "- **Distribution-free**: No normality assumptions required  \n",
+    "- **Well-calibrated**: Theoretical coverage guarantees  \n",
+    "- **Easy to implement**: Just add `ConformalIntervals` to your StatsForecast models  \n",
+    "- **Flexible**: Apply to individual models or all models at once\n",
+    "\n",
+    "**Next steps:**\n",
+    "\n",
+    "- Try conformal prediction on your own forecasting problems\n",
+    "- Experiment with different `n_windows` values for optimal calibration\n",
+    "- Compare with native prediction intervals from statistical models\n",
+    "- Explore [advanced uncertainty quantification methods](./UncertaintyIntervals)\n",
+    "\n",
     "## Acknowledgements\n",
+    "\n",
     "We would like to thank [Kevin Kho](https://github.com/kvnkho) for writing this tutorial, and Valeriy [Manokhin](https://github.com/valeman) for his expertise on conformal prediction, as well as for promoting this work."
    ]
   },