Purpose
hyd1d is an R package that provides an S4-class and several functions to compute 1-dimensional water levels along the German federal waterways Elbe and Rhine.
Use
Installation
The package hyd1d is available from CRAN. To install it run:
install.packages("hyd1d")To install the recent developmental version from Github execute the following commands:
install.packages("devtools")
library(devtools)
devtools::install_github("bafg-bund/hyd1d")Afterwards hyd1d can be loaded like every other R package with the following command:
S4-class WaterLevelDataFrame
All water level computations with hyd1d are based on
the S4-class WaterLevelDataFrame.
To compute water levels with one of the waterLevel…()-functions,
a WaterLevelDataFrame
has to be initialized with the homonymous
WaterLevelDataFrame()-function:
wldf <- WaterLevelDataFrame(river = "Elbe",
time = as.POSIXct("2016-12-21"),
station = seq(257, 262, 0.1))The required information to initialize a WaterLevelDataFrame
are the function arguments river, time and at
least one of the two possible station arguments (station or
station_int). With this information an object of class
WaterLevelDataFrame
can be created, which has the following structure:
str(wldf)
#> 'data.frame': 51 obs. of 3 variables:
#> Formal class 'WaterLevelDataFrame' [package "hyd1d"] with 9 slots
#> ..@ .Data :List of 3
#> .. ..$ : num 257 257 257 257 257 ...
#> .. ..$ : int 257000 257100 257200 257300 257400 257500 257600 257700 257800 257900 ...
#> .. ..$ : num NA NA NA NA NA NA NA NA NA NA ...
#> ..@ river : chr "Elbe"
#> ..@ time : POSIXct, format: "2016-12-21"
#> ..@ gauging_stations :'data.frame': 0 obs. of 27 variables:
#> .. ..$ id : int
#> .. ..$ gauging_station : chr
#> .. ..$ uuid : chr
#> .. ..$ km : num
#> .. ..$ km_qps : num
#> .. ..$ river : chr
#> .. ..$ longitude : num
#> .. ..$ latitude : num
#> .. ..$ mw : num
#> .. ..$ mw_timespan : chr
#> .. ..$ pnp : num
#> .. ..$ w : num
#> .. ..$ wl : num
#> .. ..$ n_wls_below_w_do : int
#> .. ..$ n_wls_above_w_do : int
#> .. ..$ n_wls_below_w_up : int
#> .. ..$ n_wls_above_w_up : int
#> .. ..$ name_wl_below_w_do: chr
#> .. ..$ name_wl_above_w_do: chr
#> .. ..$ name_wl_below_w_up: chr
#> .. ..$ name_wl_above_w_up: chr
#> .. ..$ w_wl_below_w_do : num
#> .. ..$ w_wl_above_w_do : num
#> .. ..$ w_wl_below_w_up : num
#> .. ..$ w_wl_above_w_up : num
#> .. ..$ weight_up : num
#> .. ..$ weight_do : num
#> ..@ gauging_stations_missing: chr NA
#> ..@ comment : chr "Initialised by WaterLevelDataFrame()."
#> ..@ names : chr "station" "station_int" "w"
#> ..@ row.names : int 1 2 3 4 5 6 7 8 9 10 ...
#> ..@ .S3Class : chr "data.frame"
summary(wldf)
#> $slots
#>
#> river Elbe
#> time 2016-12-21
#> gauging_stations None
#> gauging_stations_missing None
#> comment Initialised by WaterLevelDataFrame().
#>
#> $data
#> station station_int w
#> Min. :257.0 Min. :257000 Min. : NA
#> 1st Qu.:258.2 1st Qu.:258250 1st Qu.: NA
#> Median :259.5 Median :259500 Median : NA
#> Mean :259.5 Mean :259500 Mean :NaN
#> 3rd Qu.:260.8 3rd Qu.:260750 3rd Qu.: NA
#> Max. :262.0 Max. :262000 Max. : NA
#> NA's :51The actual water level information is stored in the S4-slot
.Data, which is in fact a data.frame with the
columns station, station_int and
w. The columns station and
station_int contain a stationing information, which
corresponds to the official stationing of the German Waterways and
Shipping Administration (Wasserstraßen- und Schifffahrtsverwaltung
(WSV)). The stationing information is duplicated to enable database
joins with GIS data through the integer-type column
station_int. The column w contains the actual
water level in the height reference system DHHN92 (1992 German height
reference system), but is usually empty after initialization and gets
filled throught the application of one of the waterLevel…()-functions.
For the application of waterLevel…()-functions
information stored in the S4-slots river and where
appropriate time is essential. They enable a distinct
localization of the stationing along the rivers Elbe and Rhine and a
determination of the time of water level computation. The other slots of
an object of class WaterLevelDataFrame
are filled during the water level computation and contain partial
results needed to visualize the results (gauging_station)
or serve information purposes ( gauging_stations_missing,
comment).
Computation of water levels
waterLevel
The most advanced function to interpolate FLYS3
water levels (Bundesanstalt für
Gewässerkunde, 2013, 2016)
with local gauging data is implemented in the
waterLevel()-function. This function uses package-internal
gauging data from the dataset df.gauging_data,
which contains daily-averaged gauging data since 1960-01-01. Therefore
waterLevel() can be applied for the time period between
1960-01-01 and yesterday.
After the initialization of a
WaterLevelDataFrame
the application is very simple:
wldf <- waterLevel(wldf)
summary(wldf)
#> $slots
#>
#> river Elbe
#> time 2016-12-21
#> gauging_stations VOCKERODE, ROSSLAU, DESSAU, AKEN
#> gauging_stations_missing None
#> comment Computed by waterLevel().
#>
#> $data
#> station station_int w
#> Min. :257.0 Min. :257000 Min. :54.42
#> 1st Qu.:258.2 1st Qu.:258250 1st Qu.:54.67
#> Median :259.5 Median :259500 Median :54.82
#> Mean :259.5 Mean :259500 Mean :54.87
#> 3rd Qu.:260.8 3rd Qu.:260750 3rd Qu.:55.11
#> Max. :262.0 Max. :262000 Max. :55.35And if you want to visualize the results using
plotShiny() the additional argument
shiny = TRUE has to be used. Thereby the columns
section, weight_x and weight_y
get created in the .Data-Slot, which are required for
visualization.
wldf <- waterLevel(wldf, shiny = TRUE)
summary(wldf)
#> $slots
#>
#> river Elbe
#> time 2016-12-21
#> gauging_stations VOCKERODE, ROSSLAU, DESSAU, AKEN
#> gauging_stations_missing None
#> comment Computed by waterLevel().
#>
#> $data
#> station station_int w section
#> Min. :257.0 Min. :257000 Min. :54.42 Min. :1.00
#> 1st Qu.:258.2 1st Qu.:258250 1st Qu.:54.67 1st Qu.:2.00
#> Median :259.5 Median :259500 Median :54.82 Median :2.00
#> Mean :259.5 Mean :259500 Mean :54.87 Mean :2.02
#> 3rd Qu.:260.8 3rd Qu.:260750 3rd Qu.:55.11 3rd Qu.:2.00
#> Max. :262.0 Max. :262000 Max. :55.35 Max. :3.00
#> weight_x weight_y
#> Min. :0.008197 Min. :0.1000
#> 1st Qu.:0.161765 1st Qu.:0.1911
#> Median :0.529412 Median :0.2640
#> Mean :0.520204 Mean :0.3192
#> 3rd Qu.:0.897059 3rd Qu.:0.4294
#> Max. :1.000000 Max. :0.6302
xlim_min <- 257
xlim_max <- 263
{
plotShiny(wldf, TRUE, TRUE, TRUE, xlim = c(xlim_min, xlim_max),
xlab = "river station (km)",
ylab = "elevation (m a.s.l. (DHHN92))")
legend("topright",
col = c("darkblue", "darkblue", "darkblue", "red", "black"),
pch = c(21, NA, NA, NA, NA),
pt.bg = c("darkblue", NA, NA, NA, NA),
pt.cex = c(1, NA, NA, NA, NA),
lty = c(0, 0, 1, 1, 1),
lwd = c(0, 0, 1, 0.6, 0.6),
legend = c("gauge height", "gauge weight", "waterLevel",
"upper FLYS w.l.", "lower FLYS w.l."),
text.col = c(1, "darkblue", 1, 1, 1),
cex = 0.7, bty = "n")
} water levels (**0.5MQ**, **a** and **0.75MQ**) and gauge height as of 2016-12-21 at River Elbe between Rosslau and Dessau.](hyd1d_files/figure-html/figure1-1.png)
Fig. 1: Interpolated water level, computation-relevant stationary FLYS3 water levels (0.5MQ, a and 0.75MQ) and gauge height as of 2016-12-21 at River Elbe between Rosslau and Dessau.
waterLevelPegelonline
The way how the waterLevelPegelonline()-function
computes a water level is equivalent to the
waterLevel()-function. Just the data source of the gauging
data is different, since it does not use package-internal data, but
online data provided by https://pegelonline.wsv.de/gast/start (Wasserstraßen- und
Schifffahrtsverwaltung des Bundes (WSV), 2022). Because data
provided by PEGELONLINE are only
available for the past 30 days, the application of this function is
limited to recent time periods, but with a high temporal resolution.
# one hour ago
time <- as.POSIXct(Sys.time() - 3600)
# initialize a WaterLevelDataFrame
wldf <- WaterLevelDataFrame(river = "Elbe",
time = time,
station = seq(257, 262, 0.1))
# compute w
wldf <- waterLevelPegelonline(wldf, shiny = TRUE)
summary(wldf)
#> $slots
#>
#> river Elbe
#> time 2024-09-12 09:22:42.965667
#> gauging_stations VOCKERODE, ROSSLAU, DESSAU, AKEN
#> gauging_stations_missing None
#> comment Computed by waterLevelPegelonline().
#>
#> $data
#> station station_int w section
#> Min. :257.0 Min. :257000 Min. :53.62 Min. :1.00
#> 1st Qu.:258.2 1st Qu.:258250 1st Qu.:53.94 1st Qu.:2.00
#> Median :259.5 Median :259500 Median :54.10 Median :2.00
#> Mean :259.5 Mean :259500 Mean :54.14 Mean :2.02
#> 3rd Qu.:260.8 3rd Qu.:260750 3rd Qu.:54.42 3rd Qu.:2.00
#> Max. :262.0 Max. :262000 Max. :54.65 Max. :3.00
#> weight_x weight_y
#> Min. :0.008197 Min. :0.4632
#> 1st Qu.:0.161765 1st Qu.:0.5067
#> Median :0.529412 Median :0.6276
#> Mean :0.520204 Mean :0.6280
#> 3rd Qu.:0.897059 3rd Qu.:0.7485
#> Max. :1.000000 Max. :0.7921
# and plot the results
{
plotShiny(wldf, TRUE, TRUE, TRUE, xlim = c(xlim_min, xlim_max),
xlab = "river station (km)",
ylab = "elevation (m a.s.l. (DHHN92))")
legend("topright",
col = c("darkblue", "darkblue", "darkblue", "red", "black"),
pch = c(21, NA, NA, NA, NA),
pt.bg = c("darkblue", NA, NA, NA, NA),
pt.cex = c(1, NA, NA, NA, NA),
lty = c(0, 0, 1, 1, 1),
lwd = c(0, 0, 1, 0.6, 0.6),
legend = c("gauge height", "gauge weight", "waterLevel",
"upper FLYS w.l.", "lower FLYS w.l."),
text.col = c(1, "darkblue", 1, 1, 1),
cex = 0.7, bty = "n")
} water levels (**0.5MQ**, **a** and **0.75MQ**) and gauge height as of 2024-09-12 09:22 at River Elbe between Rosslau and Dessau.](hyd1d_files/figure-html/figure2-1.png)
Fig. 2: Interpolated water level, computation-relevant stationary FLYS3 water levels (0.5MQ, a and 0.75MQ) and gauge height as of 2024-09-12 09:22 at River Elbe between Rosslau and Dessau.
waterLevelFlood1 & waterLevelFlood2
To compare the newly developed functions waterLevel()
and waterLevelPegelonline() to existing computation
methods, the functions waterLevelFlood1() and
waterLevelFlood2() have been implemented. These functions
compute water levels according to the Flood1- and Flood2-methods of the
modelling environment INFORM
(Rosenzweig, Giebel, & Schleuter,
2011). They either shift the reference water level
MQ vertically, so that it intersects with the gauge
height at a selected reference gauging station, or linearly interpolate
water levels with neighboring gauging stations.
wldf <- WaterLevelDataFrame(river = "Elbe",
time = as.POSIXct("2016-12-21"),
station = seq(257, 262, 0.1))
wldf1 <- waterLevelFlood1(wldf, "ROSSLAU", shiny = TRUE)
summary(wldf1)
#> $slots
#>
#> river Elbe
#> time 2016-12-21
#> gauging_stations ROSSLAU
#> gauging_stations_missing None
#> comment Computed by waterLevelFlood1(): gauging_station = ROSSLAU, w = 137
#>
#> $data
#> station station_int w section weight_x
#> Min. :257.0 Min. :257000 Min. :54.15 Min. :1 Min. :1
#> 1st Qu.:258.2 1st Qu.:258250 1st Qu.:54.44 1st Qu.:1 1st Qu.:1
#> Median :259.5 Median :259500 Median :54.68 Median :1 Median :1
#> Mean :259.5 Mean :259500 Mean :54.73 Mean :1 Mean :1
#> 3rd Qu.:260.8 3rd Qu.:260750 3rd Qu.:55.05 3rd Qu.:1 3rd Qu.:1
#> Max. :262.0 Max. :262000 Max. :55.36 Max. :1 Max. :1
#> weight_y
#> Min. :-0.92
#> 1st Qu.:-0.92
#> Median :-0.92
#> Mean :-0.92
#> 3rd Qu.:-0.92
#> Max. :-0.92
wldf2 <- waterLevelFlood1(wldf, "DESSAU", shiny = TRUE)
summary(wldf2)
#> $slots
#>
#> river Elbe
#> time 2016-12-21
#> gauging_stations DESSAU
#> gauging_stations_missing None
#> comment Computed by waterLevelFlood1(): gauging_station = DESSAU, w = 165
#>
#> $data
#> station station_int w section weight_x
#> Min. :257.0 Min. :257000 Min. :54.43 Min. :1 Min. :1
#> 1st Qu.:258.2 1st Qu.:258250 1st Qu.:54.72 1st Qu.:1 1st Qu.:1
#> Median :259.5 Median :259500 Median :54.96 Median :1 Median :1
#> Mean :259.5 Mean :259500 Mean :55.01 Mean :1 Mean :1
#> 3rd Qu.:260.8 3rd Qu.:260750 3rd Qu.:55.33 3rd Qu.:1 3rd Qu.:1
#> Max. :262.0 Max. :262000 Max. :55.64 Max. :1 Max. :1
#> weight_y
#> Min. :-0.64
#> 1st Qu.:-0.64
#> Median :-0.64
#> Mean :-0.64
#> 3rd Qu.:-0.64
#> Max. :-0.64
wldf3 <- waterLevelFlood2(wldf)
summary(wldf3)
#> $slots
#>
#> river Elbe
#> time 2016-12-21
#> gauging_stations VOCKERODE, ROSSLAU, DESSAU, AKEN
#> gauging_stations_missing None
#> comment Computed by waterLevelFlood2()
#>
#> $data
#> station station_int w
#> Min. :257.0 Min. :257000 Min. :54.43
#> 1st Qu.:258.2 1st Qu.:258250 1st Qu.:54.68
#> Median :259.5 Median :259500 Median :54.90
#> Mean :259.5 Mean :259500 Mean :54.90
#> 3rd Qu.:260.8 3rd Qu.:260750 3rd Qu.:55.12
#> Max. :262.0 Max. :262000 Max. :55.35
Fig. 3: Water levels computed according to the Flood1-method with the reference gauges Rosslau (wldf1) and Dessau (wldf2) and the Flood2-method as of 2016-12-21 at River Elbe between Rosslau and Dessau.
waterLevelFlys3InterpolateY
To compare the newly developed functions waterLevel()
and waterLevelPegelonline
to existing computation methods of FLYS3,
the function waterLevelFlys3InterpolateY() has been
implemented. This function computes a water level according to the
method implemented in the W-INFO-module of FLYS3.
This function determines the relative position of the gauge height at a
reference gauge to the two surrounding FLYS3
water levels and uses this weight for a longitudinal interpolation
between both water levels.
wldf <- waterLevelFlys3InterpolateY(wldf, "ROSSLAU", shiny = TRUE)
summary(wldf)
#> $slots
#>
#> river Elbe
#> time 2016-12-21
#> gauging_stations ROSSLAU
#> gauging_stations_missing None
#> comment Computed by waterLevelFlys3InterpolateY(): gauging_station = ROSSLAU, w = 137
#>
#> $data
#> station station_int w section weight_x
#> Min. :257.0 Min. :257000 Min. :54.11 Min. :1 Min. :1
#> 1st Qu.:258.2 1st Qu.:258250 1st Qu.:54.42 1st Qu.:1 1st Qu.:1
#> Median :259.5 Median :259500 Median :54.67 Median :1 Median :1
#> Mean :259.5 Mean :259500 Mean :54.72 Mean :1 Mean :1
#> 3rd Qu.:260.8 3rd Qu.:260750 3rd Qu.:55.08 3rd Qu.:1 3rd Qu.:1
#> Max. :262.0 Max. :262000 Max. :55.35 Max. :1 Max. :1
#> weight_y
#> Min. :0.1786
#> 1st Qu.:0.1786
#> Median :0.1786
#> Mean :0.1786
#> 3rd Qu.:0.1786
#> Max. :0.1786 with the reference gauge Rosslau as of 2016-12-21 at River Elbe between Rosslau and Dessau.](hyd1d_files/figure-html/figure4-1.png)
Fig. 4: Water levels according to FLYS3 with the reference gauge Rosslau as of 2016-12-21 at River Elbe between Rosslau and Dessau.
waterLevelFlys3…
All other waterLevelFlys3...()-functions
(waterLevelFlys3(), waterLevelFlys3Seq() and
waterLevelFlys3InterpolateX()) serve exclusively for the
preparation and querying of stationary FLYS3
water levels. They can be used to extract water levels from the dataset
df.flys
and interpolate the water levels linearly along the x-axis, but without
modifying the dataset contents. These functionalities are needed for
all waterLevel…()-functions
described in this vignette and are mentioned here for completeness.
Products
waterLevel
The waterLevel() function is the central function of the
package hyd1d. To apply it only three input parameters,
that are needed to initialize a WaterLevelDataFrame,
are required. That predestines this function to embed it into an
interactive Shiny Application:
https://shiny.bafg.de/waterlevel/
 with the interpolated water level, caomputationrevelvant stationary [FLYS3](https://www.bafg.de/DE/5_Informiert/1_Portale_Dienste/FLYS/flys_node.html)-waterlevels (**0.5MQ**, **a** and **0.75MQ**) and gauge heights at 2016-12-21 at the River Elbe between Rosslau and Dessau, Germany.](screenshot_waterLevel.png)
Fig. 5: Screenshot of the waterLevel-ShinyApp with the interpolated water level, caomputationrevelvant stationary FLYS3-waterlevels (0.5MQ, a and 0.75MQ) and gauge heights at 2016-12-21 at the River Elbe between Rosslau and Dessau, Germany.
waterLevelPegelonline
The same is true for the function waterLevelPegelonline().
Since this function queries gauging data through the internet and not
from package-internal datasets, the resulting shiny application is well
suited to generate up-to-date water level information.
https://shiny.bafg.de/waterlevelpegelonline/
 with the interpolated water level, computationrevelvant stationary [FLYS3](https://www.bafg.de/DE/5_Informiert/1_Portale_Dienste/FLYS/flys_node.html)-waterlevels (**a**, **0.75MQ** and **0.5MQ**) and gauge heights at 2018-04-13 11:00 a.m. at the River Elbe between Rosslau and Dessau, Germany.](screenshot_waterLevelPegelonline.png)
Fig. 6: Screenshot of the waterLevelPegelonline-ShinyApp with the interpolated water level, computationrevelvant stationary FLYS3-waterlevels (a, 0.75MQ and 0.5MQ) and gauge heights at 2018-04-13 11:00 a.m. at the River Elbe between Rosslau and Dessau, Germany.
hydflood (flood extents and durations)
The R package hydflood enables the modelling of flood extents and durations through an extrapolation of water levels computed along the river axis with functions provided within R package hyd1d to cross section areas and GIS operations comparing these water levels to digital elevation models. Daily flood extents can be aggregated over longer time periods to flood durations (e.g. days/year). More details to this method can be found on the corresponding package documentation of hydflood: