get_lag_file {hydroroute}

Get Lag from Input File

Description

Given a file path it reads a data frame (time series) of measurements which combines several gauging station ID's and calls get_lag(). The relation (ID's) of gauging stations is read from a file (provided through the file path). The file with Q data and the relation file need to have the same separator (inputsep) and character for decimal points (inputdec). Gauging station ID's have to be in order of their location in downstream direction. The resulting lag is appended to the relation file. This can be saved to a file.

Usage

get_lag_file(
  Q_file,
  relation_file,
  steplength = 15,
  lag.max = 20,
  na.action = na.pass,
  tz = "Etc/GMT-1",
  format = "%Y.%m.%d %H:%M",
  cols = c(1, 2, 3),
  inputsep = ";",
  inputdec = ".",
  save = FALSE,
  outfile = file.path(tempdir(), "relation.csv"),
  mc.cores = getOption("mc.cores", 2L),
  overwrite = FALSE
)

Arguments

Q_file

Data frame or character string. If it is a data frame, it corresponds to the Q data frame in get_lag(). It contains at least a column with the gauging station ID's (default: column index 1), a column with date-time values in character representation (default: column index 2) and a column with flow measurements (default: column index 3). If the column indices differ from c(1, 2, 3), they have to be specified as cols argument in the format c(i, j, k). If it is a character string, it contains the path to the corresponding file which is then read within the function with utils::read.csv().

relation_file

A character string containing the path to the relation file. It is read within the function with utils::read.csv(). The file must contain a column ID that contains the gauging station ID's in order of their location in downstream direction. The lag will then be appended as column to the data frame. For more details on the relation file, see the vignette.

steplength

Numeric value that specifies the length between time steps in minutes (default: 15 minutes). As time steps have to be equispaced, this is used by hydropeak::flow() to get a compatible format and fill missing time steps with NA.

lag.max

Maximum lag at which to calculate the ccf in stats::ccf() (default: 20).

na.action

Function to be called to handle missing values in stats::ccf() (default: na.pass).

tz

Character string specifying the time zone to be used for internal conversion (default: Etc/GMT-1).

format

Character string giving the date-time format of the date-time column in the input data frame Q. This is passed to hydropeak::flow(), to get a compatible format (default: YYYY.mm.dd HH:MM).

cols

Integer vector specifying column indices in the input data frame which contain gauging station ID, date-time and flow rate to be renamed. The default indices are 1 (ID), 2 (date-time) and 3 (flow rate, Q).

inputsep

Character string for the field separator in input data.

inputdec

Character string for decimal points in input data.

save

A logical. If FALSE (default) the lag, appended to the relation file, is not written to a file, otherwise it is written to outfile.

outfile

A character string naming a file path and name where the output file should be written to.

mc.cores

Number of cores to use with parallel::mclapply(). On Windows, this is set to 1.

overwrite

A logical. If FALSE (default), it produces an error if a LAG column already exists in the relation file. Otherwise, it overwrites an existing column.

Value

Returns invisibly the data frame of the relation data with the estimated cumulative lag between neighboring gauging stations in the format HH:MM appended.

Examples

Q_file <- system.file("testdata", "Q.csv", package = "hydroroute")
relation_file <- system.file("testdata", "relation.csv",
                             package = "hydroroute")
get_lag_file(Q_file, relation_file, inputsep = ",", inputdec = ".",
             format = "%Y-%m-%d %H:%M", save = FALSE, overwrite = TRUE)

Q_file <- read.csv(Q_file)
get_lag_file(Q_file, relation_file, inputsep = ",", inputdec = ".",
             format = "%Y-%m-%d %H:%M", save = FALSE, overwrite = TRUE)