Introduction to grwat R package
In grwat: River Hydrograph Separation and Analysis

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Example data

Throughout grwat package documentation a sample dataset spas containing the daily runoff data for Spas-Zagorye gauge on Protva river in Central European plane is used. The dataset is supplemented by meteorological variables (temperature and precipitation) obtained from CIRES-DOE (1880-1949) and ERA5 (1950-2021) data averaged inside gauge's basin:

library(grwat)
library(dplyr)
library(ggplot2)
library(lubridate)

data(spas)
head(spas)

This 4-column representation is standard for advanced separation discussed below.

Baseflow filtering

For more information on baseflow filtering, read the Baseflow filtering vignette.

grwat implements several methods for baseflow filtering. The get_baseflow() function does the job:

Qbase = gr_baseflow(spas$Q, method = 'lynehollick', a = 0.925, passes = 3)
head(Qbase)

Though get_baseflow() needs just a vector of runoff values, it can be applied in a traditional tidyverse pipeline like follows:

# Calculate baseflow using Jakeman approach
hdata = spas %>% 
  mutate(Qbase = gr_baseflow(Q, method = 'jakeman'))

# Visualize for 2020 year
ggplot(hdata) +
  geom_area(aes(Date, Q), fill = 'steelblue', color = 'black') +
  geom_area(aes(Date, Qbase), fill = 'orangered', color = 'black') +
  scale_x_date(limits = c(ymd(19800101), ymd(19801231)))

Advanced hydrograph separation

For more information on advanced separation, read the Advanced separation vignette.

Advanced separation by gr_separate() implements the method by [@rets2022], which involves additional data on temperatures and precipitation to detect and classify flood events into the rain, thaw and spring (seasonal thaw). Between these events $100\%$ of the runoff is considered to be ground. Inside those events the ground flow is filtered either by one of the baseflow functions, or by Kudelin's method, which degrades baseflow to $0$ under the maximum runoff value during the year.

The method is controlled by more than 20 parameters, which can be region-specific. Therefore, to ease the management and distribution of these parameters, they are organized as list, as returned by gr_get_params():

sep = gr_separate(spas, params = gr_get_params(reg = 'center'))
head(sep)

Resulting separation can be visualized by gr_plot_sep() function. In addition to classification of the flow, the function shows the dates of the spring seasonal flood:

gr_plot_sep(sep, years = c(1978, 1989))

Summaries

For more information on annual variables, read the Summaries vignette.

After hydrograph is separated, its characteristics can be summarized by gr_summarize() into annual variables which characterize the annual runoff, its components (ground, spring, rain and thaw) and low flow periods (summer and winter):

vars = gr_summarize(sep)
head(vars)

These characteristics can be plotted by gr_plot_vars():

gr_plot_vars(vars, Qygr)
gr_plot_vars(vars, D10w1, Wsprngr, Nthw, Qrnmax, tests = TRUE,
             layout = matrix(1:4, nrow = 2, byrow = TRUE))

Additional features

grwat contains some useful functions that can facilitate your work with runoff data. In particular:

gr_report() aggregates hydrograph separation and its summaries into one information-rich graphical report that brings everything into one place. Just pass the results of gr_separate() and gr_summarize() into gr_report() function and provide the path to the output HTML file.
gr_get_gaps() and gr_fill_gaps() find and interpolate the periods of missing runoff and meteorological data which may affect the results.
gr_read_rean() and gr_join_rean() add temperature and precipitation to your runoff data from daily reanalysis. This can be useful if you do not have meteorological observations inside the basin. Currently the East European plain is covered.
gr_plot_matrix(), gr_plot_hori() and gr_plot_ridge() empower daily runoff analysis with fascinating graphical techniques which can be used to compare hydrographs for different years: matrix plots, horizon plots and ridgeline plots.
gr_set_locale() translates plots and reports to the specified language (English, Russian and Ukrainian are currently available).
gr_plot_* functions return silently ggplot2 objects or the lists of such objects. This means that they can be modified to your preferences before plotting. Just set print = FALSE and tweak aesthetics as you want or remove some information.