wasa_calibwrap: Wrapper function for calibration of the WASA-SED model
In tpilz/WasaEchseTools: Title: Handy tools for preprocessing and analysis of the hydrological models WASA-SED and ECHSE (limited to the WASA engine). Currently only meant for internal use! If you want to try it, handle with care!

Description Usage Arguments Details Value Note Author(s)

A wrapper function, executing a simulation of the WASA-SED model for a given parameter realisation.

wasa_calibwrap(pars = NULL, wasa_app = NULL, sp_input_dir = NULL,
  meteo_dir = NULL, dir_run = paste0(tempfile(pattern = "wasa_calib_"),
  sep = "/"), sim_start = NULL, sim_end = NULL, resol = "daily",
  warmup_start = NULL, radex_file = NULL, dat_streamflow = NULL,
  dat_pr = NULL, flood_thresh = NULL, thresh_zero = NULL,
  warmup_len = 3, max_pre_runs = 20, storage_tolerance = 0.01,
  keep_warmup_states = FALSE, return_val = "river_flow_ts",
  return_sp = FALSE, log_meta = NULL, keep_rundir = FALSE,
  keep_log = FALSE, error2warn = FALSE)

`pars`	A named vector of type numeric with the values of selected parameters (directed to `wasa_modify_pars`).
`wasa_app`	Character string giving the system command of the WASA-SED application (directed to `wasa_run`).
`sp_input_dir`	Character string of the directory containing the spatial WASA-SED input. E.g. the output of `db_wasa_input` (argument 'dest_dir') (directed to `wasa_prep_runs`).
`meteo_dir`	Character string of the directory containing the time series input files for the WASA-SED model. Requires the files temperature.dat, radiation.dat, humidity.dat, and rain_daily.dat or rain_hourly.dat (directed to `wasa_prep_runs`).
`dir_run`	Character specifying the directory for the model run with the current parameter realisation (directed to `wasa_run`). Default: A temporary directory created with `tempfile`.
`sim_start`	Object of class 'date' giving the start date of the simulation (will be written into WASA-SED input file 'do.dat'; directed to `wasa_prep_runs`).
`sim_end`	Object of class 'date' giving the end date of the simulation (will be written into WASA-SED input file 'do.dat' directed to `wasa_prep_runs`).
`resol`	Temporal resolution of the model simulations. Supported are: 'daily' (default) and 'hourly'.
`warmup_start`	An object of class 'date' giving the start date of the warm-up period. If `NULL` (default), the value in do.dat (lines 4 and 6) is used. Directed to `wasa_run`.
`radex_file`	Character string of the file (including path) of preprared extraterrestrial radiation input (named 'extraterrestrial_radiation.dat') (directed to `wasa_prep_runs`)).
`dat_streamflow`	OPTIONAL: Object of class 'xts' containing a time series of streamflow at the catchment outlet in (m3/s) in the resolution of the model run. NA values are allowed and will be discarded for goodness of fit calculations. Only needed if `return_val = 'nse'`.
`dat_pr`	OPTIONAL: Object of class 'xts' containing a time series of catchment-wide average precipitation in (m3) in the resolution of the model run. If not given (default), it will be read (and calculated) from the WASA-SED input files if needed. However, it is more efficient in terms of function execution time to specify it as input if needed. Only needed if `return_val = 'hydInd'`.
`flood_thresh`	OPTIONAL: Numeric value giving the threshold in (m3/s) for the definition of a flood event (directed to `hydInd`). Only needed if `return_val = 'hydInd'`.
`thresh_zero`	OPTIONAL: Values of discharge in (m3/s) below this value will be treated as zero flows (directed to `hydInd`). Only needed if `return_val = 'hydInd'`.
`warmup_len`	Integer giving the length of the warm-up period in months. Default: 3. Directed to `wasa_run`.
`max_pre_runs`	Integer specifying the maximum number of warm-up iterations to be applied. If the relative storage change is still larger than `storage_tolerance` after `max_pre_runs` iterations, the warm-up will be aborted and the model be run anyway. A warning will be issued. Default: 20. Directed to `wasa_run`.
`storage_tolerance`	Numeric value giving the relative change of the model's water storages between two connsecutive warm-up runs below which the warm-up will be concluded and the actual model simulation be started. Default: 0.01. Directed to `wasa_run`.
`keep_warmup_states`	Logical value. Shall state storage files after finishing the warm-up runs be stored for upcomming runs (i.e. .stat files be copied into `sp_input_dir`/input)? WARNING: Existing .stat files will be overwritten! Default: `FALSE`. This option might be useful for calibration runs as it might reduce the number of necessary warm-up runs for each new parameter set.
`return_val`	Character vector specifying your choice of what this function shall return. Default: 'river_flow'. See description of return value below.
`return_sp`	Logical flag specifying if certain output shall be given including spatial variability at subbasin level instead of mere catchment specific values. See description of return values below for spatial outputs. Default: `FALSE`.
`log_meta`	Character containg the name (and path) of a file into which information about the function call will be written. See below for more information. Default: `NULL`, i.e. no logile will be created. If the file already exists, the file name to be created will be extended by a call to `tempfile`.
`keep_rundir`	Value of type `logical`. Shall directory `dir_run` be retained (`TRUE`) or deleted (`FALSE`) after function execution? Default: `FALSE`.
`keep_log`	Value of type `logical`. Shall the WASA-SED specific log file (not to be confused with `log_meta`!) of the model run be written (to `dir_run`)? Default: `FALSE`. Will be ignored if `keep_rundir = FALSE`. Directed to `wasa_run`.
`error2warn`	Value of type `logical`. Shall runtime errors of the model be reported as a warning instead of stopping this function with an error? If so, the model run's log file will be saved and, in case of reasonable model output, this wrapper function will proceed as usual. If no reasonable output could be found, a value `NA` will be returned. Default: `FALSE`. Also directed to `wasa_run`.

Function is a wrapper function, internally executing functions wasa_prep_runs, wasa_modify_pars, and wasa_run and processing and returning the simulation output as specified. The function can be employed by model calibration functions such as dream or optim_dds, or to execute single model runs within a single function call.

Function returns a named list or a single element (if length(return_val) = 1) of numeric value(s). Can be controlled by argument return_val. Currently implemented are the options:

river_flow_[mm|ts]: A single value of the catchment's simulated river outflow over the specified simulation period in (mm) or a time series of class 'xts' in (m3/s). Respects return_sp (only ts, river_flow_mm is only given for catchment outlet!).

eta_mm[_ts]: A single value of the catchment's simulated amount of actual evapotranspiration over the specified simulation period in (mm) or a time series of class 'xts' in (mm/timestep). Respects return_sp.

etp_mm[_ts]: A single value of the catchment's simulated amount of potential evapotranspiration over the specified simulation period in (mm) or a time series of class 'xts' in (mm/timestep). Respects return_sp.

runoff_total_mm[_ts]: A single value of the catchment's simulated amount of total runoff, i.e. runoff contribution into river(s), over the specified simulation period in (mm). Respects return_sp or a time series of class 'xts' in (mm/timestep).

runoff_gw_mm[_ts]: A single value of the catchment's simulated amount of groundwater runoff, i.e. groundwater contribution into river(s), over the specified simulation period in (mm). Respects return_sp or a time series of class 'xts' in (mm/timestep).

runoff_sub_mm[_ts]: A single value of the catchment's simulated amount of subsurface runoff, i.e. near-surface soil water (excl. groundwater!) contribution into river(s), over the specified simulation period in (mm) or a time series of class 'xts' in (mm/timestep). Note: due to computational reasons, 'runoff_gw_mm' will be given in addition if this value is set. Respects return_sp.

runoff_surf_mm[_ts]: A single value of the catchment's simulated amount of surface runoff, i.e. surface water contribution into river(s), over the specified simulation period in (mm) or a time series of class 'xts' in (mm/timestep). Respects return_sp.

hydInd: Named vector of hydrological indices calculated with function hydInd. See function's doc for more information. This option requires the optional input arguments flood_thresh, thresh_zero, and (optional) dat_pr.

nse: A single numeric value giving the Nash-Sutcliffe efficiency of streamflow simulation at the catchment outlet (a common goodness of fit measure of hydrological model runs).

kge: A single numeric value giving the Kling-Gupta efficiency of streamflow simulation at the catchment outlet (see paper https://doi.org/10.1016/j.jhydrol.2009.08.003).

If argument log_meta was given, the logfile contains the following information: parameter names and corresponding realisations, output element names and corresponding values, run_dir: realisation of argument dir_run, time_total: total time for function execution (i.e. until writing logfile, in secs.), time_simrun: runtime of the simulation run (in secs.), time_warmup: total runtime for all warm-up runs (in secs.), warmup_iterations: number of warm-up iterations, warmup_storchange: relative storage change after the last warm-up iteration.

To avoid warm-up runs, set max_pre_runs or warmup_len to zero.

Model's water balance: runoff_total_mm = runoff_surf_mm + runoff_sub_mm + runoff_gw_mm. Moreover, river_flow_mm should be slight less than (due to transmission losses and storage changes; but all in all almost equal to) runoff_total_mm as long as there is no artificial influence (e.g. from reservoirs).

Initial states can have a large influence, depending on setup and parameterisation. Therefore, it is advisable to make some test runs with different warmup parameters ( warmup_start, warmup_len, max_pre_runs, storage_tolerance, keep_warmup_states) before starting a calibration run! Consecutive runs with the same parameterisation should come up with the same results when keep_warmup_states = TRUE.

If running this function in parallel mode: Setting argument keep_warmup_states = TRUE can have problematic side effects due to parallel reading and (over-)writing of the same files. To accelerate warmup anyway, you can generate default initial storage files by running a default parametrisation over the warmup horizon until convergence is reached and use the resulting storage files as initial storages for all calibration runs. A similar problem arises When specifying argument log_meta. In that case, create an empty initial logfile 'log_meta' before starting the parallel calibration routine to invoke the file name extension via tempfile right away.

Tobias Pilz tpilz@uni-potsdam.de

tpilz/WasaEchseTools documentation built on May 5, 2019, 12:33 p.m.