R SWAT User Manual

1. Launch R-SWAT interface

1.1. First approach:

Recommend for the first time you use R-SWAT, only steps 6 is required for the next time you run R-SWAT.

• Step 1: Install R version > 4.1.1 or newer version (If you use old version of R this might NOT work).
• Step 2: Install R studio
• Step 3: Click here to download the whole code of this app.
• Step 4: Extract the downloaded file => Open RStudio
• Step 5: Open the file ./R/loadPackages.R with RStudio and install all packages list in this file (take 5-10 minutes).
• Step 6: Open the file server.R or ui.R in R studio => then click the green button named Run App

1.2. Second approach

Not recommend for the first time using R-SWAT, only step 3 is required for the next time you run R-SWAT

• Steps 1-2: identical to Steps 1-2 in the first approach. These steps are optional, required only if R and RStudio has not been installed
• Step 3: Open R (or RStudio) and run the following commands

# Load shiny package (if you have not installed shiny, please install it using install.packages("shiny") )
library(shiny)

# Automatically download this R-SWAT app (code + data) to your local machine and run it
runGitHub("R-SWAT", "tamnva")

1.3. Third approach

Not recommend for the first time using R-SWAT, only step 5 is required for the next time you run R-SWAT

• Step 1-4: identical to Steps 1-2 in the first approach. These steps are optional, required only if R and RStudio has not been installed or R-SWAT has not been download to your local computer.
• Step 5: Open R and run the following commands

# Load shiny package (if you have not installed shiny, please install it using install.packages("shiny") )
library(shiny)

# Automatically download this R-SWAT app (code + data) to your local machine and run it
runApp("RSWAT_folder")   

2. Parameter sensitivity analysis

All of the required data to reproduce these example are in this folder. If there is any issue, please post it in the Google group or contact me directly, I am happy to answer your question.

2.1. Sensi_Cali_(uniform_Latin_Hypercube_Sampling)

• Problem description: Perform parameter sensitivity analysisfor streamflow at the catchment outlet. Use multivariable regression approach with parameters generated by uniform Latin Hypercube Sampling, this is a global sensitivity analysis approach. This approach has been used by SWAT-CUP (see page 60). The parameters subjected to sensitivity analysis are in the file ./data/parameter_range.csv observed streamflow at the catchment outlet is ./data/obs_var_1.txt. The number of iterations (model runs) is 100

• General procedure: 1. General Setting → 2. Parameter sampling → 3. Run SWAT → 4.1. Objective function → 4.2. Sensitivity analysis

2.2. Sensi_(from_sensitivity_package)

• Problem description: Same as 2.1. but using Morris's Elementary Effects Screening Method (Morris, 1991; Campolongo et al., 2007; Iooss et al., 2021).

• General procedure: 1. General Setting → 2. Parameter sampling → 4.1. Objective function → 3. Run SWAT → 4.2. Sensitivity analysis

2.3. Sensi_(from_userDefined_package)

• Problem description: Same as 2.1. but using the Variance-Based Sensitivity Indices (Sobol' indices) from the sensobol package

• General procedure: Add package 'sensobol' to the file "loadPackages.R" → 1. General Setting → 2. Parameter sampling → 4.1. Objective function → 3. Run SWAT → 4.2. Sensitivity analysis

• The input R commands can be copied from the text below. "convertRange" is R-SWAT function to convert parameter range from [0,1] to the user-defined range.

sensCaliObject <- SWAT(convertRange(sobol_matrices(N =4, params = paste("X", 1:nParam, sep = "")), minCol, maxCol))
sobol_indices(Y = sensCaliObject, N = 4, params = paste("X", 1:nParam, sep = ""))$results

3. Parameter calibration

All of the required data to reproduce these example are in this folder.

3.1 . Sensi_Cali_(uniform_Latin_Hypercube_Sampling)

• Problem description: Parameter calibration and uncertainty analysis for streamflow (./data/obs_var_1.txt) at the catchment outlet with parameter generated by Uniform Latin Hypercube sampling. This approach has been used by SUIF2. The parameters subjected to calibration analysis are in the file ./data/parameter_range.csv. The number of iterations (model runs) is 100. Behavioral threshold NSE >= 0.5

• General procedure: 1. General Setting → 2. Parameter sampling → 3. Run SWAT → 4.1. Objective function → 4.2. Optimization/Uncertainty

3.2. Cali_(Generalized_Likelihood_Uncertainty_Estimation)

• Problem description: Similar to 3.1. but using the GLUE approach (Beven and Binley, 1992).

• General procedure: 1. General Setting → 2. Parameter sampling → 4.1. Objective function → 3. Run SWAT → 4.2. Optimization/Uncertainty

3.3. Cali_(from_hydroPSO_package)

• Problem description: Similar to 3.1 but using the Particle Swarm Optimisation (PSO) algorithm (Zambrano-Bigiarinia & Rojas, 2013) and the number of iterations (maxit * 40) = 40 or maxit = 1

• General procedure: 1. General Setting → 2. Parameter sampling → 4.1. Objective function → 3. Run SWAT→ 4.2. Optimization/Uncertainty

3.4. Cali_(from_nloptr_package)

• Problem description: Similar to 3.1 but using the Particle Swarm Optimisation (PSO) algorithm (Zambrano-Bigiarinia & Rojas, 2013) and the number of iterations (maxit * 40) = 40 or maxit = 1.

• General procedure: 1. General Setting → 2. Parameter sampling → 4.1. Objective function → 3. Run SWAT→ 4.2. Optimization/Uncertainty

3.5. Cali_(from_optimization_package)

• Problem description: Similar to 3.1 but using Simulated Annealing (Corana et al., 1987; Kirkpatrick et al., 1983; Pronzato et al., 1984) from the optimization package (Husmann et al., 2022). The following command in 2. Parameter sampling will execute the model in total 134 times.
• General procedure: 1. General Setting → 2. Parameter sampling → 4.1. Objective function → 3. Run SWAT→ 4.2. Optimization/Uncertainty

3.6. Cali_(Dynamically_Dimensioned_Search)

• Problem description 1: Similar to 3.1 except the followings. Use Dynamically Dimensioned Search (DDS, Tolson and Shoemaker, 2007), a built-in function in R-SWAT. Run DDS parallel on 3 cores independently (each core 20 runs, the total number of model runs is 3*20 + 3 = 63). In other words, there is no communication of the intermediate results among cores.

• General procedure: 1. General Setting → 2. Parameter sampling → 4.1. Objective function → 3. Run SWAT→ 4.2. Optimization/Uncertainty

  (NOTE: Change input field in Step 2. Parameter sampling to "20, 2" if users want to perform following optimization with DDS: evaluating the objective function and finding the best parameter set among all cores after each iteration; assigning this best parameter set as an initial parameter set for all cores in the next run).

3.7. Cali_(from_userDefined_package)

• Problem description: Similar to 3.1 except the followings: use the Global Optimization by Differential Evolution from the DEoptim package (Ardia et al., 2011; Ardia et al., 2022) for parameter optimization. Run 5 iteration (itermax = 5) and each 10 simulations (NP = 10) each iteration.

• General procedure: add DEoptim to the requiredPackages in the loadPackages.R file → 1. General Setting → 2. Parameter sampling → 4.1. Objective function → 3. Run SWAT→ 4.2. Optimization/Uncertainty

  Copy the following code for step 2. Parameter sampling

outDEoptim <- DEoptim(SWAT, minCol, maxCol, DEoptim.control(NP = 10, itermax = 5))

3.8. Read_User_Parameter_File

• Problem description: Same as 3.1 but the parameter set is read from the external file, the parameter set file is bestPar.txt (only 9 parameter sets/iterations - please UNZIP the downloaded file)
• General procedure: 1. General Setting → 2. Parameter sampling → 3. Run SWAT → 4.1. Objective function → 4.2. Optimization/Uncertainty

4. Extract user define output(s) - userReadSwatOutput

4.1. Example 1

• Problem description: Perform model calibration for monthly streamflow at the catchment outlet using GLUE approach (Beven and Binley, 1992). The parameters used for calibration and their ranges are in this file ./data/parameter_range.csv. The calibration period is from 01.2001 - 12.2006. The objective function is NSE, behavioral threshold is 0.5, the number of iterations is 20.
• General procedure: 1. Identify where the data is stored → 2. modify the file ./R/userReadSwatOutput.R → 3. Prepared corresponding observed data file → 4. Run R-SWAT
  1. Identify where the data are stored. In this example, we know that the "watout.dat" file contains the streamflow at the catchment outlet in a DAILY time step (download the TxtInOut folder and copy/paste the executable in this folder, run SWAT to explore the watout.dat file). Here is the watout.dat file (please UNZIP this file). This is a screenshot of the watout.dat file
  2. Here is the modified userReadSwatOutput.R file with detailed explanation. Please UNZIP this file and replace the file /R/userReadSwatOutput.R. Please ALWAYS checking your code if it works before using for R-SWAT.
  3. The data after extraction will have a length of 72 (this is also the number of month from 01.2001 - 12.2006). The observed data file for calibration should have a same length, here is a the observed data file for calibration (please UNIZIP this file)
  4. run R-SWAT: 1. General Setting → 2. Parameter sampling → 3. Run SWAT → 4.1. Objective function → 4.2. Optimization/Uncertainty (Note: the lowest NSE is 0.89, therefore, the behavioral threshold given above is automatically satisfied).

4.2. Example 2

• Problem description: Same Example 1 calibrate for both monthly streamflow and sediment at the catchment outlet
• General procedure: 1. Identify where the data is stored → 2. modify the file ./R/userReadSwatOutput.R → 3. Prepared corresponding observed data file → 4. Run R-SWAT.
  1. Identify where the data are stored. In this example, we know that the "watout.dat" file contains the streamflow and sediment loading (tons/month) at the catchment outlet in a DAILY time step (download the TxtInOut folder and copy/paste the executable in this folder, run SWAT to explore the watout.dat file). Here is the watout.dat file (please UNZIP this file). This is a screenshot of the watout.dat file
  2. Here is the modified userReadSwatOutput.R file with detailed explanation. Please UNZIP this file and replace the file /R/userReadSwatOutput.R. Please ALWAYS checking your code if it works before using for R-SWAT.
  3. The data after extraction will have a length of 72 (this is also the number of month from 01.2001 - 12.2006). The observed data file for calibration should have a same length, here is a the observed data file for calibration (please UNIZIP this file).
  4. run R-SWAT: 1. General Setting → 2. Parameter sampling → 3. Run SWAT → 4.1. Objective function → 4.2. Optimization/Uncertainty (Note: the lowest NSE is 0.89, therefore, the behavioral threshold given above is automatically satisfied).

5. User-defined objective function - userObjFunction

5.1. Using modified NSE for model calibration/sensitivity analysis

• Problem description: Parameter calibration for streamflow (./data/obs_var_1.txt) at the catchment outlet with parameter generated by Uniform Latin Hypercube sampling (20 iterations). The parameters subjected to calibration analysis are in the file ./data/parameter_range.csv. The number of iterations (model runs) is 20. Use (NSE + ln(NSE))/2 as the objective function.
• General procedure: First modified the file userObjFunction.R (here is the modified file) → 1. General Setting → 2. Parameter sampling → 3. Run SWAT → 4.1. Objective function → 4.2. Optimization/Uncertainty

5.2. Using modified NSE for streamflow calibration at two gauging stations

• Problem description: Parameter calibration for streamflow at the catchment outlet and at the outlet of subcatchment 1 with parameter generated by Uniform Latin Hypercube sampling (20 iterations). The observed data are here. The parameters subjected to calibration analysis are in the file ./data/parameter_range.csv. Use (2 * NSE_Q_outlet + 1 * NSE_Q_subcatchment_1)/3 as the objective function. Behavioral threshold is 0.3
• General procedure: First modified the file userObjFunction.R (here is the modified file) → 1. General Setting → 2. Parameter sampling → 3. Run SWAT → 4.1. Objective function → 4.2. Optimization/Uncertainty

6. Visualization

6.1. watout.dat

• Data for visualization: watout.dat file and observed data
• Here is a screen shot of the result

6.2. output.hru

• Data for visualization: TxtInOut files and hru shape file
• Here is a screen shot of the result

6.3. output.rch

• Data for visualization: file.cio in the TxtInOut folder, observed data, and output.rch file
• Here is a screen shot of the result

6.4. output.sub

• Data for visualization: Subbasin shape file can be found here, TxtInOut files
• Here is a screen shot of the result.

7. Other ultilities

7.1. Extracting model outputs that are not used for calibration

• Problem description: In some cases, if we want to extract model outputs that are not used for calibration or validation, in this case, simply put the values of the variables as NA (meaning not available). So the objective function will not use these values. In this example, I calibrate the model for outflows from Reach 1 and want to see how the outflow from Reach 2 looks like (but not calibrate the model for outflows from Reach 2)

8. Evaluating R-SWAT functions

8.1. Evaluating the function for updating SWAT input files with a new parameter set

• In this updated TxtInOut files with new parameter values, we demonstrate that R-SWAT can correctly update SWAT input files with a given parameter set. The source code used in this example (R-SWAT version 1.0.0) and the original TxtInOut can be downloaded here