ReadTimeOutput {HYPEtools}

Read a Time Output File

Description

Import a time output file 'time<HYPE_output_variable>.txt' or a converted time output file in netCDF format into R.

Usage

ReadTimeOutput(
  filename,
  dt.format = "%Y-%m-%d",
  hype.var = NULL,
  out.reg = NULL,
  type = c("df", "dt", "hsv"),
  select = NULL,
  id = NULL,
  nrows = -1L,
  skip = 0L,
  warn.nan = FALSE,
  verbose = TRUE
)

Arguments

filename

Path to and file name of the time output file to import. Acceptable file choices are *.txt files following HYPE time output file format or .nc files following the HYPE netCDF formatting standard. See also details for netCDF import.

dt.format

Date-time format string as in strptime. Incomplete format strings for monthly and annual values allowed, e.g. "\%Y". If set to NULL, no date-time conversion will be attempted and the column will be imported as character, applicable e.g. for files containing just one row of summary values over the model period.

hype.var

Character, HYPE variable ID in x. See list of HYPE variables. If NULL (default), the variable ID is extracted from the provided file name, which only works for standard HYPE time output file names (incl. regional and class outputs).

out.reg

Logical, specify if file contents are sub-basin or output region results (i.e. SUBIDs or OUTREGIDs as columns). TRUE for output regions, FALSE for sub-basins. Use only in combination with user-provided hype.var argument.

type

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

select

Integer vector, column numbers to import. Note: first column with dates must be imported and will be added if missing.

id

Integer vector, HYPE SUBIDs/OUTREGIDs to import. Alternative to argument select, takes precedence if both are provided.

nrows

Integer, number of rows to import, see documentation in fread.

skip

Integer, number of data rows to skip on import. Time output header lines are always skipped.

warn.nan

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

verbose

Logical, print information during import.

Details

ReadTimeOutput imports from text or netCDF files. netCDF import is experimental and not feature-complete (e.g. attributes are not yet fully digested). Text file import uses fread from package data.table, netCDF import extracts data and attributes using functions from package ncdf4. Date-time representations in data files are converted to POSIX time representations. Monthly and annual time steps are returned as first day of the time step period.

Import from netCDF files requires an id dimension in the netCDF data. Gridded data with remapped HYPE results in spatial x/y dimensions as defined in the HYPE netCDF formatting standard are currently not supported.

Value

ReadTimeOutput returns a data.frame, data.table, or a HypeSingleVar array. Data frames and data tables contain additional attributes: variable, giving the HYPE variable ID, subid and outregid, the HYPE SUBIDs/OUTREGIDs (corresponding to columns from column two onward) to which the time series belong (both attributes always created and assigned NA if not applicable to data contents), timestep with a time step attribute, and comment with first row comment of imported text file as character string or global attributes of imported netCDF file as character string of collated key-value pairs. An additional attribute id.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 '****************'. ReadTimeOutput will convert those cases to 'NA' entries. Current versions of HYPE allow for defining significant instead of fixed number of digits, which should prevent this issue from arising.

Examples

te <- ReadTimeOutput(filename = system.file("demo_model",
"results", "timeCOUT.txt", package = "HYPEtools"), dt.format = "%Y-%m")
te