ReadXobs {HYPEtools}

Read an 'Xobs.txt' file

Description

This is a convenience wrapper function to import an Xobs file into R.

Usage

ReadXobs(
  filename = "Xobs.txt",
  dt.format = "%Y-%m-%d",
  variable = NULL,
  nrows = -1L,
  verbose = if (nrows %in% 0:2) FALSE else TRUE
)

Arguments

filename

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

dt.format

Date-time format string as in strptime.

variable

Character vector, HYPE variable ID(s) to select for import. Not case-sensitive. If NULL (default), all variables are imported. See Xobs.txt documentation for a list of variable IDs.

nrows

Integer, number of rows to import. A value of -1 indicates all rows, a positive integer gives the number of rows to import.

verbose

Logical, throw warning if class HypeXobs's attribute timestep cannot be computed.

Details

ReadXobs is a convenience wrapper function of fread from package data.table, with conversion of date-time strings to POSIX time representations. Variable names, SUBIDs, comment, and timestep are returned as attributes (see attr on how to access these).

Duplicated variable-SUBID combinations are not allowed in HYPE Xobs files, and the function will throw a warning if any are found.

Value

If datetime import to POSIXct worked, ReadXobs returns a HypeXobs object, a data frame with four additional attributes variable, subid, comment, and timestep: variable and subid each contain a vector with column-wise HYPE IDs (first column with date/time information omitted). comment contains the content of the Xobs file comment row as single string. timestep contains a keyword string. Column names of the returned data frame are composed of variable names and SUBIDs, separated by an underscore, i.e. [variable]_[subid]. If datetime conversion failed on import, the returned object is a data frame (i.e. no class HypeXobs).

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 e.g. converting to string representations during the process).

Examples

te <- ReadXobs(filename = system.file("demo_model", "Xobs.txt", package = "HYPEtools"))
te