ReadMapOutput {HYPEtools}

Read a Map Output File

Description

This is a convenience wrapper function to import a map output file ('map<HYPE_output_variable>.txt') into R.

Usage

ReadMapOutput(
  filename,
  dt.format = NULL,
  hype.var = NULL,
  type = c("df", "dt", "hsv"),
  warn.nan = FALSE,
  col.prefix = "X"
)

Arguments

filename

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

dt.format

Date-time format string as in strptime, for conversion of date-time information in column headers to POSIX dates, which are returned as attribute. Incomplete format strings for monthly and annual values allowed, e.g. "\%Y". Defaults to NULL, which prevents date-time conversion, applicable e.g. for files containing just one column of summary values over the model period.

hype.var

Character string, a four-letter keyword to specify HYPE variable ID of file contents. See list of HYPE variables. If NULL (default), the variable ID is extracted from the provided file name, which only works for standard HYPE map output file names.

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.

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.

col.prefix

String, prefix added to mapoutput column names. Default is X. Set to NULL to ignore.

Details

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

Value

ReadMapOutput returns a data.frame, data.table, or a HypeSingleVar array. Data frames and data tables contain additional attributes: variable, giving the HYPE variable ID, date, a vector of date-times (corresponding to columns from column 2), timestep with a time step attribute, and comment with the first line of the imported file as text string. An additional attribute subid.nan might be returned, see argument warn.nan.

Note

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 '****************'. ReadMapOutput 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 <- ReadMapOutput(filename = system.file("demo_model",
"results", "mapEVAP.txt", package = "HYPEtools"), dt.format = NULL)
te