WriteXobs {HYPEtools}

Write an 'Xobs.txt' File

Description

WriteXobs writes or appends an observation data set to an Xobs file.

Usage

WriteXobs(
  x,
  filename,
  append = FALSE,
  comment = NULL,
  variable = NULL,
  subid = NULL,
  last.date = NULL,
  timestep = "d"
)

Arguments

x

A data frame, e.g. an object originally imported with ReadXobs. Date-time information in the first column and measured values in the remaining columns. Column names are ignored on export, but if attributes comment, variable, and subid are available, these can be exported as Xobs headers (see also arguments of the same names below).

filename

A character string naming a file to write to. Windows users: Note that Paths are separated by '/', not '\'.

append

Logical. If TRUE, x will be appended to file filename. File must exist and have an identical column structure as x. If FALSE, existing file in filename will be overwritten!

comment

A character string to be exported as first row comment in the Xobs file. If provided, it takes precedence over a comment attribute of x. Comments are only exported if append is FALSE.

variable

A character vector to be exported as second row in the Xobs file. Must contain the same number of variables as x. If omitted or NULL, an attribute variable in x is mandatory. Will take precedence over a variable attribute of x. If append is TRUE the values are used to test for consistency between export object and the existing file.

subid

Third row in Xobs, containing SUBIDs (integer). Behavior otherwise as argument variable.

last.date

Optional date-time of last observation in existing Xobs file as text string. Only relevant with append = TRUE. Formatting depending on time step, e.g. '2000-01-01' (day) or '2000-01-01 00:00' (hour). Will be automatically read from file per default, but can be provided to reduce execution time when appending to large files.

timestep

Character string, either "day" or "hour", giving the time step between observations. Can be abbreviated.

Details

WriteXobs writes a 'Xobs.txt' file, typically originating from an imported and modified 'Xobs.txt'. HYPE Xobs files contain a three-row header, with a comment line first, next a line of variables, and then a line of subids. Objects imported with ReadXobs include attributes holding this information, and WriteXobs will use this information. Otherwise, these attributes can be added to objects prior to calling WriteXobs, or passed as function arguments.

If argument append is TRUE, the function requires daily or hourly time steps as input. The date-time column must be of class POSIXct, see as.POSIXct. Objects returned from ReadXobs per default have the correct class for the date-time column. When appending to existing file, the function adds new rows with '-9999' values in all data columns to fill any time gaps between existing and new data. If time periods overlap, the export will stop with an error message. Argument last.date can be provided to speed up appending exports, but per default, WriteXobs extracts the last observation in the existing file automatically.

Value

No return value, called for export to text files.

Note

Both variable and subid do not include elements for the first column in the Xobs file/object, in accordance with ReadXobs. These elements will be added by the function.

Examples

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