Introduction to hydroroute

Input data

Several data files are required to perform the analysis.

Dataset `Q`

If the mean translation time between hydrographs at neighboring gauging stations is not given or known, the raw dataset Q, containing (equispaced) date-time values and the corresponding flow fluctuations, is needed. Based on these data the mean translation time between hydrographs at neighboring gauging stations may be estimated using get_lag(). The dataset Q needs to contain three variables:

ID Character string which refers to the identifier of the gauging station (in Austria: HZBCODE).
Time Character string with date-time information of stage measurements.
Q Numeric, flow (stage measurements).

The combination of ID and Time must be unique. Functions that use the dataset Q assume that these variables are contained in this order with exactly these names. If this is not the case, i.e., if the columns have different names or are not in this order, the order can be specified in these functions with argument cols. The columns are then renamed internally to make the data processable. Also the date-time format must be specified if it is different from the function’s default format used.

The following code loads the sample dataset Q and shows the first few rows:

Q_path <- system.file("testdata", "Q.csv", package = "hydroroute")
Q <- read.csv(Q_path)
head(Q)
#>       ID                Time    Q
#> 1 200000 2014-01-01 00:00:00 4.07
#> 2 200000 2014-01-01 00:15:00 4.06
#> 3 200000 2014-01-01 00:30:00 4.05
#> 4 200000 2014-01-01 00:45:00 4.04
#> 5 200000 2014-01-01 01:00:00 4.03
#> 6 200000 2014-01-01 01:15:00 4.01

The sample dataset Q is a data frame with 22656 rows and 3 variables as described above. The station ID’s along the flow path are 100000, 200000, 300000, 400000. The time ranges from "2014-01-01 00:00:00" to "2014-02-28 23:45:00".

Dataset `relation`

The dataset relation provides information about the gauging stations of neighboring hydrographs. It contains:

ID Character string which refers to the identifier of the gauging station (in Austria: HZBCODE).
Type Character string which characterizes the source hydrograph (Turbine flow, Gauge, Basin outflow).
Station Character string which indicates the order of the n hydrographs in relation in downstream direction (Si with i = 1, ..., n).
fkm Numeric, position of hydrograph in km relative to the source.
LAG Character string which contains the cumulative mean translation time (or estimated cumulative lag) between the source and a specific gauging station in the format HH:MM. For S1 this is either indicated as missing (NA) or always given as 00:00. It is either already provided in relation or can be estimated from the corresponding dataset Q with get_lag().

The following code loads an example dataset:

relation_path <- system.file("testdata", "relation.csv", package = "hydroroute")
relation <- read.csv(relation_path)
relation
#>       ID  Type Station   fkm   LAG
#> 1 100000 Gauge      S1  0.01 00:00
#> 2 200000 Gauge      S2  9.16 01:00
#> 3 300000 Gauge      S3 17.02 02:15
#> 4 400000 Gauge      S4 29.27 03:30

The dataset relation contains 4 adjacent gauging stations.

Event files

The output files from hydropeak’s get_events_*() function are used to identify AEs. The naming scheme of the output files is ID_event-type_date-time-from_date-time-to.csv. Event types are defined as follows:

0: Constant event after an NA event (i.e., a missing event) or as first event in the time series.
1: Constant event after a decreasing event.
2: Increasing event (IC).
3: Constant event after an increasing event.
4: Decreasing event (DC).
5: NA event.

The most important event types for the following analysis are 2 (increasing event; IC) and 4 (decreasing event; DC).

Package hydroroute includes 8 sample Event files for each gauging station ID contained in the sample dataset Q and event type 2 (IC) and 4 (DC) between "2014-01-01 00:00:00" and "2014-02-28 23:45:00". The increasing events for the station with ID 100000 are thus loaded using:

Sx <- system.file("testdata", "Events", "100000_2_2014-01-01_2014-02-28.csv",
                  package = "hydroroute")
Sx <- read.csv(Sx)
head(Sx)
#>       ID EVENT_TYPE                Time   AMP  MAFR       MEFR DUR     RATIO
#> 1 100000          2 2014-01-01 00:15:00  0.01  0.01 0.01000000   1  1.003546
#> 2 100000          2 2014-01-01 01:00:00 27.07 12.20 6.76750000   4 10.565371
#> 3 100000          2 2014-01-01 10:15:00 29.38 15.50 7.34500000   4 11.801471
#> 4 100000          2 2014-01-01 13:30:00  0.16  0.03 0.02666667   6  1.060837
#> 5 100000          2 2014-01-01 17:30:00 30.91 16.90 7.72750000   4 12.490706
#> 6 100000          2 2014-01-01 20:45:00  0.02  0.01 0.01000000   2  1.007812

Get mean translation time between hydrographs with `get_lag()`

For the identification of AEs, the translation time between neighboring hydrographs and the event amplitude have to be considered. For the first criterion, the mean translation time (LAG) between hydrographs has to be estimated and the cumulative values appended to the relation data for further processing, if not available yet.

Function get_lag_file() uses:

Q_file A path to a file that contains the Q data from several stations or a data frame that contains this information.
relation_file A path to a relation file. The IDs of the stations must be in Q.

If the argument save is TRUE, the relation data with appended LAG column is written to a file specified in outfile. If a LAG column already exists, argument overwrite has to be set to TRUE to overwrite the existing column. The function can be applied to several relation files by iterating over file paths or if a single Q data file is available, get_lag_dir() can be used. relation files can be selected from a directory using regular expressions (argument relation_pattern).

The following code shows this for single file names:

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

This code indicates the use with get_lag_dir() where the directory is specified:

Q_file <- system.file("testdata", "Q.csv", package = "hydroroute")
relations_path <- system.file("testdata", package = "hydroroute")
get_lag_dir(Q_file, relations_path, inputsep = ",",
            inputdec = ".", format = "%Y-%m-%d %H:%M", overwrite = TRUE)
#> Warning in parallel::mclapply(relation_list, function(x) get_lag_file(Q_file =
#> Q_file, : scheduled core 1 encountered error in user code, all values of the job
#> will be affected

Estimate settings with `estimate_AE()`

Greimel et al. (2022) propose the following algorithm to identify AEs:

"Starting from every single event at the upstream hydrograph (Sx), the mean translation time between the hydrographs […] is subtracted from the downstream hydrograph (Sy). This then captures several events from the downstream hydrograph within a time slot similar to the translation time. The event detected at Sy with the amplitude most similar to Sx is designated as potential AE. […]

For these events, then the relative difference in amplitude is determined. Parabolas are fitted to the histogram obtained for the relative difference data binned into intervals from -1 to 1 of width 0.1 by fixing the vertex at the inner maximum of the histogram and the width is determined by minimizing the average squared distance between the parabola and the histogram data along arbitrary symmetric ranges from the inner maximum. Based on the fitted parabola cut points with the x-axis are determined such that only those potential AEs are retained where the relative difference is within these cut points. If this automatic scheme does not succeed to determine suitable cut points, e.g., because the estimated cut points are outside -1 and 1, then a strict criterion for the relative difference in amplitude is imposed to identify AEs considering only deviations of at most 10%."

estimate_AE() estimates suitable settings for the amplitude based on the method developed in Greimel et al. (2022) for exact time matches.

It performs this procedure for two neighboring hydrographs, i.e., it takes a subset of relation and the two corresponding Event files as input. The gauging station IDs in the subset of relation and in the Event files must match. Suitable settings for the amplitude are estimated as follows:

Sy$Time is shifted by the mean translation time between Sx and Sy.
Based on the time, exact matches between Sx and Sy are captured.
Relative difference in AMP are computed, e.g., (Sy$AMP - Sx$AMP) / Sx$AMP.
Matched events detected at Sy with the amplitude most similar to Sx are filtered. However, only matched events with an amplitude at Sy of at most two times the amplitude at Sx are considered as potential AEs.
The relative differences of potential AEs are binned into intervals of length 0.1 from -1 to 1. The created relative frequency table of the binned relative differences is passed to function get_parabola() where either suitable cut points with the x-axis are determined or a strict criterion is returned.
The table of the relative differences is visualized in a plot where the fitted parabola and the cut points with the x-axis are also shown.
The estimated settings for amplitude, a data frame of “real” AEs, i.e., associated events within the estimated cut points, and the plot are returned.

Note that the metric flow ratio (RATIO) does not make sense for S1 if the hydrograph is not of type Gauge. So metric RATIO is set to NA internally in this case.

The following code shows this procedure for two Event files:

# file paths
Sx <- system.file("testdata", "Events", "100000_2_2014-01-01_2014-02-28.csv",
                  package = "hydroroute")
Sy <- system.file("testdata", "Events", "200000_2_2014-01-01_2014-02-28.csv",
                  package = "hydroroute")
relation <- system.file("testdata", "relation.csv", package = "hydroroute")

# read data
Sx <- utils::read.csv(Sx)
Sy <- utils::read.csv(Sy)
relation <- utils::read.csv(relation)
relation <- relation[1:2, ]

# estimate AE, exact time matches
results <- estimate_AE(Sx, Sy, relation, timeLag = c(0, 1, 0))

results$settings
#>   station.x station.y bound lag    metric
#> 1        S1        S2 lower   0 0.9286046
#> 2        S1        S2 inner   1 1.0500000
#> 3        S1        S2 upper   0 1.1713954

Column bound represents the lower, inner and upper bounds that are used to subset potential AEs. lag represents the time lag. Only exact matches are used in this examples, which is specified by argument timeLag = c(0, 1, 0), which refers to 0 deviation at the lower and upper bound and 1 at the inner bound, meaning, that the mean translation time from relation is not altered when time matches are computed.

results$plot_threshold

head(results$real_AE)
#>     id.x event_type.x              time.x amp.x mafr.x   mefr.x dur.x   ratio.x
#> 1 100000            2 2014-01-11 17:15:00 39.01   20.4 13.00333     3 12.177650
#> 2 100000            2 2014-01-14 12:30:00 15.00    6.0  2.50000     6  1.262238
#> 3 100000            2 2014-01-15 06:15:00 77.14   38.3 12.85667     6 27.060811
#> 4 100000            2 2014-01-15 20:15:00 10.20    5.1  2.55000     4  1.312883
#> 5 100000            2 2014-01-19 06:45:00 74.41   23.7  9.30125     8 30.883534
#> 6 100000            2 2014-01-27 15:45:00  0.10    0.1  0.10000     1  1.001391
#>   station.x   id.y event_type.y              time.y amp.y mafr.y mefr.y dur.y
#> 1        S1 200000            2 2014-01-11 18:15:00 39.06   20.3  6.510     6
#> 2        S1 200000            2 2014-01-14 13:30:00 14.40    5.3  2.400     6
#> 3        S1 200000            2 2014-01-15 07:15:00 77.49   33.2 15.498     5
#> 4        S1 200000            2 2014-01-15 21:15:00 10.20    4.0  2.040     5
#> 5        S1 200000            2 2014-01-19 07:45:00 76.36   28.9  9.545     8
#> 6        S1 200000            2 2014-01-27 16:45:00  0.10    0.1  0.100     1
#>     ratio.y station.y   diff_metric
#> 1  7.804878        S2  1.281723e-03
#> 2  1.231140        S2 -4.000000e-02
#> 3 14.111675        S2  4.537205e-03
#> 4  1.280992        S2  0.000000e+00
#> 5 16.457490        S2  2.620616e-02
#> 6  1.001311        S2  1.469658e-13

Combine everything with `peaktrace()`

Function peaktrace combines the identification of potential AEs and the estimation of suitable amplitude settings for a whole river section as specified in a relation file. In addition, the flow metrics of the AEs are pictured by scatter plots and the translation and retention process between the hydrographs is described by linear models.

In the following, the input arguments of function peaktrace() are described:

relation_path: Is the path where the whole relation file from a river section is to be read from.
events_path: Is the path of the directory where the Event files are located. These files must correspond to the format described earlier in the section discussing the input data.
initial_values_path: Is the path where initial values for predicting the metric at the neighboring stations are to be read from. It should not contain missing values. But missing values can be imputed with a method specified in argument impute_method, which is by default max. An example for such a file is:

initial_values_path <- system.file("testdata", "initial_value_routing.csv",
                                   package = "hydroroute")
initials <- read.csv(initial_values_path)
initials
#>    Station Metric    Value   Name
#> 1       S1    AMP 93.00000  Q_max
#> 2       S1    AMP 69.75000 Q_0.75
#> 3       S1    AMP 46.50000  Q_0.5
#> 4       S1    AMP 23.25000 Q_0.25
#> 5       S1   MAFR 93.00000  Q_max
#> 6       S1   MAFR 69.75000 Q_0.75
#> 7       S1   MAFR 46.50000  Q_0.5
#> 8       S1   MAFR 23.25000 Q_0.25
#> 9       S1   MEFR 93.00000  Q_max
#> 10      S1   MEFR 69.75000 Q_0.75
#> 11      S1   MEFR 46.50000  Q_0.5
#> 12      S1   MEFR 23.25000 Q_0.25
#> 13      S1    DUR  1.00000      N
#> 14      S2  RATIO 19.90099    Max

The columns must be identical to this example. The content may vary. The initial values used for prediction must not contain any missing values.

Station refers to the gauging station of the hydrograph. Here, all initial values correspond to gauging station S1 except for metric RATIO, which starts at gauging station S2.
Metric corresponds to the metric. This is used to pick the corresponding fitted predictive model.
Value can be chosen arbitrarily or estimated with a data-driven approach. A unique Name is assigned which can be used to characterize the curve obtained from this initial value used to predict the metrics in downstream direction. E.g., for this example the initial values are set to certain quantiles of the metrics at station S1.

The return value of function peaktrace() is structured as follows:

A named list with one list element for each event_type.
For each event_type:
1. One element that contains the estimated settings from estimate_AE() for all gauging stations.
2. Plot of relative differences of AMP with cut points from settings_AE()` for all pairs of neighboring gauging stations.
3. Real AEs according to the estimated settings from estimate_AE() for all pairs of neighboring gauging stations and a column diff_metric that contains the relative difference in AMP.
4. A grid of scatter plots containing the AEs for neighboring hydrographs and for each metric with the fitted regression line.
5. Results of model fitting. Each row contains the corresponding stations and metric, the model type (default: “lm”), formula, coefficients, number of observations and $R^2$.
6. Plot of predicted values based on the initial values.

relation_path <- system.file("testdata", "relation.csv", package = "hydroroute")
events_path <- system.file("testdata", "Events", package = "hydroroute")
initial_values_path <- system.file("testdata", "initial_value_routing.csv",
                                   package = "hydroroute")
res <- peaktrace(relation_path, events_path, initial_values_path)

The first list object refers to event type 2 (IC event).

res$`2`$settings
#>   station.x station.y bound lag    metric
#> 1        S1        S2 lower   0 0.9286046
#> 2        S1        S2 inner   1 1.0500000
#> 3        S1        S2 upper   0 1.1713954
#> 4        S2        S3 lower   0 0.9019974
#> 5        S2        S3 inner   1 1.0500000
#> 6        S2        S3 upper   0 1.1980026
#> 7        S3        S4 lower   0 0.7711146
#> 8        S3        S4 inner   1 0.9500000
#> 9        S3        S4 upper   0 1.1288854

The settings data frame contains the estimated time lag and metric settings computed with estimate_AE(). In this example with 4 stations, it contains nine rows where three rows describe the relation between two neighboring stations. Since only exact time matches were allowed, the lag values are 0 for lower and upper bound and 1 for inner. metric contains the range of relative values of the amplitude allowed.
Events, where the relative difference in amplitude and the relative difference in time are within these settings, are considered as “real” AE and therefore events caused by disruptive factors are excluded as far as possible.

The following plot shows the histograms obtained for the relative differences in amplitude for each pair of neighboring gauging stations binned into intervals from -1 to 1 of width 0.1. The dashed line shows the fitted parabola and the cut points of the parabola with the x-axis are indicated. Potential AEs where the relative difference is within these cut points are considered as “real” AEs.

grid::grid.draw(res$`2`$plot_threshold)

The “real” AEs can be insepcted using:

head(res$`2`$real_AE)
#>     id.x event_type.x              time.x amp.x mafr.x   mefr.x dur.x   ratio.x
#> 1 100000            2 2014-01-11 17:15:00 39.01   20.4 13.00333     3 12.177650
#> 2 100000            2 2014-01-14 12:30:00 15.00    6.0  2.50000     6  1.262238
#> 3 100000            2 2014-01-15 06:15:00 77.14   38.3 12.85667     6 27.060811
#> 4 100000            2 2014-01-15 20:15:00 10.20    5.1  2.55000     4  1.312883
#> 5 100000            2 2014-01-19 06:45:00 74.41   23.7  9.30125     8 30.883534
#> 6 100000            2 2014-01-27 15:45:00  0.10    0.1  0.10000     1  1.001391
#>   station.x   id.y event_type.y              time.y amp.y mafr.y mefr.y dur.y
#> 1        S1 200000            2 2014-01-11 18:15:00 39.06   20.3  6.510     6
#> 2        S1 200000            2 2014-01-14 13:30:00 14.40    5.3  2.400     6
#> 3        S1 200000            2 2014-01-15 07:15:00 77.49   33.2 15.498     5
#> 4        S1 200000            2 2014-01-15 21:15:00 10.20    4.0  2.040     5
#> 5        S1 200000            2 2014-01-19 07:45:00 76.36   28.9  9.545     8
#> 6        S1 200000            2 2014-01-27 16:45:00  0.10    0.1  0.100     1
#>     ratio.y station.y   diff_metric
#> 1  7.804878        S2  1.281723e-03
#> 2  1.231140        S2 -4.000000e-02
#> 3 14.111675        S2  4.537205e-03
#> 4  1.280992        S2  0.000000e+00
#> 5 16.457490        S2  2.620616e-02
#> 6  1.001311        S2  1.469658e-13

The scatter plots of the metrics at the neighboring gauging stations for the “real” AEs are contained in plot_scatter. The scatter plots are arranged in a grid where each row contains scatter plots for a specific metric and each colums contains a different pair of neighboring gauging stations. The x-axis is the upstream hydrograph Sx, the y-axis is the downstream hydrograph Sy. A linear regression line and the corresponding $R^2$ value are added to each plot. By default the aspect ratio is fixed and the axis limits are equal within each plot.

grid::grid.draw(res$`2`$plot_scatter)

The fitted regression models may also be inspected:

res$`2`$models
#>    station.x station.y metric type formula  (Intercept)         x  n        r2
#> 1         S1        S2    amp   lm   y ~ x -0.377244258 1.0303350 19 0.9979228
#> 2         S1        S2    dur   lm   y ~ x  2.067669173 0.8285714 19 0.5135465
#> 3         S1        S2   mafr   lm   y ~ x -0.440654551 0.9439691 19 0.9551428
#> 4         S1        S2   mefr   lm   y ~ x  1.020255216 0.5914326 19 0.6819072
#> 5         S1        S2  ratio   lm   y ~ x  0.676332880 0.5637640 19 0.9812847
#> 6         S2        S3    amp   lm   y ~ x  0.664033077 1.0000771 48 0.9979394
#> 7         S2        S3    dur   lm   y ~ x -0.060168880 1.0202826 48 0.9312795
#> 8         S2        S3   mafr   lm   y ~ x  0.338584951 1.2772993 48 0.9733938
#> 9         S2        S3   mefr   lm   y ~ x  0.541783935 0.7533491 48 0.9615361
#> 10        S2        S3  ratio   lm   y ~ x  0.409250880 0.6672002 48 0.9947602
#> 11        S3        S4    amp   lm   y ~ x -0.105807545 0.9738516 22 0.9885472
#> 12        S3        S4    dur   lm   y ~ x -0.007334963 1.0207824 22 0.4009188
#> 13        S3        S4   mafr   lm   y ~ x  1.857559005 0.6542612 22 0.8790622
#> 14        S3        S4   mefr   lm   y ~ x  0.983509431 0.8140004 22 0.8216348
#> 15        S3        S4  ratio   lm   y ~ x  0.902987364 0.4858827 22 0.4856234

The models data frame contains the fitted (linear) models for each pair of neighboring stations and each metric.

station.x is the upstream hydrograph Sx.
station.y is the downstream hydrograph Sy.
metric is the name of the corresponding metric.
type is the model class, by default lm.
formula is the expression that is used to fit the model.
(Intercept), x are the extracted coefficients (called with coef).
n is the number of events used to fit the model.
r2 is the extracted or computed $R^2$ for each model.

Finally the fitted regression models are used to predict the values of the metrics along the longitudinal flow path given the initial values:

gridExtra::grid.arrange(grobs = res$`2`$plot_predict$grobs, nrow = 3, ncol = 2)

If a file with initial values is passed to peaktrace(), predictions along the longitudinal flow path are made and visualized in a plot. Each line in the plot represents a different scenario, e.g., the uppermost solid lines for AMP, MAFR and MEFR represent the values of Q_max in the initial file. Starting from these initial values, predictions are made with the corresponding models, e.g., the first value of the initial valus file is passed to the model that describes the relationship of AMP between S1 and S2 to predict the value at S2.

The initial value and the first fitted model are:

initials[1, ]
#>   Station Metric Value  Name
#> 1      S1    AMP    93 Q_max
res$`2`$models[1, ]
#>   station.x station.y metric type formula (Intercept)        x  n        r2
#> 1        S1        S2    amp   lm   y ~ x  -0.3772443 1.030335 19 0.9979228

The resulting predicted value is then passed to the next model along the flow path, i.e., the model of S2 and S3 to predict the value at S3.

res$`2`$models[6, ]
#>   station.x station.y metric type formula (Intercept)        x  n        r2
#> 6        S2        S3    amp   lm   y ~ x   0.6640331 1.000077 48 0.9979394

Finally, this predicted value is passed to the last model along this river section: the model between S3 and S4 to predict the value at S4.

res$`2`$models[11, ]
#>    station.x station.y metric type formula (Intercept)         x  n        r2
#> 11        S3        S4    amp   lm   y ~ x  -0.1058075 0.9738516 22 0.9885472

This procedure is repeated for all metrics according to the initial values file. Note that in this initial values file metric RATIO starts at station S2. Therefore the first value of RATIO to predict is at station S3.

The second list object refers to event type 4 (DC event). The nested objects of this event type are shown below.

res$`4`$settings
#>   station.x station.y bound lag    metric
#> 1        S1        S2 lower   0 0.8145994
#> 2        S1        S2 inner   1 0.9500000
#> 3        S1        S2 upper   0 1.0854006
#> 4        S2        S3 lower   0 0.9209006
#> 5        S2        S3 inner   1 1.0500000
#> 6        S2        S3 upper   0 1.1790994
#> 7        S3        S4 lower   0 0.7296107
#> 8        S3        S4 inner   1 0.9500000
#> 9        S3        S4 upper   0 1.1703893

head(res$`4`$real_AE)
#>     id.x event_type.x              time.x amp.x mafr.x   mefr.x dur.x   ratio.x
#> 1 100000            4 2014-01-02 07:45:00 27.44  13.98 6.860000     4 12.154472
#> 2 100000            4 2014-01-03 18:15:00 26.87  13.90 5.374000     5  9.867987
#> 3 100000            4 2014-01-04 08:15:00 27.39  13.44 1.245000    22 10.099668
#> 4 100000            4 2014-01-07 08:00:00 27.84  14.60 3.977143     7 12.796610
#> 5 100000            4 2014-01-09 01:45:00  0.10   0.10 0.100000     1  1.003367
#> 6 100000            4 2014-01-09 08:45:00  0.10   0.10 0.100000     1  1.001634
#>   station.x   id.y event_type.y              time.y amp.y mafr.y    mefr.y
#> 1        S1 200000            4 2014-01-02 08:45:00 26.37    6.2 1.6481250
#> 2        S1 200000            4 2014-01-03 19:15:00 25.84    6.4 1.9876923
#> 3        S1 200000            4 2014-01-04 09:15:00 27.29    6.3 0.8269697
#> 4        S1 200000            4 2014-01-07 09:00:00 26.75    6.5 1.4861111
#> 5        S1 200000            4 2014-01-09 02:45:00  0.10    0.1 0.1000000
#> 6        S1 200000            4 2014-01-09 09:45:00  0.10    0.1 0.1000000
#>   dur.y  ratio.y station.y   diff_metric
#> 1    16 8.069705        S2 -3.899417e-02
#> 2    13 6.007752        S2 -3.833271e-02
#> 3    33 7.188209        S2 -3.650968e-03
#> 4    18 8.328767        S2 -3.915230e-02
#> 5     1 1.003247        S2 -3.108624e-14
#> 6     1 1.001565        S2  6.702972e-14

grid::grid.draw(res$`4`$plot_threshold)

grid::grid.draw(res$`4`$plot_scatter)

res$`4`$models
#>    station.x station.y metric type formula (Intercept)         x  n        r2
#> 1         S1        S2    amp   lm   y ~ x  -0.6190171 1.0148836 42 0.9972531
#> 2         S1        S2    dur   lm   y ~ x   6.8921955 0.9216949 42 0.5252316
#> 3         S1        S2   mafr   lm   y ~ x   0.1571962 0.5572280 42 0.8463763
#> 4         S1        S2   mefr   lm   y ~ x   0.9501539 0.2137833 42 0.2878343
#> 5         S1        S2  ratio   lm   y ~ x   0.3400903 0.6014280 42 0.9866592
#> 6         S2        S3    amp   lm   y ~ x   0.8142924 0.9876290 85 0.9969959
#> 7         S2        S3    dur   lm   y ~ x   2.0450832 0.7109990 85 0.8977360
#> 8         S2        S3   mafr   lm   y ~ x   0.5882917 0.9100048 85 0.9552515
#> 9         S2        S3   mefr   lm   y ~ x   0.6619488 0.7858019 85 0.8479033
#> 10        S2        S3  ratio   lm   y ~ x   0.6995621 0.5642271 85 0.9739526
#> 11        S3        S4    amp   lm   y ~ x  -0.5237764 0.9892361 20 0.9505922
#> 12        S3        S4    dur   lm   y ~ x   2.0875629 0.5934821 20 0.6466735
#> 13        S3        S4   mafr   lm   y ~ x  -0.5674951 1.0119329 20 0.6077902
#> 14        S3        S4   mefr   lm   y ~ x   0.4711672 1.0970619 20 0.6502208
#> 15        S3        S4  ratio   lm   y ~ x   1.1018134 0.2806048 20 0.6643971

gridExtra::grid.arrange(grobs = res$`4`$plot_predict$grobs, nrow = 3, ncol = 2)

Extract AEs and perform routing with existing settings

If estimated settings are already available, it is possible to use the settings directly to extract “real” AEs from the Event data. For such an analysis, a path to a relation file must be provided, as well as a path to the Event data and paths to settings and initial values.

Extract AEs

The following code shows the extraction of “real” AEs based on the settings file which is included in the package after having been generated with estimate_AE().

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_settings.csv",
                         package = "hydroroute")
initials_path <- system.file("testdata", "initial_value_routing.csv",
                             package = "hydroroute")
real_AE <- extract_AE(relation_path, events_path, settings_path)
head(real_AE)
#>     id.x event_type.x              time.x amp.x mafr.x   mefr.x dur.x   ratio.x
#> 1 100000            2 2014-01-11 17:15:00 39.01   20.4 13.00333     3 12.177650
#> 2 100000            2 2014-01-14 12:30:00 15.00    6.0  2.50000     6  1.262238
#> 3 100000            2 2014-01-15 06:15:00 77.14   38.3 12.85667     6 27.060811
#> 4 100000            2 2014-01-15 20:15:00 10.20    5.1  2.55000     4  1.312883
#> 5 100000            2 2014-01-19 06:45:00 74.41   23.7  9.30125     8 30.883534
#> 6 100000            2 2014-01-27 15:45:00  0.10    0.1  0.10000     1  1.001391
#>   station.x   id.y event_type.y              time.y amp.y mafr.y mefr.y dur.y
#> 1        S1 200000            2 2014-01-11 18:15:00 39.06   20.3  6.510     6
#> 2        S1 200000            2 2014-01-14 13:30:00 14.40    5.3  2.400     6
#> 3        S1 200000            2 2014-01-15 07:15:00 77.49   33.2 15.498     5
#> 4        S1 200000            2 2014-01-15 21:15:00 10.20    4.0  2.040     5
#> 5        S1 200000            2 2014-01-19 07:45:00 76.36   28.9  9.545     8
#> 6        S1 200000            2 2014-01-27 16:45:00  0.10    0.1  0.100     1
#>     ratio.y station.y   diff_metric
#> 1  7.804878        S2  1.281723e-03
#> 2  1.231140        S2 -4.000000e-02
#> 3 14.111675        S2  4.537205e-03
#> 4  1.280992        S2  0.000000e+00
#> 5 16.457490        S2  2.620616e-02
#> 6  1.001311        S2  1.469658e-13

Routing

With the extracted “real” AEs, the routing procedure can be performed to describe the translation and retention processes between neighboring hydrographs.

Therefore, the output from extract_AE() (or similar, the output $real_AE from estimate_AE()), the initial values data frame and the relation data frame have to be passed to function routing().

relation <- utils::read.csv(relation_path)
initials <- utils::read.csv(initials_path)
res <- routing(real_AE, initials, relation)

This produces the same scatter plot as before when peaktrace() was called as the events and the settings are the same.

grid::grid.draw(res$plot_scatter)

res$models
#>    station.x station.y metric type formula  (Intercept)         x  n        r2
#> 1         S1        S2    amp   lm   y ~ x -0.377244258 1.0303350 19 0.9979228
#> 2         S1        S2    dur   lm   y ~ x  2.067669173 0.8285714 19 0.5135465
#> 3         S1        S2   mafr   lm   y ~ x -0.440654551 0.9439691 19 0.9551428
#> 4         S1        S2   mefr   lm   y ~ x  1.020255216 0.5914326 19 0.6819072
#> 5         S1        S2  ratio   lm   y ~ x  0.676332880 0.5637640 19 0.9812847
#> 6         S2        S3    amp   lm   y ~ x  0.664033077 1.0000771 48 0.9979394
#> 7         S2        S3    dur   lm   y ~ x -0.060168880 1.0202826 48 0.9312795
#> 8         S2        S3   mafr   lm   y ~ x  0.338584951 1.2772993 48 0.9733938
#> 9         S2        S3   mefr   lm   y ~ x  0.541783935 0.7533491 48 0.9615361
#> 10        S2        S3  ratio   lm   y ~ x  0.409250880 0.6672002 48 0.9947602
#> 11        S3        S4    amp   lm   y ~ x -0.105807545 0.9738516 22 0.9885472
#> 12        S3        S4    dur   lm   y ~ x -0.007334963 1.0207824 22 0.4009188
#> 13        S3        S4   mafr   lm   y ~ x  1.857559005 0.6542612 22 0.8790622
#> 14        S3        S4   mefr   lm   y ~ x  0.983509431 0.8140004 22 0.8216348
#> 15        S3        S4  ratio   lm   y ~ x  0.902987364 0.4858827 22 0.4856234

gridExtra::grid.arrange(grobs = res$plot_predict$grobs, nrow = 3, ncol = 2)

Introduction to hydroroute

Julia Haider

Introduction

Input data

Dataset `Q`

Dataset `relation`

Event files

Get mean translation time between hydrographs with `get_lag()`

Estimate settings with `estimate_AE()`

Combine everything with `peaktrace()`

Extract AEs and perform routing with existing settings

Extract AEs

Routing

References

Introduction to hydroroute

Julia Haider

Introduction

Input data

Dataset Q

Dataset relation

Event files

Get mean translation time between hydrographs with get_lag()

Estimate settings with estimate_AE()

Combine everything with peaktrace()

Extract AEs and perform routing with existing settings

Extract AEs

Routing

References

Dataset `Q`

Dataset `relation`

Get mean translation time between hydrographs with `get_lag()`

Estimate settings with `estimate_AE()`

Combine everything with `peaktrace()`