v0.2.2.0 vignette added

DESCRIPTION

 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

NEWS

 ############# 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)

vignettes/get_started.rmd

+---
+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 [&#8451;] [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>
+
+