---
title: "LOESS Concepts"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{LOESS Concepts}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<!-- markdownlint-disable MD024 -->

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

## What is LOESS?

**LOESS** (Locally Estimated Scatterplot Smoothing) is a nonparametric
regression method that fits smooth curves through scatter plots without assuming
a global functional form.

Unlike parametric methods (linear regression, polynomial fitting), LOESS adapts
locally to the data structure, making it ideal for:

- **Exploratory data analysis** — Discover patterns without assumptions
- **Trend estimation** — Extract signals from noisy time series
- **Baseline correction** — Remove systematic effects in spectroscopy
- **Genomic smoothing** — Smooth methylation, ChIP-seq, or expression data

---

## How It Works

![LOESS smoothing concept](../man/figures/loess_concept.svg)

For each point in your data, LOESS:

1. **Selects neighbors** — Choose the nearest points (controlled by `fraction`)
2. **Assigns weights** — Closer points get higher weights (using a kernel
   function)
3. **Fits locally** — Perform weighted least squares regression
4. **Extracts value** — Use the fitted value as the smoothed estimate
5. **Iterates** (optional) — Reweight points based on residuals to reduce
   outlier influence

---

## The Fraction Parameter

The `fraction` (also called bandwidth or span) is the most important parameter.
It controls what proportion of data is used for each local fit.

![Effect of the fraction parameter](../man/figures/fraction_comparison.svg)

| Fraction | Effect | When to Use |
| --- | --- | --- |
| **0.1–0.3** | Fine detail, follows data closely | Rapidly changing signals |
| **0.3–0.5** | Balanced smoothing | Most applications |
| **0.5–0.7** | Heavy smoothing | Noisy data, trend extraction |
| **0.7–1.0** | Very smooth | Strong noise, global trends |

> **Tip:** Start with `fraction=0.67` (the default) and adjust based on visual
> inspection. Use cross-validation for automated selection.

---

## Robustness Iterations

Standard LOESS is sensitive to outliers. **Robustness iterations** downweight
points with large residuals:

![Effect of robustness iterations](../man/figures/robust_iter_comparison.svg)

| Iterations | Effect | When to Use |
| --- | --- | --- |
| 0 | No robustness (fastest) | Clean data, speed-critical |
| 1–3 | Moderate | Most applications |
| 4–6 | Strong | Data with clear outliers |
| 7+ | Very strong | Heavy contamination |

---

## Confidence vs Prediction Intervals

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

| Interval Type | What It Represents | Width |
| --- | --- | --- |
| **Confidence** | Uncertainty in the *mean curve* | Narrow |
| **Prediction** | Uncertainty for *new observations* | Wide |

- Use **confidence intervals** to show where the true trend likely lies
- Use **prediction intervals** to show where new data points might fall

---

## Execution Modes

| Mode | Use Case | Memory | Features |
| --- | --- | --- | --- |
| **Batch** | Complete datasets | Entire dataset | All features |
| **Streaming** | >100K points | One chunk | Residuals, robustness |
| **Online** | Real-time data | Fixed window | Incremental updates |

---

## Quick Decision Guide

| Situation | Mode |
| --- | --- |
| Data fits in memory; needs intervals or CV | Batch |
| Data too large for memory or arrives in chunks | Streaming |
| Data arrives point-by-point in real time | Online |

---

## Key Advantages

| Feature | LOESS | Polynomial Regression | Moving Average |
| --- | --- | --- | --- |
| No parametric assumptions | ✓ | ✗ | ✓ |
| Adapts to local structure | ✓ | ✗ | Partial |
| Robust to outliers | ✓ | ✗ | ✗ |
| Uncertainty estimates | ✓ | ✓ | ✗ |
| Handles irregular sampling | ✓ | ✓ | ✗ |
| Multivariate predictors | ✓ | ✓ | ✗ |
| Adjustable polynomial degree | ✓ (0–4) | ✓ | ✗ |

---

## Next Steps

- `vignette("quickstart", package = "rfastloess")` — See it in action
- `?Loess` — All configuration options
- `vignette("degree", package = "rfastloess")` — Constant, linear,
  quadratic fits
- `vignette("dimensions", package = "rfastloess")` — 2D and n-D smoothing
- `vignette("boundary", package = "rfastloess")` — Edge bias reduction
  strategies
- `vignette("robustness", package = "rfastloess")` — Outlier
  downweighting methods
- `vignette("scaling", package = "rfastloess")` — MAD, MAR, Mean scale
  estimation
- `vignette("merge", package = "rfastloess")` — Chunk reconciliation in
  Streaming mode

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