get_lag_file function

Get Lag from Input File

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.

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.

Returns

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)