ReadBasinOutput {HYPEtools}

Read a Basin Output File

Description

This is a convenience wrapper function to import a basin output file as data frame or matrix into R.

Usage

ReadBasinOutput(
  filename,
  dt.format = "%Y-%m-%d",
  type = c("df", "dt", "hmv"),
  id = NULL,
  warn.nan = FALSE
)

Arguments

filename

Path to and file name of the basin output file to import. Windows users: Note that Paths are separated by '/', not '\'.

dt.format

Date-time format string as in strptime. Incomplete format strings for monthly and annual values allowed, e.g. '\ be imported as character, applicable e.g. for files containing just one row of summary values over the model period.

type

Character, keyword for data type to return. "df" to return a standard data frame, "dt" to return a data.table object, or "hmv" to return a HypeMultiVar array.

id

Integer, SUBID or OUTREGID of the imported sub-basin or outregion results. If NULL (default), the function attempts to read this from the imported file's name, which only works for standard HYPE basin output file names or any where the first 7 digits give the SUBID or OUTREGID with leading zeros. See details.

warn.nan

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

Details

ReadBasinOutput is a convenience wrapper function of fread from package data.table, with conversion of date-time strings to POSIX time representations. Monthly and annual time steps are returned as first day of the time step period.

HYPE basin output files can contain results for a single sub-basin or for a user-defined output region. ReadBasinOutput checks HYPE variable names (column headers in imported file) for an "RG"-prefix. If it is found, the ID read from either file name or argument id is saved to attribute outregid, otherwise to attribute subid.

Value

ReadBasinOutput returns a data.frame, data.table, or a HypeMultiVar array. Data frames and data tables contain additional attributes: hypeunit, a vector of HYPE variable units, subid and outregid, the HYPE SUBID/OUTREGID to which the time series belong (both attributes always created and assigned NA if not applicable to data contents), timestep with a time step keyword attribute, and comment with contents of an optional first-row comment (NA otherwise). An additional attribute subid.nan might be returned, see argument warn.nan.

Note

For the conversion of date/time strings, time zone "UTC" is assumed. This is done to avoid potential daylight saving time side effects when working with the imported data (and possibly converting to string representations during the process).

HYPE results are printed to files using a user-specified accuracy. This accuracy is specified in 'info.txt' as a number of decimals to print. If large numbers are printed, this can result in a total number of digits which is too large to print. Results will then contain values of '****************'. ReadBasinOutput will convert those cases to 'NA' entries.

Current versions of HYPE allow for defining significant numbers of digits instead of fixed ones, which should prevent this issue from arising.

Examples

te <- ReadBasinOutput(filename = system.file("demo_model",
"results", "0003587.txt", package = "HYPEtools"))