---
title: "Choosing an Execution Mode"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Choosing an Execution Mode}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<!-- markdownlint-disable MD024 -->

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

`rfastlowess` provides three execution modes for different data sizes and
processing needs:

![Execution mode comparison](../man/figures/adapter_comparison.svg)

| Mode | Class | Use Case | Memory | Key Features |
| --- | --- | --- | --- | --- |
| **Batch** | `Lowess` | Full dataset | Entire dataset | CI, PI, CV, GPU |
| **Streaming** | `StreamingLowess` | >100K points | Per chunk | With overlap |
| **Online** | `OnlineLowess` | Live / real-time | Sliding window | Per-point |

## 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 |

---

## Batch Adapter

Standard mode for complete datasets. **Supports all features.**

### When to Use

- Dataset fits in memory
- Need intervals, cross-validation, or diagnostics
- Processing complete files

### Example

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

model <- Lowess(
    fraction = 0.5,
    iterations = 3,
    parallel = TRUE,
    outputs = "diagnostics",
    intervals = intervals_opts(confidence = 0.90, prediction = 0.99)
)
result <- fit(model, x, y)
cat("95% CI at midpoint: [", result$confidence_lower[50], ", ",
    result$confidence_upper[50], "]\n")
```

---

## Streaming Adapter

Process large datasets in chunks with configurable overlap.

### When to Use

- Dataset >100,000 points
- Memory-constrained environments
- Batch processing pipelines

### Parameters

| Parameter | Default | Description |
| --- | --- | --- |
| `chunk_size` | 5000 | Points per chunk |
| `overlap` | `chunk_size / 10` | Overlap between chunks |
| `merge_strategy` | `"weighted_average"` | How to merge overlaps |

### Merge Strategies

| Strategy | Behavior |
| --- | --- |
| `"average"` | Average overlapping values |
| `"weighted_average"` | Distance-weighted blend |
| `"take_first"` | Keep left chunk values |
| `"take_last"` | Keep right chunk values |

### Example

```{r streaming_adapter}
library(rfastlowess)
x <- seq(0, 2 * pi, length.out = 100)
y <- sin(x) + 0.1

model <- StreamingLowess(
    fraction = 0.3,
    iterations = 2,
    chunk_size = 5000,
    overlap = 500,
    merge_strategy = "average"
)
process_chunk(model, x, y)
result <- finalize(model)
cat("Smoothed y[0]:", result$y[1], "\n")
```

> **Always call finalize():** The streaming adapter buffers overlap
> data. Call `finalize(model)` after the last chunk to retrieve the
> buffered tail.

---

## Online Adapter

Incremental updates with a sliding window for real-time data.

### When to Use

- Data arrives incrementally (sensors, streams)
- Need real-time smoothed values
- Fixed memory budget

### Parameters

| Parameter | Default | Description |
| --- | --- | --- |
| `window_capacity` | 1000 | Max points in window |
| `min_points` | 2 | Points before output starts |
| `update_mode` | `"incremental"` | Update strategy |

### Update Modes

| Mode | Behavior | Speed |
| --- | --- | --- |
| `"incremental"` | Update only affected fits | Faster |
| `"full"` | Recompute entire window | More accurate |

### Example

```{r online_adapter}
library(rfastlowess)
x <- seq(0, 2 * pi, length.out = 100)
y <- sin(x) + 0.1

model <- OnlineLowess(
    fraction = 0.2,
    window_capacity = 100,
    min_points = 5,
    update_mode = "incremental"
)
shown <- 0
for (i in seq_along(x)) {
    result <- add_point(model, x[i], y[i])
    if (!is.null(result) && shown < 5) {
        cat("Current smoothed value:", result$y, "\n")
        shown <- shown + 1
    }
}
```

---

## Feature Comparison

| Feature | Batch | Streaming | Online |
| --- | --- | --- | --- |
| Parallel execution | ✓ | ✓ | ✗ |
| Diagnostics | ✓ | ✓ | ✗ |
| Residuals | ✓ | ✓ | ✓ |
| Robustness weights | ✓ | ✓ | ✓ |
| Confidence intervals | ✓ | ✗ | ✗ |
| Prediction intervals | ✓ | ✗ | ✗ |
| Cross-validation | ✓ | ✗ | ✗ |

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