Skip to contents

Run SWAT+

Source: R/swatplus_run_swat.R
run_swatplus.Rd

This function allows to run a SWAT+ project in R. Basic settings for the SWAT run such as the simulation period or the time interval for the outputs can be done directly. SWAT simulation outputs can be defined that are returned in a 'tidy' format in R. Functionality such as model parametrization, parallel execution of simulations, or incremental saving of simulation runs is provided.

Usage

run_swatplus(
  project_path,
  output,
  parameter = NULL,
  start_date = NULL,
  end_date = NULL,
  years_skip = NULL,
  start_date_print = NULL,
  run_index = NULL,
  run_path = NULL,
  n_thread = NULL,
  save_path = NULL,
  save_file = NULL,
  return_output = TRUE,
  add_parameter = TRUE,
  add_date = TRUE,
  refresh = TRUE,
  keep_folder = FALSE,
  quiet = FALSE,
  revision = NULL,
  time_out = Inf
)

Arguments

project_path

Character string that provides the path to the SWAT project folder (i.e. TxtInOut).

output

Define the output variables to extract from the SWAT model runs. See function define_output help file to see how to define simulation outputs.

parameter

(optional) SWAT model parameters either provided as named vector or a tibble. The parameter changes provided with parameter are performed during the model execution accordingly. To learn how to modify parameters see the Get started page of SWATplusR.

start_date

(optional) Start date of the SWAT simulation. Provided as character string in any ymd format (e.g. 'yyyy-mm-dd'), numeric value in the form yyyymmdd, or in Date format.

end_date

(optional) End date of the SWAT simulation. Provided as character string in any ymd format (e.g. 'yyyy-mm-dd'), numeric value in the form yyyymmdd, or in Date format.

years_skip

(optional) Integer value to define the number of simulation years that are skipped before writing SWAT model outputs.

start_date_print

(optional) Start date for printing of the simulation outputs. start_date_print overrules years_skip. Provided as character string in any ymd format (e.g. 'yyyy-mm-dd'), numeric value in the form yyyymmdd, or in Date format.

run_index

(optional) Numeric vector (e.g.run_index = c(1:100, 110, 115)) to run a subset of the provided parameter sets. If NULL all provided parameter sets are used in the simulation.

run_path

(optional) Character string that provides the path where the '.model_run' folder is written and the SWAT models are executed. If NULL '.model_run' is built in the project folder.

n_thread

(optional) Number of threads to be used for the parallel model run. If not provided models are run on single core. The parameter is ineffective for single simulations.

save_path

(optional) Character string to define the path where the model runs are saved if save_file is defined. If save_path = NULL the save_file is saved in the project_path.

save_file

(optional) Character string to define the name of the folder where data bases are generated that store the simulations incrementally.

return_output

(optional) Logical. Whether outputs should be returned or not. Set return_out = FALSE and provide save_file if outputs should only be saved on the hard drive and not be returned in R. 'Default = TRUE

add_parameter

(optional) Logical. If add_parameter = TRUE, the values of the parameter changes and information on the changes are saved and/or returned together with the model outputs. Default = TRUE

add_date

(optional) Logical. If add_date = TRUE a date column is added to every simulation output table. Default = TRUE

refresh

(optional) Logical. refresh = TRUE always forces that '.model_run' is newly written when SWAT run ins started. Default = TRUE

keep_folder

(optional) Logical. If keep_folder = TRUE '.model_run' is kept and not deleted after finishing model runs. In this case '.model_run' is reused in a new model run if refresh = FALSE. Default = FALSE

quiet

(optional) Logical. If quiet = TRUE no messages are written. Default = FALSE

revision

(optional) Numeric. If revision is defined run_swatplus() uses the input revision number (e.g. revision = 59.3. Otherwise the revision number is acquired from the SWAT executable.

time_out

(optional) Numeric. Timeout for simulation in seconds. Simulations may get stuck due to specific parameter combinations. A timeout kills any simulation if the runtime exceeds the set time in seconds. Be careful with this setting as a timeout set too short will also kill all potentially sucessful runs before finishing.

Value

Returns the simulation results for the defined output variables as a tibble. If more than one parameter set was provided a list of tibbles is returned where each column is a model run and each list entry is an output variable.

Examples

To learn the basics on how to use SWATplusR see the Get started page on the package's github page.