get_lag_dir {hydroroute}

Get Lag from Input Directory

Description

Given a file path it reads a data frame (time series) of measurements. For each relation file in the provided directory path it calls get_lag_file(). Make sure that the file with Q data and the relation files have the same separator (inputsep) and character for decimal points (inputdec). Gauging station ID's in the relation files have to be in order of their location in downstream direction. The resulting lags are appended to the relation files. The resulting list of relation files can be returned and each relation file can be saved to its input path.

Usage

get_lag_dir(
  Q,
  relation,
  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 = ".",
  relation_pattern = "relation",
  save = FALSE,
  mc.cores = getOption("mc.cores", 2L),
  overwrite = FALSE
)

Arguments

Q

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

A character string containing the path to the directory where the relation files are located. They are read within the function with utils::read.csv().

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

Field separator character string for input data.

inputdec

Character string for decimal points in input data.

relation_pattern

Character string containing a regular expression to filter relation files (default: relation, to filter files that contain relation with no restriction) (see base::grep()).

save

A logical. If FALSE (default) the lag, appended to the relation file, overwrites the original relation input file.

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 a list of data frames where each list element represents a relation file from the input directory. Optionally, the data frames are used to overwrite the existing relation files with the appended LAG column.

Examples

Q_file <- system.file("testdata", "Q.csv", package = "hydroroute")
relations_path <- system.file("testdata", package = "hydroroute")
lag_list <- get_lag_dir(Q_file, relations_path, inputsep = ",",
                        inputdec = ".", format = "%Y-%m-%d %H:%M",
                        overwrite = TRUE)
lag_list