---
title: "Oklahoma Reservoir Workflow"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Oklahoma Reservoir Workflow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse  = TRUE,
  comment   = "#>",
  fig.width = 7,
  fig.height = 5,
  dpi       = 120
)
```

## Overview

This vignette demonstrates Oklahoma-focused workflows with okBATHTUB:

1. Looking up reservoir morphometry from the bundled dataset
2. Selecting appropriate coefficient sets for different ecoregions
3. Comparing model predictions to observed monitoring data
4. Multi-segment reservoir modelling
5. Load reduction scenario analysis

```{r load}
library(okBATHTUB)
```

## Reservoir lookup

The bundled `ok_reservoirs` dataset includes morphometric data for major
Oklahoma reservoirs compiled from publicly available sources (USACE
Tulsa District design memoranda, U.S. Bureau of Reclamation design
data, the National Inventory of Dams, and published OWRB reports).

```{r summary}
ok_reservoir_summary()
```

Look up any reservoir by name (partial or exact match):

```{r lookup}
# Partial match
ok_reservoir("Tenkiller")[, c("lake_name", "surface_area_ha", "mean_depth_m",
                              "eco_l3_name")]

# Filter by ecoregion
ct <- ok_reservoir(ecoregion = "Cross Timbers")
nrow(ct)
head(ct[, c("lake_name", "surface_area_ha", "mean_depth_m")], 5)
```

## Choosing a coefficient set

Three coefficient families are supported:

| Set            | Retention model        | Chl-a / Secchi             |
|----------------|------------------------|----------------------------|
| `"walker"`     | Walker BATHTUB Model 1 | Walker (1985) national     |
| `"vollenweider"` | Vollenweider/Larsen-Mercier | Walker (1985) national |
| `"oklahoma"`   | Walker BATHTUB Model 1 | Oklahoma ecoregion-specific|

For Oklahoma reservoirs, `"oklahoma"` is generally preferred because the
Chl-a / Secchi regressions are calibrated to Oklahoma data. The
retention model is still Walker Model 1, which is the canonical default
in the BATHTUB program and is calibrated to U.S. Army Corps of
Engineers reservoir data — many Oklahoma reservoirs are Corps projects,
so this is appropriate.

If you have reason to prefer a simpler retention model (no ortho-P /
total-P data, very rough screening, or comparison to legacy results),
`"vollenweider"` is available. Be aware that this form is *not*
calibrated to Corps of Engineers reservoir data.

## Worked example: Arcadia Lake

Arcadia Lake is a 716 ha Cross Timbers reservoir managed by the City of
Edmond for water supply. Suppose we have estimated tributary loads
from a watershed model:

```{r arcadia_inputs}
arcadia <- ok_reservoir("Arcadia Lake", exact = TRUE)

result <- ok_load(
    inflow_m3yr   = 45e6,    # ~36,500 acre-feet/yr
    tp_inflow_ugl = 120,     # flow-weighted mean TP
    tn_inflow_ugl = 1800,    # flow-weighted mean TN
    coefficients  = "oklahoma",
    ecoregion     = "Cross Timbers"
  ) |>
  ok_hydraulics(
    surface_area_ha = arcadia$surface_area_ha,
    mean_depth_m    = arcadia$mean_depth_m
  ) |>
  ok_retention() |>
  ok_inlake()    |>
  ok_tsi()

summary(result)
```

## Comparing to observed monitoring data

If you have observed in-lake monitoring data, use `ok_tsi_observed()`
to compute observed TSI and compare to predictions:

```{r compare_observed}
# Suppose lake monitoring data summary for Arcadia gives these
# growing-season means:
obs <- ok_tsi_observed(
  tp_ugl   = 56,
  chla_ugl = 18,
  secchi_m = 0.95
)

cat("--- Predicted (okBATHTUB) vs Observed ---\n")
cat(sprintf("TP    : pred = %5.1f, obs = %5.1f ug/L\n",
            result$data$tp_inlake_ugl, 56))
cat(sprintf("Chl-a : pred = %5.2f, obs = %5.2f ug/L\n",
            result$data$chla_ugl, 18))
cat(sprintf("Secchi: pred = %5.2f, obs = %5.2f m\n",
            result$data$secchi_m, 0.95))
cat(sprintf("TSI   : pred = %5.1f, obs = %5.1f\n",
            result$data$tsi_mean, obs$tsi_mean))
```

The predicted-vs-observed comparison is the most important diagnostic
for any empirical model. Persistent biases in one direction may indicate
that the model coefficients need site-specific calibration: pass a
custom named list as `coefficients` to `ok_load()` if you have
sufficient data to fit your own.

## Multi-segment reservoir modelling

Reservoirs with strong longitudinal gradients (Tenkiller, Eufaula, and
Texoma are classic Oklahoma examples) are often best modelled as a
series of well-mixed segments. Each segment's outflow feeds the next
segment's inflow:

```{r multi_segment}
# A simple 3-segment Tenkiller-like reservoir
result <- ok_segment_chain(
  inflow_m3yr   = 1e9,
  tp_inflow_ugl = 110,
  tn_inflow_ugl = 1700,
  segments = list(
    list(label = "riverine",    surface_area_ha = 1200, mean_depth_m = 4),
    list(label = "transition",  surface_area_ha = 1800, mean_depth_m = 9),
    list(label = "lacustrine",  surface_area_ha = 2060, mean_depth_m = 25)
  ),
  coefficients = "oklahoma",
  ecoregion    = "Ouachita Mountains"
)

ok_segment_summary(result)
```

In-lake TP decreases moving down-reservoir as nutrients settle, which
is the expected pattern for an unstratified-to-stratified reservoir
gradient.

## Load reduction scenarios

Use `ok_scenario_sweep()` to evaluate a range of nutrient load
reductions and identify the reduction needed to meet a TSI target:

```{r scenario, fig.height=5, eval=requireNamespace("ggplot2", quietly=TRUE)}
baseline <- ok_load(
    inflow_m3yr   = 45e6,
    tp_inflow_ugl = 120,
    coefficients  = "oklahoma",
    ecoregion     = "Cross Timbers"
  ) |>
  ok_hydraulics(surface_area_ha = 716, mean_depth_m = 4.6)

sweep <- ok_scenario_sweep(
  baseline,
  max_reduction_pct = 60,
  step_pct          = 10
)

# Print key columns
print(sweep[, c("tp_reduction_pct", "tp_inflow_ugl",
                "tp_inlake_ugl", "chla_ugl", "tsi_mean",
                "trophic_state")],
      row.names = FALSE)
```

## References

- Carlson, R.E. (1977). A trophic state index for lakes.
  *Limnology and Oceanography*, 22(2), 361-369.
- Walker, W.W. (1985). Empirical methods for predicting eutrophication
  in impoundments; Report 3, Phase III: Model refinements. Technical
  Report E-81-9, U.S. Army Engineer Waterways Experiment Station.
- Walker, W.W. (1996). *Simplified Procedures for Eutrophication
  Assessment and Prediction: User Manual*. Instruction Report W-96-2,
  U.S. Army Engineer Waterways Experiment Station.