---
title: "Weight Functions (Kernels)"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Weight Functions (Kernels)}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<!-- markdownlint-disable MD024 -->

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

## Overview

Weight functions (kernels) determine how neighboring points contribute
to each local fit. Points closer to the target receive higher weights.

![Weight function comparison](../man/figures/kernel_comparison.svg)

---

## Available Kernels

| Kernel | Efficiency | Smoothness | Support |
| --- | --- | --- | --- |
| **Tricube** | 0.998 | Very smooth | Compact |
| **Epanechnikov** | 1.000 | Smooth | Compact |
| **Gaussian** | 0.961 | Infinite | Unbounded |
| **Biweight** | 0.995 | Very smooth | Compact |
| **Cosine** | 0.999 | Smooth | Compact |
| **Triangle** | 0.989 | Moderate | Compact |
| **Uniform** | 0.943 | None | Compact |

**Efficiency** = AMISE relative to Epanechnikov (1.0 = optimal)

---

## Tricube (Default)

Cleveland's original choice. Best all-around performance.

$$w(u) = (1 - |u|^3)^3$$

**Use when**: Default choice for most applications.

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

model <- Lowess(weight_function = "tricube")
result <- fit(model, x, y)
cat("Smoothed y[0]:", result$y[1], "\n")
```

---

## Epanechnikov

Theoretically optimal for kernel density estimation.

$$w(u) = \frac{3}{4}(1 - u^2)$$

**Use when**: Optimal MSE properties desired.

```{r kernels_2}
model <- Lowess(weight_function = "epanechnikov")
result <- fit(model, x, y)
cat("Smoothed y[0]:", result$y[1], "\n")
```

---

## Gaussian

Infinitely smooth. No boundary effects.

$$w(u) = \exp(-u^2/2)$$

**Use when**: Maximum smoothness needed, computational cost acceptable.

```{r kernels_3}
model <- Lowess(weight_function = "gaussian")
result <- fit(model, x, y)
cat("Smoothed y[0]:", result$y[1], "\n")
```

---

## Biweight

Good balance of efficiency and smoothness.

$$w(u) = (1 - u^2)^2$$

**Use when**: Alternative to Tricube with slightly different properties.

```{r kernels_4}
model <- Lowess(weight_function = "biweight")
result <- fit(model, x, y)
cat("Smoothed y[0]:", result$y[1], "\n")
```

---

## Cosine

Smooth and computationally efficient.

$$w(u) = \cos(\pi u / 2)$$

**Use when**: Want smooth kernel with simple form.

```{r kernels_5}
model <- Lowess(weight_function = "cosine")
result <- fit(model, x, y)
cat("Smoothed y[0]:", result$y[1], "\n")
```

---

## Triangle

Simple linear taper.

$$w(u) = 1 - |u|$$

**Use when**: Simple, interpretable weights.

```{r kernels_6}
model <- Lowess(weight_function = "triangle")
result <- fit(model, x, y)
cat("Smoothed y[0]:", result$y[1], "\n")
```

---

## Uniform

Equal weights within window. Fastest but least smooth.

$$w(u) = 1$$

**Use when**: Speed is critical, smoothness less important.

```{r kernels_7}
model <- Lowess(weight_function = "uniform")
result <- fit(model, x, y)
cat("Smoothed y[0]:", result$y[1], "\n")
```

---

## Choosing a Kernel

Choose the first row below whose condition applies:

| Condition | Kernel |
| --- | --- |
| Need maximum smoothness | `"gaussian"` |
| Default is acceptable | `"tricube"` |
| Need optimal asymptotic MSE | `"epanechnikov"` |
| Speed is critical | `"uniform"` |
| None of the above | `"biweight"` |

> **Recommendation:** Stick with **Tricube** (default) unless you have
> specific requirements. The differences between kernels are usually
> small in practice.

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