--- title: "Run a deficit-irrigation scenario with cumba_scenario()" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Run a deficit-irrigation scenario with cumba_scenario()} %\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 ) ``` # Why `cumba_scenario()`? While `cumba_experiment()` replays an observed irrigation schedule, `cumba_scenario()` runs the model in **automatic deficit-irrigation mode**. Irrigation is triggered when, simultaneously: 1. the crop water status (`ws = 1 - WSI`, where WSI is the simulated water-stress index) falls **below a phase-specific threshold** (`wsLevel`), and 2. at least `turnMin` days have elapsed since the last irrigation. The water applied at each event refills the soil to field capacity in the rooted layers. # The `irrigationStrategy` argument The irrigation logic is controlled by a single **`irrigationStrategy`** argument — a named list with one entry per phenological phase: | Phase | Period | |----------------|-------------------------------------| | `vegetative` | transplanting → flowering | | `reproductive` | flowering → mid-ripening | | `ripening` | mid-ripening → harvest | Each entry is a list with: - `wsLevel` — threshold (0–1) on the crop water status `ws = 1 - WSI`. Irrigation fires when `ws < wsLevel`, i.e. when WSI exceeds `1 - wsLevel`. - `turnMin` — minimum days between consecutive irrigations. # A complete walkthrough on `tomatoFoggia` ```{r run} library(cumba) library(dplyr) library(ggplot2) data(tomatoFoggia) data(cumbaParameters) weather <- tomatoFoggia$weather out <- cumba_scenario( weather = weather, param = cumbaParameters, estimateRad = TRUE, estimateET0 = TRUE, transplantingDOY = 120, irrigationStrategy = list( vegetative = list(wsLevel = 0.5, turnMin = 4), reproductive = list(wsLevel = 0.5, turnMin = 4), ripening = list(wsLevel = 0.5, turnMin = 4) ), fullOut = FALSE ) head(out) ``` ## Compare two irrigation strategies Define a full-irrigation and a deficit strategy, then compare yield and Brix at harvest across all site-years: ```{r compare} full_irr <- list( vegetative = list(wsLevel = 1.0, turnMin = 4), reproductive = list(wsLevel = 1.0, turnMin = 4), ripening = list(wsLevel = 1.0, turnMin = 4) ) deficit <- list( vegetative = list(wsLevel = 0.4, turnMin = 4), reproductive = list(wsLevel = 0.4, turnMin = 4), ripening = list(wsLevel = 0.3, turnMin = 4) ) run_strategy <- function(strategy, label) { cumba_scenario( weather = weather, param = cumbaParameters, irrigationStrategy = strategy, transplantingDOY = 120, estimateRad = TRUE, estimateET0 = TRUE, fullOut = FALSE ) |> mutate(strategy_label = label) } scen <- bind_rows( run_strategy(full_irr, "Full irrigation"), run_strategy(deficit, "Deficit irrigation") ) # Last row per (strategy × site × year) = harvest day harvest <- scen |> group_by(strategy_label, site, year) |> slice_tail(n = 1) |> ungroup() pal <- c("Full irrigation" = "#2166ac", "Deficit irrigation" = "#d6604d") ggplot(harvest, aes(strategy_label, yield, fill = strategy_label)) + geom_boxplot(width = 0.45, outlier.shape = 21, outlier.size = 2, colour = "grey30", linewidth = 0.6) + scale_fill_manual(values = pal) + labs(y = "Yield (t ha⁻¹)", x = NULL, title = "Yield response to irrigation strategy") + theme_bw(base_size = 12) + theme(legend.position = "none") ggplot(harvest, aes(strategy_label, brix, fill = strategy_label)) + geom_boxplot(width = 0.45, outlier.shape = 21, outlier.size = 2, colour = "grey30", linewidth = 0.6) + scale_fill_manual(values = pal) + labs(y = "Brix (°Brix)", x = NULL, title = "Brix response to irrigation strategy") + theme_bw(base_size = 12) + theme(legend.position = "none") ``` ## Daily soil-water and irrigation dynamics ```{r daily, fig.height = 4} scen_yr1 <- scen |> filter(year == min(year)) ggplot(scen_yr1, aes(doy)) + geom_col(aes(y = irrigation, fill = strategy_label), position = "dodge", width = 0.9, alpha = 0.5) + geom_line(aes(y = swc, colour = strategy_label), linewidth = 0.9) + scale_colour_manual(values = pal, name = NULL) + scale_fill_manual(values = pal, name = NULL) + labs(x = "Day of year", y = "Soil water content (%) / Irrigation (mm)", title = "Soil water and irrigation events — first year") + theme_bw(base_size = 12) + theme(legend.position = "bottom") ``` # Notes - `cumba_scenario()` does **not** require an `irrigation_df`; the schedule is generated internally from the stress thresholds. - The `yield` column in the short output is in **t ha⁻¹**. - Setting `fullOut = TRUE` returns all internal state variables (Kc, carbon pools, flowering state, soil water per layer, etc.). - The `irrigationStopCycle` argument (default `100`) sets the phenological cycle completion percentage beyond which no further irrigation is applied — useful for regulated-deficit ripening.