---
title: "Validation of lakefetch Calculations"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Validation of lakefetch Calculations}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

The `lakefetch` package has been validated through three complementary approaches:

1. **Analytical validation** - Testing against synthetic lakes with known geometry
2. **Literature validation** - Comparing results to lakes with published morphometry
3. **Edge case validation** - Testing challenging geometries (islands, complex shorelines)

All validation scripts are included in the package under `inst/validation/`.

## Analytical Validation

Analytical validation uses synthetic lake geometries where the expected fetch values
can be calculated mathematically. This provides the most rigorous test of algorithm
correctness.

### Test Cases

| Test | Geometry | Expected | Result |
|------|----------|----------|--------|
| Circular lake center | r=1000m, point at center | 1000m all directions | PASS (0% error) |
| Circular lake edge | r=1000m, point 800m from center | Min: 200m, Max: 1800m | PASS (0% error) |
| Rectangular lake N/S | 2000x1000m, center point | 500m | PASS (0% error) |
| Rectangular lake E/W | 2000x1000m, center point | 1000m | PASS (0% error) |
| Effective fetch | Circular center, top 3 mean | 1000m | PASS (0% error) |

### Running Analytical Validation

```{r analytical}
source(system.file("validation", "validate_fetch.R", package = "lakefetch"))
```

## Literature Validation

Literature validation compares fetch calculations against real lakes with published
morphometry data from the World Lake Database (ILEC) and state limnology surveys.

### Test Lakes

| Lake | State | Published Area | Calculated Area | Result |
|------|-------|---------------|-----------------|--------|
| Lake Sunapee | NH | 16.7 km² | 16.85 km² | PASS |
| Cayuga Lake | NY | 172 km² | 173.87 km² | PASS |
| Green Lake | WI | 29.6 km² | 32.66 km² | PASS |

### Validation Approach

For each lake:

1. Download boundary from OpenStreetMap
2. Calculate fetch at the lake centroid
3. Compare max fetch to half the published maximum length
4. Compare mean fetch to expected range based on lake shape

Cayuga Lake (a Finger Lake) correctly hit the 50 km fetch cap, demonstrating proper
handling of very elongated lakes.

### Running Literature Validation

```{r literature}
source(system.file("validation", "validate_literature.R", package = "lakefetch"))
```

## Edge Case Validation

Edge case validation tests challenging geometries that could cause algorithm failures.

### Test Cases

| Test | Geometry | Key Finding | Result |
|------|----------|-------------|--------|
| Central island | Island at lake center | Rays correctly stop at island | PASS |
| Offset island | Island 800m north of center | North rays blocked at 500m | PASS |
| Complex shoreline | Sinusoidal variation ±300m | Fetch varies 1119-1881m | PASS |
| Multiple islands | 3 islands at different positions | Each blocks rays independently | PASS |
| Very large lake | Lake Erie | OSM limitation* | SKIPPED |

*Great Lakes require pre-downloaded shapefiles due to OSM bounding box limitations.

### Key Validations

- **Islands work correctly**: Fetch rays stop at island boundaries, not pass through
- **Complex shorelines handled**: Bays and peninsulas produce expected directional variation
- **Multiple islands supported**: Each island independently blocks rays in its direction

### Running Edge Case Validation

```{r edge_cases}
source(system.file("validation", "validate_edge_cases.R", package = "lakefetch"))
```

## Methodology Alignment

The `lakefetch` package implements fetch calculation following established standards:

### Shore Protection Manual (USACE, 1984)

The Shore Protection Manual defines effective fetch using radial measurements weighted
by direction. `lakefetch` uses a similar ray-casting approach with configurable
angular resolution (default 5°).
### Mason et al. (2018)

Mason et al. used a comparable ray-casting approach to create effective fetch maps
for the Great Lakes at 30m resolution. Their methodology was validated against
USACE Wave Information Studies (R² = 0.635).

### Effective Fetch Calculation

`lakefetch` calculates effective fetch as the mean of the top 3 directional fetch
values. This provides a robust exposure metric independent of specific wind direction,
suitable for ecological applications where wind patterns may vary.

## Unit Tests

In addition to validation scripts, the package includes 79 formal unit tests using
the `testthat` framework:

| Test File | Tests | Coverage |
|-----------|-------|----------|
| test-fetch_core.R | 18 | Core algorithm, analytical validation |
| test-data_loading.R | 25 | Input handling, column detection |
| test-options.R | 24 | Configuration management |
| test-visualization.R | 12 | Plotting functions |

Run tests with:

```{r tests}
devtools::test()
```

## R CMD Check Status

The package passes R CMD check with:

- 0 errors
- 0 warnings
- 1 note (system time check - acceptable for CRAN)

## Summary

The validation suite demonstrates that `lakefetch`:

1. **Correctly calculates fetch** - 0% error against analytical solutions
2. **Handles real-world lakes** - Results match published morphometry
3. **Manages complex geometries** - Islands and irregular shorelines handled correctly
4. **Follows established methods** - Consistent with SPM and published literature

## References
- Mason, L.A., Riseng, C.M., Layman, A.J., Jensen, R. (2018). Effective fetch and
  relative exposure index maps for the Laurentian Great Lakes. Scientific Data
  5:180295. doi:10.1038/sdata.2018.295

- U.S. Army Corps of Engineers (1984). Shore Protection Manual, 4th ed.

- Håkanson, L.A. (1981). A Manual of Lake Morphometry. Springer-Verlag.