ReadTimeOutput: 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
)

Value

ReadTimeOutput returns a data.frame, data.table::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.

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::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.

Examples

Run this code

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