2_SWATdoctR verification workflow¶

Purpose¶

The 2_SWATdoctR folder does not build the SWAT+ model. It verifies an already prepared SWAT+ TxtInOut-style setup stored in clean_setup.

The workflow is a quality-assurance stage. It runs diagnostic simulations, extracts selected outputs, and generates plots that can reveal problems in:

climate inputs,
water balance,
management operations,
plant growth,
plant stress,
point sources,
tile drainage.

Key files¶

Path	Meaning
`2_SWATdoctR/DoctR.Rproj`	RStudio project file.
`2_SWATdoctR/workflow.R`	Main SWATdoctR script.
`2_SWATdoctR/clean_setup/`	SWAT+ model input folder used by `run_swat_verification()`.
`2_SWATdoctR/plots.pdf`	Expected output generated by `workflow.R`.

Required software and packages¶

Requirement	Why it is needed
R and RStudio	Run `workflow.R`; RStudio supports workshop execution.
`SWATdoctR`	Provides `run_swat_verification()` and diagnostic plotting functions.
`grid`	Used for PDF page and viewport handling.
`gridExtra`	Loaded by the script; useful for grid-based plot handling.
SWAT+ executable and valid `clean_setup`	Required for model runs.

Verification simulations¶

The script defines three verification runs using the same project path, output groups, date range, warm-up skip, and folder-cleaning behavior. The intended difference is the nostress setting.

Run object	`nostress`	Project path	Outputs	Date range in code	Warm-up / skip	Folder behavior
`Run_1`	`0`	`./clean_setup`	`wb`, `mgt`, `plt`	2004-01-01 to 2023-12-31	3 years	`keep_folder = FALSE`
`Run_2`	`1`	`./clean_setup`	`wb`, `mgt`, `plt`	2004-01-01 to 2023-12-31	3 years	`keep_folder = FALSE`
`Run_3`	`2`	`./clean_setup`	`wb`, `mgt`, `plt`	2004-01-01 to 2023-12-31	3 years	`keep_folder = FALSE`

Date consistency note

The workflow manual mentions 2024 in some explanatory text, but the shown R code uses end_date = 20231231 and years = 2010:2023. This documentation follows the shown code. If the model time.sim extends to 2024, update workflow.R intentionally and rerun the checks.

Main script logic¶

1. Load packages¶

library(SWATdoctR)
library(grid)
library(gridExtra)

2. Run verification simulations¶

Run_1 <- run_swat_verification(
  "./clean_setup",
  outputs = c("wb", "mgt", "plt"),
  start_date = 20040101,
  end_date = 20231231,
  years_skip = 3,
  nostress = 0,
  keep_folder = FALSE
)

3. Combine run objects¶

sim_list <- list(all_str = Run_1, no_str = Run_2, nutrient_str = Run_3)

The combined list allows SWATdoctR plotting functions to compare yield and PHU across stress settings.

4. Create diagnostic PDF¶

pdf("plots.pdf", width = 15, height = 25)

All plots are written to a single multi-page PDF.

Diagnostic plots¶

Plot	What to check
`plot_climate_annual(Run_1)`	Annual precipitation, temperature, and climate-input plausibility.
`plot_monthly_snow(Run_1)`	Seasonal snow accumulation and melt behavior.
`plot_waterbalance(Run_1, simplified = TRUE)`	First-pass water-balance plausibility.
`plot_waterbalance(Run_1)`	Detailed water-balance components.
`plot_variable_at_harvkill(Run_1, variable = "yield")`	Yield at crop harvest/kill events.
`plot_variable_at_harvkill(Run_1, variable = "phu")`	PHU fraction at harvest/kill.
`plot_variable_at_harvkill(sim_list, variable = "yield")`	Yield comparison across stress settings.
`plot_variable_at_harvkill(sim_list, variable = "phu")`	PHU comparison across stress settings.
`plot_variable_at_harvkill(Run_1, variable = "stress")`	Stress factors at harvest/kill.
`plot_hru_pw_day()`	Daily LAI and biomass for selected HRUs.

Expected output¶

Output	Created by	Use
`Run_1`	`run_swat_verification()`	Verification object for all-stress/default run.
`Run_2`	`run_swat_verification()`	Verification object for no-stress run.
`Run_3`	`run_swat_verification()`	Third stress-configuration run; verify exact semantics for the installed package version.
`sim_list`	Base R list	Cross-run comparison object.
`plots.pdf`	R `pdf()` device	Multi-page diagnostic report.
Temporary verification folder	SWATdoctR internals	Normally removed because `keep_folder = FALSE`.

If `plots.pdf` is incomplete¶

If an error occurs before dev.off(), the PDF device may remain open. Run the following until no device remains:

dev.off()

Then rerun the failed section.