---
title: "Run an experiment with cumba_experiment()"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Run an experiment with cumba_experiment()}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# When to use `cumba_experiment()`

Use `cumba_experiment()` when you have **observed experiments** with
their actual irrigation schedule and you want CUMBA to reproduce them.
This is the function used during **model calibration** against
yield/Brix observations.

The companion function `cumba_scenario()` is meant for *what-if*
deficit-irrigation studies, where irrigation is triggered automatically
based on phase-specific water-stress thresholds.

# Required inputs

| Argument        | Description                                                                 |
|-----------------|-----------------------------------------------------------------------------|
| `weather`       | Daily data frame: `Site`, `Tx`, `Tn`, `P`, `DATE`, `Lat` (if `estimateRad = TRUE`) or `Rad` |
| `param`         | Named list-of-lists (e.g. `cumbaParameters`) or plain numeric data frame    |
| `irrigation_df` | Data frame with `ID`, `Site`, `YEAR`, `DATE`, `WVOL` (mm)                  |
| `estimateRad`   | `TRUE` → Hargreaves–Samani from `Lat`; `FALSE` → use `Rad` column          |
| `estimateET0`   | `TRUE` → FAO-56 Penman–Monteith; `FALSE` → use `ET0` column                |
| `irrigationEfficiency` | Fraction of applied water reaching the root zone (default `0.9`)     |
| `fullOut`       | `FALSE` → short output; `TRUE` → all internal state variables               |

# A complete walkthrough on `tomatoFoggia`

```{r run}
library(cumba)
library(dplyr)
library(ggplot2)

data(tomatoFoggia)
data(cumbaParameters)

out <- cumba_experiment(
  weather              = tomatoFoggia$weather,
  param                = cumbaParameters,
  irrigation_df        = tomatoFoggia$irrigation,
  estimateRad          = TRUE,
  estimateET0          = TRUE,
  irrigationEfficiency = 0.9,
  fullOut              = FALSE
)

head(out)
```

## Harvest-day values

Each simulation ends when the crop cycle is complete. The last row for
each (site × year × experiment) combination carries the harvest-day
yield and Brix:

```{r harvest}
harvest <- out |>
  group_by(site, year, experiment) |>
  slice_tail(n = 1) |>
  ungroup() |>
  select(site, year, experiment, yield, brix)

harvest
```

## Compare with observations

`tomatoFoggia$production` contains observed `yield_ref` (t ha⁻¹) and
`brix_ref` (°Brix). The `yield` column in the short output is in
**q ha⁻¹**, so divide by 10 to convert to t ha⁻¹:

```{r compare}
production <- tomatoFoggia$production

cmp <- harvest |>
  mutate(experiment = as.integer(experiment)) |>
  inner_join(production, by = c("experiment" = "ID")) |>
  mutate(yield_t = yield / 10)

ggplot(cmp, aes(yield_ref, yield_t)) +
  geom_abline(slope = 1, intercept = 0, linetype = 2, colour = "grey50") +
  geom_smooth(method = "lm", se = TRUE, colour = "#d6604d",
              fill = "#f4a582", linewidth = 0.8) +
  geom_point(size = 3, colour = "#2166ac", alpha = 0.85) +
  labs(x = "Observed yield (t ha⁻¹)",
       y = "Simulated yield (t ha⁻¹)",
       title = "CUMBA — yield validation") +
  theme_bw(base_size = 12)

ggplot(cmp, aes(brix_ref, brix)) +
  geom_abline(slope = 1, intercept = 0, linetype = 2, colour = "grey50") +
  geom_smooth(method = "lm", se = TRUE, colour = "#4dac26",
              fill = "#b8e186", linewidth = 0.8) +
  geom_point(size = 3, colour = "#762a83", alpha = 0.85) +
  labs(x = "Observed Brix (°Brix)",
       y = "Simulated Brix (°Brix)",
       title = "CUMBA — Brix validation") +
  theme_bw(base_size = 12)
```

## Full output for diagnostics

Pass `fullOut = TRUE` to access every internal state variable (GDD,
Kc, soil water per layer, carbon pools, flowering state, etc.):

```{r full, eval = FALSE}
out_full <- cumba_experiment(
  weather              = tomatoFoggia$weather,
  param                = cumbaParameters,
  irrigation_df        = tomatoFoggia$irrigation,
  estimateRad          = TRUE,
  estimateET0          = TRUE,
  fullOut              = TRUE
)

names(out_full)
```

# Notes

- Cardinal temperatures in `param` must satisfy `Tmax > Topt > Tbase`
  and soil parameters must satisfy `FieldCapacity > WiltingPoint`;
  otherwise the function stops with a descriptive error.
- Run-time scales linearly with the number of (site × year × ID)
  combinations: each is simulated independently day-by-day.
- The `experiment` column in the output is a character; convert with
  `as.integer()` before joining with integer-keyed observation tables.
