ReadWsOutput {HYPEtools}

Read optimization simulation results

Description

Read and combine HYPE optimization simulation output files, generated with 'task WS' during HYPE optimization runs. Outputs can consist of basin, time, or map output files.

Usage

ReadWsOutput(
  path,
  type = c("time", "map", "basin"),
  hype.var = NULL,
  id = NULL,
  dt.format = NULL,
  select = NULL,
  from = NULL,
  to = NULL,
  progbar = TRUE,
  warn.nan = FALSE
)

Arguments

path

Character string, path to the directory holding simulation output files to import. Windows users: Note that Paths are separated by '/', not '\'.

type

Character string, keyword for HYPE output file type to import. One of "time", "map", or "basin". Can be abbreviated. The first two require specification of argument hype.var, the latter of argument subid. Format of return value depends on output type, see details.

hype.var

Character string, keyword to specify HYPE output variable to import. Must include "RG"-prefix in case of output region files. Not case-sensitive. Required in combination with type "time" or "map".

id

Integer, giving a single SUBID or OUTREGID for which to import basin output files. Required in combination with type "basin".

dt.format

Date-time format string as in strptime, for conversion of date-time information in imported result files to POSIX dates, which are returned as attribute. Incomplete format strings for monthly and annual values allowed, e.g. '\ summary values over the model period.

select

Integer vector, column numbers to import, for use with type = "time". Note: first column with dates must be imported.

from

Integer. For partial imports, number of simulation iteration to start from.

to

Integer. For partial imports, number of simulation iteration to end with.

progbar

Logical, display a progress bar while importing HYPE output files. Adds overhead to calculation time but useful when many files are imported.

warn.nan

Logical, check if imported results contain any NaN values. If TRUE and NaNs are found, a warning is thrown and affected SUBIDs and iterations are saved in an attribute subid.nan. Adds noticeable overhead to import time for large simulation file sets.

Details

HYPE optimization routines optionally allow for generation of simulation output files for each iteration in the optimization routine. For further details see documentation on 'task WS' in the optpar.txt online documentation.

ReadWsOutput imports and combines all simulation iterations in an array, which can then be easily used in further analysis, most likely in combination with performance and parameter values from an imported corresponding 'allsim.txt' file.

The result folder containing HYPE WS results, argument path, can contain other files as well, ReadWsOutput searches for file name pattern to filter targeted result files. However, if files of the same type exist from different model runs, e.g. from another calibration run or from a standard model run, the pattern search cannot distinguish these from the targeted files and ReadWsOutput will fail.

For large numbers of result files, simulations can be partially imported using arguments from and to, in order to avoid memory exceedance problems.

Value

ReadWsOutput returns a 3-dimensional array with additional attributes. The array content depends on the HYPE output file type specified in argument type. Time and map output file imports return an array of class HypeSingleVar with [time, subid, iteration] dimensions, basin output file imports return an array of class HypeMultiVar with [time, variable, iteration] dimensions. An additional attribute subid.nan might be returned, see argument warn.nan, containing a list with SUBID vector elements. Vectors contain iterations where NaN values occur for the given subid.

Returned arrays contain additional attributes:

date

A vector of date-times, POSIX if argument dt.format is non-NULL. Corresponds to 1st array dimension.

subid

A (vector of) SUBID(s). Corresponds to 2nd array dimension for time and map output files. NA if not applicable.

outregid

A (vector of) OUTREGID(s). Corresponds to 2nd array dimension for time and map output files. NA if not applicable.

variable

A vector of HYPE output variables. Corresponds to 2nd array dimension for basin output files.

nan (optional)

A named list with SUBID or HYPE variable vector elements. Vectors contain iterations where NaN values occur for the given SUBID/HYPE variable.

Examples

te <- ReadWsOutput(path = system.file("demo_model",
"results", package = "HYPEtools"), type = "map",
hype.var = "cout", dt.format = "%Y-%m")
te