Depends airGR (>= 1.4.3.52) Imports dygraphs (>= 1.1.1.6), markdown, plotrix, shiny (>= 1.1.0), shinyjs (>= 1.0), xts

Suggests knitr

Description Add-on package to the 'airGR' package that simplifies its use and is aimed at being used for teaching hydrology. The package provides 1) three functions that allow to complete very simply a hydrological modelling exercise 2) plotting functions to help students to explore observed data and to interpret the results of calibration and simulation of the GR ('Génie rural') models 3) a 'Shiny' graphical interface that allows for displaying the impact of model parameters on hydrographs and models internal variables.

Description

airGRteaching is an add-on package to the airGR package that simplifies its use and is teachingoriented. It allows to use with very low programming skills the rainfall-runoff models (GR4H, GR5H, GR4J, GR5J, GR6J, GR2M, GR1A) and a snow melt and accumulation model (CemaNeige). This package also provides graphical devices to help students to explore data and modelling results.

The airGRteaching package has been designed to fulfil a major requirement: facilitating the use of the airGR functionalities by students. The names of the functions and their arguments were chosen to this end.

The package is mostly based on three families of functions:

-the functions that allow to complete very simply a hydrological modelling exercise; -plotting functions to help students to explore observed data and to interpret the results of calibration and simulation of the GR models; -a function which runs a 'Shiny' graphical interface that allows for displaying in real-time model parameters impacts on hydrographs.

This package brings into R the hydrological modelling tools developed at INRAE-Antony (Catchment Hydrology research group of the HYCAR Research Unit, France).

# -Modelling Functions

Three functions allow to complete very simply a hydrological modelling exercise:

-preparation of data: PrepGR(); -calibration of the models: CalGR(); -simulation with the models: SimGR() # -Plotting Functions airGRteaching provides two types of plotting functions that allow to produce static (plot()) or dynamic (dyplot()) graphics (incl. mouse events and interactive graphics). The devices allow to explore observed data and to interpret the results of calibration and simulation of the GR models.

# -Shiny interface

The package also provides the ShinyGR()) function, which allows to run a Shiny interface. Thus its is possible to perform:

-interactive flow simulations with parameters modifications; -automatic calibration; -display of internal variables evolution; -time period selection.

A demonstrator of the graphical interface is available for free online on the Sunshine website.

# -Models

The six hydrological models and the snow melt and accumulation model already available in airGR are available in airGRteaching. These models can be called within airGRteaching using the following model names: ## data.frame of observed data data(L0123001, package = "airGR") BasinObs2 <-BasinObs[, c("DatesR", "P", "E", "Qmm", "T")] ## Preparation of observed data for modelling PREP <-PrepGR(ObsDF = BasinObs2, HydroModel = "GR4J", CemaNeige = FALSE) head(as.data.frame(PREP))

## Calibration step CAL <-CalGR(PrepGR = PREP, CalCrit = "KGE2", WupPer = NULL, CalPer = c("1990-01-01", "1991-12-31")) head(as.data.frame(CAL)) ## Simulation step using the result of the automatic calibration method to set the model parameters SIM <-SimGR(PrepGR = PREP, CalGR = CAL, EffCrit = "KGE2", WupPer = NULL, SimPer = c("1992-01-01", "1992-12-31")) head(as.data.frame(SIM))

CalGR

CalGR

Calibration algorithm that optimises the error criterion selected as objective function

Description

Calibration algorithm that optimises the error criterion selected as objective function using the INRAE-HYCAR procedure described by C. Michel

Usage

CalGR(PrepGR, CalCrit = c("NSE", "KGE", "KGE2", "RMSE"), WupPer = NULL, CalPer, transfo = c("", "sqrt", "log", "inv", "sort"), verbose = TRUE)

HydroModel

[character] name of the hydrological model (must be one of "GR1A", "GR2M", "GR4J", "GR5J", "GR6J", "GR4H" or "GR5H")

CemaNeige

[boolean] option indicating whether CemaNeige should be activated (only available for hourly or daily models, when HydroModel is equal to any of "GR4J", "GR5J", "GR6J", "GR4H" or "GR5H"). See details

Details

If the ObsDF argument is provided, DatesR, Precip, PotEvap, Qobs and TempMean are not necessary, and vice-versa. If one variable is provided in ObsDF and also separately, then only the data included in ObsDF are used.

If the CemaNeige argument is set to TRUE, the default version of CemaNeige is used (i.e. without the Linear Hysteresis, see the details part in CreateRunOptions).

The PrepGR function can be used even if no observed discharges are available. In this case, it is necessary to provide observed discharges time series equal to NA: this means that either the ObsDF observed discharges column or the Qobs arguments, depending on the format of data you provide, must be provided and filled with NAs.

Value list object of class PrepGR containing the data required to evaluate the model outputs: optional) [character] alternative stylesheet ["RStudio" (default), "Cerulean", "Cyborg", "Flatly", "Inrae", "Saclay", "United" or "Yeti"]

InputsModel [list] object

Details

The warm-up period always starts from the first date of the dataset to the time step just before the beginning of the simulation period (SimPer).

The ShinyGR function can be used even if no observed discharges are available. In this case, it is necessary to provide observed discharges time series equal to NA: this means that either the ObsDF observed discharges column or the Qobs arguments, depending on the format of data you provide, must be provided and filled with NAs.

Author(s)

Olivier Delaigue, Laurent Coron, Pierre Brigode

See Also

CalGR,SimGR,plot.CalGR,plot.SimGR Examples library(airGRteaching) ## data.frame of observed data of a low-land basin data(L0123001, package = "airGR") BV_L0123001 <-BasinObs[0001:6000, c("DatesR", "P", "E", "Qmm", "T")]

Usage

SimGR(PrepGR, CalGR = NULL, Param, EffCrit = c("NSE", "KGE", "KGE2", "RMSE"), WupPer = NULL, SimPer, transfo = c("", "sqrt", "log", "inv", "sort"), verbose = TRUE)

R

  topics documented: airGRteaching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 as.data.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 CalGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 dyplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 PrepGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 ShinyGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 SimGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Index 17 airGRteaching Tools to Simplify the Use of the airGR Hydrological Package for Education (Including a Shiny Application)

  SimGR(PrepGR = PREP, CalGR = CAL, EffCrit = "KGE2", WupPer = NULL, SimPer = c("1994-01-01", "1998-12-31")) dyplot(SIM, main = "Simulation") plot Time series plotting GR observation objects Description Time series plotting GR observation objects Usage ## S3 method for class PrepGR plot(x, type = "l", col.Precip = "royalblue", col.Q = "black", col.na = "grey", xlab = NULL, ylab = NULL, main = NULL, plot.na = TRUE, ...)## S3 method for class CalGR plot(x, xlab = NULL, ylab = NULL, main = NULL, which = c("perf", "iter", "ts"), ...)

  Vers une chaîne cohérente de modèles pluie-débit conceptuels globaux aux pas de temps pluriannuel, annuel, mensuel et journalier, PhD thesis (in French), ENGREF -Cemagref Antony, Paris, France, 323 pp. -Mouelhi, S., C. Michel, C. Perrin and V. Andréassian (2006a), Stepwise development of a twoparameter monthly water balance model, Journal of Hydrology, 318(1-4), 200-214, doi: 10.1016/j.jhydrol.2005.06.014. -Mouelhi, S., C. Michel, C. Perrin. & V. Andreassian (2006b), Linking stream flow to rainfall at the annual time step: the Manabe bucket model revisited, Journal of Hydrology, 328, 283-296, doi: 10.1016/j.jhydrol.2005.12.022.

	-Le Moine, N. (2008), Le bassin versant de surface vu par le souterrain : une voie d'amélioration des performances et du réalisme des modèles pluie-débit ?, PhD thesis (in French), UPMC -Cema-gref Antony, Paris, France, 324 pp. -Mathevet, T. (2005), Quels modèles pluie-débit globaux pour le pas de temps horaire ? Développe-ment empirique et comparaison de modèles sur un large échantillon de bassins versants, PhD thesis (in French), ENGREF -Cemagref Antony, Paris, France, 463 pp. data.frame containing: Dates [POSIXct] vector of dates PotEvap [numeric] time series of potential evapotranspiration (catchment average) [mm/time -Mouelhi S. (2003), Value step]
	PrecipObs	[numeric] time series of total precipitation (catchment average) [mm/time step]
	PrecipFracSolid_CemaNeige
		[numeric] time series of solid precipitation fraction (layer average) [-], must be
		defined if CemaNeige is used
	TempMeanSim_CemaNeige
		[numeric] time series of mean air temperature (layer average) [°C], must be
		defined if CemaNeige is used
	Qobs	[numeric] time series of observed flow (for the same time steps than simulated)
		[mm/time step]
	Author(s)
	Olivier Delaigue
	See Also
	PrepGR, CalGR, SimGR
	2008) -GR6J*: six-parameter daily lumped hydrological model (Pushpalatha et al., 2011) Examples
	-GR2M: two-parameter monthly lumped hydrological model (Mouelhi, 2003; Mouelhi et al., 2006a) library(airGRteaching)
	-GR1A: one-parameter annual lumped hydrological model (Mouelhi, 2003; Mouelhi et al., 2006b)
	-CemaNeige: two-parameter degree-day snow melt and accumulation daily model (combined with
	GR4H, GR5H, GR4J, GR5J or GR6J) (Valéry et al., 2014)
	*: available in the Shiny interface.
	For more information and to get started with the package, you can refer to the vignette (vignette("get_started"))
	and go on the airGRteaching website.
	# -References
	-Coron, L., G. Thirel, O. Delaigue, C. Perrin and V. Andréassian (2017), The Suite of Lumped GR
	Hydrological Models in an R Package. Environmental Modelling and Software, 94, 166-171. doi:
	10.1016/j.envsoft.2017.05.002.
	-Ficchi, A. (2017). An adaptive hydrological model for multiple time-steps: Diagnostics and im-
	provements based on fluxes consistency. PhD thesis, Irstea (Antony), GRNE (Paris), France. -
	Ficchi, A., C. Perrin and V. Andréassian (2019). Hydrological modelling at multiple sub-daily
	time steps: model improvement via flux-matching. Journal of Hydrology, 575, 1308-1327. doi:
	10.1016/j.jhydrol.2019.05.084.

-GR4H: four-parameter hourly lumped hydrological model (Mathevet, 2005) -GR5H: five-parameter hourly lumped hydrological model (Ficchi, 2017; Ficchi et al., 2019) -GR4J*: four-parameter daily lumped hydrological model (Perrin et al., 2003) -GR5J*: five-parameter daily lumped hydrological model (Le Moine, -Perrin, C., C. Michel and V. Andréassian (2003), Improvement of a parsimonious model for streamflow simulation, Journal of Hydrology, 279(1-4), 275-289, doi:10.1016/S0022-1694(03)00225-7. -Pushpalatha, R., C. Perrin, N. Le Moine, T. Mathevet and V. Andréassian (2011), A downward structural sensitivity analysis of hydrological models to improve low-flow simulation, Journal of Hydrology, 411(1-2), 66-76, doi: 10.1016/j.jhydrol.2011.09.034. -Valéry, A., V. Andréassian and C. Perrin (2014), "As simple as possible but not simpler": What is useful in a temperature-based snow-accounting routine? Part 2 -Sensitivity analysis of the Cemaneige snow accounting routine on 380 catchments, Journal of Hydrology, 517(0): 1176-1187, doi: 10.1016/j.jhydrol.2014.04.058. as.data.frame Function to coerce the outputs of PrepGR, CalGR and SimGR to a data.frame Description Function to coerce the outputs of PrepGR, CalGR and SimGR to a data.frame Usage ## S3 method for class airGRt as.data.frame(x, row.names = NULL, ...) Arguments x [object of class airGRt] typically an object of class PrepGR, CalGR or SimGR row.names NULL or a character vector giving the row names for the data.frame. Missing values are not allowed ... additional arguments to be passed to or from methods Qsim [numeric] time series of simulated flow (for the same time steps than simulated) [mm/time step] (only for objects of class CalGR or SimGR)

  POSIXct values defining the beginning and end of the warm-up period, $Run: vector of 2 POSIXct values defining the beginning and end of the calibration period dyplot col.Precip (optional) [character] vector of 1 (total precip.) or 2 (liquid and solid precip. with CemaNeige) color codes or names for precipitation (these can be of the form "#AABBCC" or "rgb(255,100,200)" or "yellow"), see par and rgb

	OptionsCalib Qobs OutputsCalib OutputsModel TypeModel CalCrit PeriodModel col.na ylab main plot.na RangeSelector (optional) [boolean] add a range selector to the bottom of the chart that allows [list] object of class RunOptions (see: CreateRunOptions) [numeric] series of observed discharges [mm/time step] [list] object of class OutputsCalib (see: Calibration) [list] object of class OutputsModel (see: RunModel) [character] name of the function of the hydrological model used [character] name of the function that computes the error criterion during the calibration step (optional) [character] vector of up to 3 color codes or names for observed (first value), simulated (second value, if provided) and additional (last value, if pro-vided) flows, respectively (these can be of the form "#AABBCC" or "rgb(255,100,200)" or "yellow"), see par and rgb (optional) [character] color code or name for missing values(these can be of the form "#AABBCC" or "rgb(255,100,200)" or "yellow"), see par and rgb (optional) [character] a label for the y-axis (flow and precipitation) (optional) [character] a main title for the plot [boolean] indicating if the missing values are plotted on the x-axis users to pan and zoom to various date ranges (see dyRangeSelector) Roller (optional) [numeric] number of time scale units (e.g. days, months, years) to average values over (see dyRoller) LegendShow (optional) Author(s) Olivier Delaigue See Also [list] $WarmUp: vector of 2 col.Q PrepGR, CalGR, SimGR

Arguments

PrepGR

[object of class PrepGR] see PrepGR for details

CalCrit

[character] name of the objective function (must be one of "NSE", "KGE", "KGE2" or "RMSE") WupPer (optional) [character] vector of 2 values to define the beginning and end of the warm-up period ["YYYY-mm-dd" or "YYYY-mm-dd HH:MM:SS"] CalPer

[character] vector of 2 values to define the beginning and end of the calibration period ["YYYY-mm-dd" or "YYYY-mm-dd HH:MM:SS"] transfo (optional) [character] name of the transformation transformation applied to discharge for calculating the objective function (must be one of "", "sqrt", "log", "inv" or "sort")

verbose (optional) [boolean] logical value indicating if the function is run in verbose mode or not

Value list object of class CalGR containing: [character] when to display the legend. Specify "always" to always show the legend. Specify "onmouseover" to only display it when a user mouses over the chart. Specify "follow" (default) to have the legend show as overlay to the chart which follows the mouse. See dyLegend ... other parameters to be passed through to plotting functions

  of class InputsModel containing the data required to evaluate the model outputs (see: CreateInputsModel outputs)

	Precip	(optional) [numeric] time series of total precipitation (catchment average) [mm/time
		step], required to create the GR and CemaNeige models inputs
	PotEvap	(optional) [numeric] time series of potential evapotranspiration (catchment av-
		erage) [mm/time step], required to create the GR model inputs
	Qobs	(optional) [numeric] time series of observed discharge [mm/time step]
	TempMean	(optional) [numeric] time series of mean air temperature [°C], required to create
		the CemaNeige model inputs (if used)
	ZInputs	(optional) [numeric or list of numerics] real giving the mean elevation of the
		Precip and TempMean series (before extrapolation) [m], used to create the Ce-
		maNeige model inputs (if used)
	HypsoData	(optional) [numeric or list of numerics] vector of 101 reals: min, q01 to q99 and
		max of catchment elevation distribution [m]; if not defined a single elevation is
		used for CemaNeige (if used)
	NLayers	(optional) [numeric or list of numerics] integer giving the number of elevation
		layers requested [-], required to create CemaNeige model inputs (if used)
	SimPer	[character or list of characters] vector of 2 values to define the beginning and the
		end of the simulation period ["YYYY-mm-dd" or "YYYY-mm-dd HH:MM:SS"], see
		below for details
	NamesObsBV	(optional) [character] vector of values to define the data inputs name(s) (if the
		ObsDF list is not already named)
	theme
	Qobs	[numeric] time series of observed discharges [mm/time step]
	HydroModel	[character] name of the function of the hydrological model used
	Author(s)
	Olivier Delaigue
	See Also
	CreateInputsModel

  CalGR numeric] see CalGR. The length of the vector of parameters depends on the model used, see below for details [character] name of the transformation applied to discharge for calculating the error criterion (must be one of "", "sqrt", "log", "inv" or "sort") verbose(optional) [boolean] logical value indicating if the function is run in verbose mode or notDetailsThe user can customize the parameters with the Param argument. The user can also use the parameters resulting from a calibration. In this case, it is necessary to use the CalGR function.TypeModel[character] name of the function of the hydrological model usedCalCrit[character] name of the function that computes the error criterion during the calibration stepEffCrit[list] name of the function that computes the error criterion during the simulation stepPeriodModel[list] $WarmUp: vector of 2 POSIXct values defining the beginning and end of the warm-up period; $Run: vector of 2 POSIXct values defining the beginning and end of the calibration period

	Arguments
	PrepGR	[object of class PrepGR] see PrepGR for details
	CalGR	(deprecated) use the Param argument instead plot, 9, 9
	Param [object of class EffCrit [character] name of the efficiency criterion (must be one of "NSE", "KGE", "KGE2" plot.CalGR, 13 plot.SimGR, 13 PrepGR, 2, 4-10, 10, 15
		or "RMSE")	rgb, 8
	WupPer	(optional) [character] vector of 2 values to define the beginning and end of the RunModel, 6, 15, 16
		warm-up period ["YYYY-mm-dd" or "YYYY-mm-dd HH:MM:SS"] ShinyGR, 3, 12
	SimPer	[character] vector of 2 values to define the beginning and end of the simulation SimGR, 2, 4, 5, 7, 8, 13, 14
		period ["YYYY-mm-dd" or "YYYY-mm-dd HH:MM:SS"]
	transfo Calibration_Michel, 7 list object of class SimGR containing: airGRteaching, 2 as.data.frame, 4 CalGR, 2, 4, 5, 6, 7, 8, 13, 15 Calibration, 6 (optional) Value	title, 9
	OptionsSimul CreateCalibOptions, 7 [list] object of class RunOptions (see: CreateRunOptions) CreateInputsCrit, 7, 15, 16
	OptionsCrit CreateInputsModel, 11 [list] object of class InputsCrit (see: CreateInputsCrit)
	OutputsModel CreateRunOptions, 6, 7, 11, 15, 16 [list] object of class OutputsModel (see: RunModel)
	Qobs dyLegend, 8	[numeric] series of observed discharges [mm/time step]
	dyplot, 3, 7
	dyRangeSelector, 8
	dyRoller, 8
	ErrorCrit_KGE, 7, 16
	ErrorCrit_KGE2, 7, 16
	ErrorCrit_NSE, 7, 16
	ErrorCrit_RMSE, 7, 16
	par, 8, 9

github.io/airGRteaching/

Author(s)

Olivier Delaigue

See Also

CreateRunOptions, CreateInputsCrit, CreateCalibOptions, ErrorCrit_RMSE, ErrorCrit_NSE, ErrorCrit_KGE, ErrorCrit_KGE2, Calibration_Michel Examples library(airGRteaching) ## data.frame of observed data data(L0123001, package = "airGR") BasinObs2 <-BasinObs[, c("DatesR", "P", "E", "Qmm", "T")] ## Preparation of observed data for modelling PREP <-PrepGR(ObsDF = BasinObs2, HydroModel = "GR4J", CemaNeige = TRUE) ## Calibration step CAL <-CalGR(PrepGR = PREP, CalCrit = "KGE2", WupPer = NULL, CalPer = c ("1990-01-01", "1993-12-31")) str (CAL) dyplot

Interactive time series plotting of GR data

Description

Interactive time series plotting of objects of classes PrepGR, CalGR or SimGR.

Usage

## Default S3 method: dyplot(x, Qsup = NULL, Qsup.name = "Qsup", col.Precip = c("royalblue", "lightblue"), col.Q = c("black", "orangered", "grey"), col.na = "lightgrey", ylab = NULL, main = NULL, plot.na = TRUE, RangeSelector = TRUE, Roller = FALSE, LegendShow = c("follow", "auto", "always", "onmouseover", "never"), ...) ## data.frame of observed data data(L0123001, package = "airGR") BasinObs2 <-BasinObs[, c("DatesR", "P", "E", "Qmm", "T")] ## Preparation of observed data for modelling when inputs set by using a data.frame