extract_AE {hydroroute}

Extract Associated Events

Description

For given relation and event data return the associated events which comply with the conditions specified in the settings.

Usage

extract_AE(
  relation_path,
  events_path,
  settings_path,
  unique = c("time", "metric"),
  inputdec = ".",
  inputsep = ",",
  saveResults = FALSE,
  outdir = tempdir(),
  TimeFormat = "%Y-%m-%d %H:%M",
  tz = "Etc/GMT-1"
)

Arguments

relation_path

Character string containing the path of the file where the relation file is to be read from with utils::read.csv(). The file must contain a column ID that contains the gauging station ID's in the file have to be in order of their location in downstream direction.

events_path

Character string containing the path of the directory where the event files corresponding to the 'relation' file are located. Only relevant files in this directory will be used, i.e., files that are related to the 'relation' file.

settings_path

Character string containing the path of the file where the settings file is to be read from with utils::read.csv(). The file must be in the format of the output of peaktrace().

unique

Character string specifying if the potential AEs which meet the timeLag and metricLag condition should be filtered to contain only unique events using "time", i.e., by selecting those where the time difference is smallest compared to the specified factor of the mean translation time, or using "metric", i.e., by selecting those where the relative difference in amplitude is smallest (default: "time").

inputdec

Character string for decimal points in input data.

inputsep

Field separator character string for input data.

saveResults

A logical. If FALSE (default), the extracted AEs are not saved. Otherwise the extracted AEs are written to a csv file.

outdir

Character string naming a directory where the extraced AEs should be saved to.

TimeFormat

Character string giving the date-time format of the date-time column in the input data frame (default: "%Y-%m-%d %H:%M").

tz

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

Value

A data frame containing “real” AEs (i.e., events where the time differences and the relative difference in amplitude is within the limits and cut points provided by the file in settings_path). If no AEs can be found between the first two neighboring stations, NULL is returned. Otherwise the function returns all “real” AEs that could be found along the river section specified in the file from relation_path. A warning is issued when the extraction is stopped early and shows the IDs for which no AEs are determined.

Examples

relation_path <- system.file("testdata", "relation.csv", package = "hydroroute")
events_path <- system.file("testdata", "Events", package = "hydroroute")
settings_path <- system.file("testdata", "Q_event_2_AMP-LAG_aut_settings.csv",
                                   package = "hydroroute")
real_AE <- extract_AE(relation_path, events_path, settings_path)