Run load reduction scenarios and compare predicted water quality responses

ok_scenario() takes a baseline ok_load() result and runs the full pipeline under one or more alternative loading scenarios, returning a tidy comparison table of predicted water quality across all scenarios. This is the primary tool for nutrient management planning - answering "how much does TP need to be reduced to move this lake from eutrophic to mesotrophic?"

Usage

ok_scenario(
  baseline,
  scenarios,
  include_baseline = TRUE,
  target_tsi = NULL,
  target_class = NULL
)

Arguments

baseline: An okBATHTUB object that has been run through at least ok_hydraulics(). All morphometry is taken from this object.
scenarios: A list of named lists, one per scenario. Each list must have a label (character, required). Optional fields: tp_reduction (numeric 0-1, fractional TP reduction), tn_reduction (numeric 0-1, fractional TN reduction), tp_inflow_ugl (numeric, absolute inflow TP in ug/L, overrides tp_reduction), tn_inflow_ugl (numeric, absolute inflow TN in ug/L), flow_change (numeric, fractional change in inflow volume, e.g. -0.20 = 20% flow reduction).
include_baseline: Logical. Whether to include the baseline run as the first row in the output. Default TRUE.
target_tsi: Numeric. Optional TSI target. If supplied, a meets_target column is added. Default NULL.
target_class: Character. One of "oligotrophic", "mesotrophic", or "eutrophic". Sets target_tsi to the upper bound of that class automatically.

Value

A data frame with one row per scenario (plus baseline if requested). Columns include: scenario (label), tp_inflow_ugl (inflow TP in ug/L), tp_reduction_pct (reduction from baseline in percent), tp_inlake_ugl (predicted in-lake TP), chla_ugl (predicted chlorophyll-a), secchi_m (predicted Secchi depth), tsi_tp, tsi_chla, tsi_mean (Carlson TSI values), trophic_state (classification), and optionally meets_target (logical, present when target_tsi is supplied).

How scenarios work

Each scenario modifies one or more inflow parameters relative to the baseline. Reductions are expressed as fractions (0-1), where tp_reduction = 0.30 means a 30% reduction in inflow TP load. Scenarios can also specify absolute concentrations directly via tp_inflow_ugl, which overrides the reduction fraction.

The morphometric parameters (surface area, mean depth) from the baseline ok_hydraulics() call are applied to every scenario.

Examples

# Baseline: Arcadia Lake with estimated inflow loading
baseline <- ok_load(
  inflow_m3yr   = 45e6,
  tp_inflow_ugl = 120,
  tn_inflow_ugl = 1800,
  segment_label = "lacustrine",
  coefficients  = "oklahoma",
  ecoregion     = "Cross Timbers"
) |>
ok_hydraulics(surface_area_ha = 890, mean_depth_m = 4.2)

# Scenario analysis: what TP reduction gets us to mesotrophic?
scenarios <- list(
  list(label = "10% TP reduction",  tp_reduction = 0.10),
  list(label = "20% TP reduction",  tp_reduction = 0.20),
  list(label = "30% TP reduction",  tp_reduction = 0.30),
  list(label = "40% TP reduction",  tp_reduction = 0.40),
  list(label = "50% TP reduction",  tp_reduction = 0.50)
)

results <- ok_scenario(
  baseline      = baseline,
  scenarios     = scenarios,
  target_class  = "mesotrophic"
)
print(results)
#>           scenario tp_inflow_ugl tp_reduction_pct tn_inflow_ugl tp_inlake_ugl
#> 1         Baseline           120                0          1800          44.2
#> 2 10% TP reduction           108               10          1800          41.4
#> 3 20% TP reduction            96               20          1800          38.5
#> 4 30% TP reduction            84               30          1800          35.4
#> 5 40% TP reduction            72               40          1800          32.0
#> 6 50% TP reduction            60               50          1800          28.5
#>   tp_retention_pct tn_inlake_ugl chla_ugl secchi_m tsi_tp tsi_chla tsi_secchi
#> 1             63.2         803.8    20.18     0.53   58.8     60.1       69.2
#> 2             61.7         803.8    19.35     0.54   57.8     59.7       68.8
#> 3             59.9         803.8    18.46     0.56   56.8     59.2       68.4
#> 4             57.9         803.8    17.49     0.57   55.6     58.7       68.0
#> 5             55.5         803.8    16.42     0.60   54.1     58.1       67.5
#> 6             52.5         803.8    15.21     0.62   52.4     57.3       66.9
#>   tsi_mean trophic_state hrt_yr                    coeff_source target_tsi
#> 1     62.7     Eutrophic  0.831 oklahoma_ecoregion_crosstimbers         50
#> 2     62.1     Eutrophic  0.831 oklahoma_ecoregion_crosstimbers         50
#> 3     61.5     Eutrophic  0.831 oklahoma_ecoregion_crosstimbers         50
#> 4     60.7     Eutrophic  0.831 oklahoma_ecoregion_crosstimbers         50
#> 5     59.9     Eutrophic  0.831 oklahoma_ecoregion_crosstimbers         50
#> 6     58.9     Eutrophic  0.831 oklahoma_ecoregion_crosstimbers         50
#>   meets_target
#> 1        FALSE
#> 2        FALSE
#> 3        FALSE
#> 4        FALSE
#> 5        FALSE
#> 6        FALSE