Skip to contents

Preparation

Workflow for SWAT+ model setup verification

Source: vignettes/qa.Rmd
qa.Rmd

This workflow provides guidance for the model setup verification of SWAT+ model setup. It is important step in quality assurance of models. This workflow should be used before and after the model calibration and validation. Before, as it is important to verify the model setup before calibration and validation to avoid trying to over compensate for model mistakes with model parametrization. After, as it is important to check that model calibration did not introduce any errors in the model setup or created problems with representation of the processes in the model. This workflow essentially summarizes all steps, which are described in the SWAT+ modeling protocol sections 6.2.2. and 6.2.3 Christoph et al. (2022).

This workflow is based model on model setup verification workflow presented in the article of Plunge et al. (2024). The main 5 steps of the workflow are as follows:

  1. Analysis of the simulated climate variables to verify if the weather inputs were correctly interpreted.
  2. Analysis of the triggered management operations to verify if the management operation inputs were correct.
  3. Unconstrained plant growth analysis to verify if the used plants and growing periods lead to plausible potential plant growth.
  4. Analysis of plant growth considering plant stress to identify potential limiting factors such as fertilizer or irrigation inputs.
  5. Verification of point source inputs to ensure that tile flow and point sources were plausibly simulated.

1. Loading required packages

SWATdoctR package is the basis of this workflow. So it should be installed and loaded, if not done. The installation of an R package from a platform such as GitHub or GitLab can be done with the package remotes

# If the package 'remotes' is not installed 
install.packages('remotes')
# If the package 'SWATdoctR' is not installed 
remotes::install_git('https://git.ufz.de/schuerz/swatdoctr')

Load of SWATdoctR with the following line. This is the only package needed for the workflow.

library(SWATdoctR)

2. Define the model path

For model setup verification the path to it have to be defined. If it is setup after calibration and validation, make sure it contains ‘calibration.cal’ file. It can be prepared with this step

# Path to the SWAT+ project
model_path <- 'Define:/your/model/txtinout/path'

# Path to folder where project is located (for later file writing)
parent_dir <- dirname(model_path)
# Name of the SWAT+ project folder (for later file reading/writing)
save_name  <- basename(gsub('/$', '', model_path))

3. (Optional) Harvest and kill operation seperation

Plotting of variables at the harvest and kill of a crop requires that the management operations ‘harvest’ and ‘kill’ are set separately in the management schedules and not as a combined ‘harvest_kill’ operation. If case your model setup have combined operation the following function fixes the issue.

add_kill_op(model_path)

4. Running the SWAT+ model (all plant stress factors deactivated)

With run_swat_verification SWAT+ simulations are performed for the model setup in the model_path, which will be used in the verification steps. The simulations for the analysis steps 1. to 3. above are preformed without plant stress activated. The simulation results are saved in the same folder where the SWAT+ project is located. The verification is an iterative step, where the simulation has to be repeated after identified issues in a model setup are fixed and verification steps are repeated.

Every time the simulation is repeated it is saved with a new file name (to have all previous steps documented), with a name that follows the syntax ‘<project_name>_nostr_<version>.rds’. It is also important to note that the outputs from the run_swat_verification function, depending on the setup, could be multiple gigabytes in size, which might cause R to break and restart. Therefore, archiving results is crucial. Automatically the new version is always increased by 1 with respect to the largest version number found in the folder. You can delete previous versions manually from the folder.

## Running SWAT+ model setup and saving outputs required for the workflow
sim_nostress <- run_swat_verification(project_path = model_path,
                                      outputs = c('wb', 'mgt', 'plt'),
                                      years_skip = 3,
                                      nostress = 1)

## Saving results into the file
file_version <- get_file_version(parent_dir, save_name, '_nostr_') + 1
saveRDS(sim_nostress, file = paste0(parent_dir,'/', save_name, '_nostr_', 
                                    file_version,'.rds'))

Following lines could be used to load saved results from the file.

file_version <- get_file_version(parent_dir, save_name, '_nostr_')
sim_nostress <- readRDS(file = paste0(parent_dir,'/', 
                                      save_name, '_nostr_', 
                                      file_version,'.rds'))

The following analyses in step 1, step 2 and step 3 use the file version file_version of sim_nostress.

Christoph, Schürz, Čerkasova Natalja, Farkas Csilla, Nemes Attila, Plunge Svajunas, Strauch Michael, Szabó Brigitta, and Piniewski Mikołaj. 2022. “SWAT+ modeling protocol for the assessment of water and nutrient retention measures in small agricultural catchments.” Zenodo. https://doi.org/10.5281/zenodo.7463395.
Plunge, Svajunas, Christoph Schürz, Natalja Čerkasova, Michael Strauch, and Mikołaj Piniewski. 2024. “SWAT+ model setup verification tool: SWATdoctR.” Environmental Modelling & Software 171: 105878. https://doi.org/10.1016/j.envsoft.2023.105878.