From e5a23d1842d4a3a19b51bccbc6987c53ade928b3 Mon Sep 17 00:00:00 2001 From: unknown <olivier.delaigue@ANPI1430.antony.irstea.priv> Date: Tue, 20 Mar 2018 15:40:46 +0100 Subject: [PATCH] v0.2.2.0 vignette added --- DESCRIPTION | 4 +- NEWS | 10 ++- vignettes/get_started.rmd | 177 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 189 insertions(+), 2 deletions(-) create mode 100644 vignettes/get_started.rmd diff --git a/DESCRIPTION b/DESCRIPTION index 3e222f1..6e874a0 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,13 +1,15 @@ Package: airGRteaching Type: Package Title: Teaching Hydrological Modelling with the GR Rainfall-Runoff Models ('Shiny' Interface Included) -Version: 0.2.1.1 +Version: 0.2.2.0 Date: 2018-03-20 Authors@R: c(person("Olivier", "Delaigue", role = c("aut", "cre"), email = "airGR@irstea.fr"), person("Laurent", "Coron", role = c("aut")), person("Pierre", "Brigode", role = c("aut")), person("Guillaume", "Thirel", role = c("ctb"))) Depends: airGR (>= 1.0.9.43) Imports: dygraphs (>= 1.1.1.4), htmlwidgets (>= 1.0), markdown, plotrix, shiny, shinyjs, xts +Suggests: knitr, webshot 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. License: GPL-2 NeedsCompilation: no URL: https://webgr.irstea.fr/en/airGR/ Encoding: UTF-8 +VignetteBuilder: knitr, webshot diff --git a/NEWS b/NEWS index 093b168..b5c8aae 100644 --- a/NEWS +++ b/NEWS @@ -1,8 +1,16 @@ ############# Release History of the airGRteaching Package +## 0.2.2.0 Release Notes (2018-03-20) -## 0.2.1.1 Release Notes (2018-03-20) + Bug fixes + - bug fixed in ShinyGR(), the criteria values are now right on Unix system + + User-visible changes + - vignette added + + +## 0.2.0.9 Release Notes (2018-03-15) CRAN-compatibility updates - embeding dygraphs functions to avoid user to install the last version of this package from GitHub (import of devtools not necessary) diff --git a/vignettes/get_started.rmd b/vignettes/get_started.rmd new file mode 100644 index 0000000..26da7f2 --- /dev/null +++ b/vignettes/get_started.rmd @@ -0,0 +1,177 @@ +--- +title: "Get Started with airGRteachning" +output: rmarkdown::html_vignette +vignette: > + %\VignetteEngine{knitr::rmarkdown} + %\VignetteIndexEntry{Get Started with airGR} + %\VignetteEncoding{UTF-8} +--- + + + +```{r include=FALSE} +formatGR <- '<strong><font color="#009EE0">%s</font></strong>' +GR <- sprintf(formatGR, "GR") +airGR <- sprintf(formatGR, "airGR") +airGRteaching <- sprintf(formatGR, "airGRteaching") +``` + + + + +```{r setup, include=FALSE} +knitr::opts_chunk$set(echo = TRUE) +library(airGRteaching) +``` + + + +### How to run the `r airGR` hydrological models in only three simple steps with `r airGRteaching` + + +#### Preparation of observed data for modelling + +A `data.frame` of daily hydrometeorological observations time series at the catchment scale is needed. The required fields are: + + * *DatesR* : dates in the `POSIXt` format + * *P* : average precipitation [mm/time step] + * *T* : catchment average air temperature [℃] [OPTIONAL] + * *E* : catchment average potential evapotranspiration [mm/time step] + * *Qmm* : outlet discharge [mm/time step] + +```{r, echo=3, eval=TRUE} +data(L0123001) +BasinObs <- BasinObs[, c("DatesR", "P", "E", "Qmm", "T")] +head(BasinObs) +``` + +Before running a model, `r airGRteaching` functions require data and options with specific formats. + +For this step, you just have to use the `PrepGR()` function. You have to define: + + * `ObsDF`: `data.frame` of hydrometeorological observations time series + * `HydroModel`: the name of the hydrological model you want to run (GR1A, GR2M, GR4J, GR5J, GR6J or GR4H) + * `CemaNeige`: if you want or not to use the snowmelt and accumulation model + +If you want to use CemaNeige, you also have to define: + + * catchment average air temperature in `ObsDF` or in `TempMean` + * `HypsoData`: a vector of 101 reals: min, quantiles (1 % to 99 %) and max of catchment elevation distribution [m]; if not defined a single elevation layer is used for CemaNeige + * `NLayers`: the number of elevation layers requested [-] + +```{r, echo=TRUE, eval=TRUE} +PREP <- PrepGR(ObsDF = BasinObs, HydroModel = "GR5J", CemaNeige = FALSE) +``` + +<br> + +#### Calibration step + +To calibrate a model, you just have to use the `CalGR()` function. By default, the objective function used is the Nash–Sutcliffe criterion (`"NSE"`), and the warm-up period is automatically set (depends on model). You just have to define: + + * `PrepGR`: the object returned by the `PrepGR()` function + * `CalPer`: a vector of 2 dates to define the calibration period + + +You can obviously define another objective function or warm-up period: + + * `CalCrit`: name of the objective function (`"NSE", "KGE", "KGE2", "RMSE"`) + * `WupPer`: a vector of 2 dates to define the warm-up period + +The calibration algorithm has been developed by Claude Michel (`Calibration_Michel()` function in the `r airGR` package) . + +```{r, warning=FALSE} +CAL <- CalGR(PrepGR = PREP, CalCrit = "KGE2", + WupPer = NULL, CalPer = c("1990-01-01", "1993-12-31")) +``` + +<br> + +#### Simulation step + +To run a model, please use the `SimGR()` function. The `PrepGR` and `WupPer` arguments of `SimGR()` are similar to the ones of the `CalGR()` function. Here, `EffCrit` is used to calculate the performance of the model over the simulation period `SimPer` and `CalGR` is the object returned by the `CalGR()` function. + +```{r, warning=FALSE} +SIM <- SimGR(PrepGR = PREP, CalGR = CAL, EffCrit = "KGE2", + WupPer = NULL, SimPer = c("1994-01-01", "1998-12-31")) +``` + +<br> + +### Pre-defined graphical plots + +#### Static plots + +The call of the `plot()` function with a `PrepGR` object draws the observed precipitation and discharge time series. + +```{r, fig.width=7*1.5, fig.height=4.25*1.5, dev.args=list(pointsize=14), echo=-1} +par(cex.lab = 0.6, cex.axis = 0.6) +plot(PREP, main = "Observation") +``` + + +By default (with the argument `which = "perf"`), the call of the `plot()` function with a `CalGR` object draws the classical `r airGR` plot diagnostics (observed and simulated time series together with diagnostic plot) + +```{r, fig.width=7*1.5, fig.height=4.25*1.5, dev.args=list(pointsize=14), echo=TRUE, eval=FALSE} +plot(CAL, which = "perf") +``` +```{r, fig.width=7*1.5, fig.height=4.25*1.5, dev.args=list(pointsize=14), echo=FALSE, warning=FALSE} +plot(CAL, which = "perf", cex.lab = 0.7, cex.axis = 0.7) +``` + +With the `CalGR` object, if the argument `which` is set to `"iter"`, the `plot()` function draws the evolution of the parameters and the values of the objective function during the second step of the calibration (steepest descent local search algorithm): + +```{r, fig.width=7*1.5, fig.height=3.25*1.5, dev.args=list(pointsize=14)} +plot(CAL, which = "iter") +``` + +With the `CalGR` object, if the argument `which` is set to `"ts"`, the `plot()` function simply draws the time series of the observed precipitation, and the observed and simulated flows: + +```{r, fig.width=7*1.5, fig.height=4.25*1.5, dev.args=list(pointsize=14), echo=-1} +par(cex.lab = 0.7, cex.axis = 0.7) +plot(CAL, which = "ts", main = "Calibration") +``` + +The call of the `plot()` function with a `SimGR` object draws the classical `r airGR` plot diagnostics. +```{r, fig.width=7*1.5, fig.height=4.25*1.5, dev.args=list(pointsize=14), eval=FALSE} +plot(SIM) +``` + + +#### Dynamic plots + +Dynamic plots, using the *dygraphs* JavaScript charting library, can be displayed by the package. + +The `dyplot()` function can be applied on `PrepGR`, `CalGR` and `SimGR` objects and draws the time series of the observed precipitation, and the observed and simulated (except with `PrepGR` objects) flows. + +The user can zoom on the plot device and can read the exact values. + +With this function, users can easily explore the data time series and also explore and interpret the possible problems of the calibration or simulation steps. + + +```{r, fig.width=7*1.5, fig.height=3.25*1.5, dev.args=list(pointsize=14), eval=TRUE} +dyplot(SIM, main = "Simulation") +``` + + +### *Shiny* interface + +The `r airGRteaching` package also provides the `ShinyGR()` function, which allows to run the *Shiny* interface that is proposed on this page. + +The `ShinyGR()` function just needs: + + * `ObsDF`: a `data.frame` (or a `list` of `data.frame`) + * `SimPer`: a vector (or list of vectors) of 2 dates to define the simulation period(s) + + +```{r, eval=FALSE} +ShinyGR(ObsDF = BasinObs, SimPer = c("1994-01-01", "1998-12-31")) +``` + +Only daily models are currently available (GR4J, GR5J, GR6J + CemaNeige). + +It is also possible to change the interface look; different themes are proposed (`theme` argument). +<div><center><image src="fig/theme_rstudio.jpg" width="32%" height="32%"> <image src="fig/theme_cerulean.jpg" width="32%" height="32%"> <image src="fig/theme_cyborg.jpg" width="32%" height="32%"></img></center></div> +<div><center><image src="fig/theme_flatly.jpg" width="32%" height="32%"> <image src="fig/theme_united.jpg" width="32%" height="32%"> <image src="fig/theme_yeti.jpg" width="32%" height="32%"></center></div> + + -- GitLab