---
title: "Confidence and Prediction Intervals"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Confidence and Prediction Intervals}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<!-- markdownlint-disable MD024 -->

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

## Overview

![Confidence and prediction intervals](../man/figures/intervals_comparison.svg)

> **Adapter support:** Batch and Streaming support confidence and prediction
> intervals; Online supports them in `update_mode = "full"` only.

| Type | Represents | Width | Use |
| --- | --- | --- | --- |
| **Confidence** | Uncertainty in mean curve | Narrow | Where is the trend? |
| **Prediction** | Uncertainty for new points | Wide | Where will data fall? |

---

## Confidence Intervals

Estimate uncertainty in the smoothed curve itself.

```{r intervals_1}
library(rfastloess)
set.seed(42)
x <- seq(0, 2 * pi, length.out = 100)
y <- sin(x) + rnorm(100, sd = 0.3)

model <- Loess(fraction = 0.5, intervals = intervals_opts(confidence = 0.95))
result <- fit(model, x, y)

# Plot with bands
plot(x, y, pch = 16, col = "gray",
    main = "LOESS with 95% Confidence Intervals")
lines(result$x, result$y, col = "blue", lwd = 2)
lines(result$x, result$confidence_lower, col = "blue", lty = 2)
lines(result$x, result$confidence_upper, col = "blue", lty = 2)

cat("95% CI at midpoint: [", result$confidence_lower[50], ", ",
    result$confidence_upper[50], "]\n")
```

---

## Prediction Intervals

Estimate where new observations might fall.

```{r intervals_2}
library(rfastloess)
set.seed(42)
x <- seq(0, 2 * pi, length.out = 100)
y <- sin(x) + rnorm(100, sd = 0.3)

model <- Loess(fraction = 0.5, intervals = intervals_opts(prediction = 0.95))
result <- fit(model, x, y)

plot(x, y, pch = 16, col = "gray",
    main = "LOESS with 95% Prediction Intervals")
lines(result$x, result$y, col = "blue", lwd = 2)
lines(result$x, result$prediction_lower, col = "red", lty = 2)
lines(result$x, result$prediction_upper, col = "red", lty = 2)

cat("Prediction bounds: [", result$prediction_lower[1], ", ",
    result$prediction_upper[1], "]\n")
```

---

## Both Intervals

Request both types simultaneously:

```{r intervals_3}
library(rfastloess)
set.seed(42)
x <- seq(0, 2 * pi, length.out = 100)
y <- sin(x) + rnorm(100, sd = 0.3)

model <- Loess(
    fraction = 0.5,
    intervals = intervals_opts(confidence = 0.95, prediction = 0.95)
)
result <- fit(model, x, y)

plot(x, y, pch = 16, col = "gray",
    main = "Confidence vs Prediction Intervals")
lines(result$x, result$y, col = "blue", lwd = 2)

# Confidence interval (narrow, blue)
lines(result$x, result$confidence_lower, col = "blue", lty = 2)
lines(result$x, result$confidence_upper, col = "blue", lty = 2)

# Prediction interval (wide, red)
lines(result$x, result$prediction_lower, col = "red", lty = 3)
lines(result$x, result$prediction_upper, col = "red", lty = 3)

legend("topright",
        c("Data", "Smoothed", "95% CI", "95% PI"),
        pch = c(16, NA, NA, NA), lty = c(NA, 1, 2, 3),
        col = c("gray", "blue", "blue", "red"))

cat("95% CI at midpoint: [", result$confidence_lower[50], ", ",
    result$confidence_upper[50], "]\n")
```

---

## Confidence Levels

Common levels and their z-values:

| Level | z-value | Interpretation |
| --- | --- | --- |
| 0.90 | 1.645 | 90% of intervals contain true value |
| 0.95 | 1.960 | 95% of intervals contain true value |
| 0.99 | 2.576 | 99% of intervals contain true value |

```{r intervals_4}
# 99% confidence interval
model <- Loess(fraction = 0.5, intervals = intervals_opts(confidence = 0.99))
result <- fit(model, x, y)
cat("First lower CI bound (99%):", result$confidence_lower[1], "\n")
```

---

## Standard Errors

Access standard errors directly (available when intervals are computed):

```{r intervals_5}
model <- Loess(fraction = 0.5, outputs = "se")
result <- fit(model, x, y)
cat("Standard errors (first 5):", head(result$standard_errors, 5), "\n")
```

---

## Availability

> **Adapter support:** Confidence and prediction intervals are available in
> Batch and Streaming; Online supports them in `update_mode = "full"` only.
> intervals.

| Feature | Batch | Streaming | Online |
| --- | --- | --- | --- |
| Confidence intervals | ✓ | ✗ | ✗ |
| Prediction intervals | ✓ | ✗ | ✗ |
| Standard errors | ✓ | ✗ | ✗ |

```{r session-info}
sessionInfo()
```