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