Commit e5a23d18 authored by unknown's avatar unknown
Browse files

v0.2.2.0 vignette added

parent 58e35fe1
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
############# 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)
......
---
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>
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment