---
title: "Severn_03: Calibration of an open-loop influenced flow model network"
author: "David Dorchies"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Severn_03: Calibration of an open-loop influenced flow model network}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: airGRiwrm.bib
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6,
  fig.asp = 0.68,
  out.width = "70%",
  fig.align = "center"
)
```

```{r setup}
library(airGRiwrm)
```

## Presentation of the study case

The calibration results shown in vignette 'V02_Calibration_SD_model' for the flows simulated on the Avon at Evesham (Gauging station '54002') and on the Severn at Buildwas (Gauging station '54095') are not fully satisfactory, especially regarding low flows. These upper basins are actually heavily influenced by impoundments and inter-basin transfers [@higgsHydrologicalChangesRiver1988].

To cope with these influences, in this vignette, we will not try to simulate the basin functioning with an hydrological model but we will rather directly inject in the model the observed flows at these nodes.

## Conversion of a gauging station into a release spot

### Modification of the GRiwrm object

The creation of the `GRiwrm` object is detailed in the vignette "V01_Structure_SD_model" of the package. The following code chunk resumes all the necessary steps:

```{r}
data(Severn)
nodes <- Severn$BasinsInfo[, c("gauge_id", "downstream_id", "distance_downstream", "area")]
nodes$distance_downstream <- nodes$distance_downstream
nodes$model <- "RunModel_GR4J"
griwrm <- CreateGRiwrm(nodes, list(id = "gauge_id", down = "downstream_id", length = "distance_downstream"))
```

To notify the SD model that the provided flows on a node should be directly used instead of an hydrological model, one only needs to declare its model as `NA`:

```{r}
griwrmV03 <- griwrm
griwrmV03$model[griwrm$id == "54002"] <- NA
griwrmV03$model[griwrm$id == "54095"] <- NA
griwrmV03
```

Here, we keep the area of this basin which means that the discharge will be provided in mm per time step. If the discharge is provided in m<sup>3</sup>/s, then the area should be set to `NA` and downstream basin areas should be modified subsequently.

The diagram of the network structure is represented below with:

  * in blue, the upstream nodes with a GR4J model
  * in green, the intermediate nodes with an SD (GR4J + LAG) model
  * in red, the node with direct flow injection (no hydrological model)

```{r diagram}
plot(griwrmV03)
```

### Generation of the GRiwrmInputsModel object

The formatting of the input data is described in the vignette "V01_Structure_SD_model". The following code chunk resumes this formatting procedure:

```{r}
BasinsObs <- Severn$BasinsObs
DatesR <- BasinsObs[[1]]$DatesR
PrecipTot <- cbind(sapply(BasinsObs, function(x) {x$precipitation}))
PotEvapTot <- cbind(sapply(BasinsObs, function(x) {x$peti}))
Precip <- ConvertMeteoSD(griwrm, PrecipTot)
PotEvap <- ConvertMeteoSD(griwrm, PotEvapTot)
Qobs <- cbind(sapply(BasinsObs, function(x) {x$discharge_spec}))
```

This time, we need to provide observed flows as inputs for the nodes '54002' and '54095':

```{r}
QobsInputs <- Qobs[, c("54002", "54095")]
```

Then, the `GRiwrmInputsModel` object can be generated taking into account the new `GRiwrm` object:

```{r}
IM_OL <- CreateInputsModel(griwrmV03, DatesR, Precip, PotEvap, QobsInputs)
```

## Calibration of the new model

Calibration options is detailed in vignette "V02_Calibration_SD_model".
We also apply a parameter regularization here but only where an upstream simulated catchment is available.

The following code chunk resumes this procedure:

```{r}
IndPeriod_Run <- seq(
  which(DatesR == (DatesR[1] + 365*24*60*60)), # Set aside warm-up period
  length(DatesR) # Until the end of the time series
)
IndPeriod_WarmUp = seq(1,IndPeriod_Run[1]-1)
RunOptions <- CreateRunOptions(IM_OL,
                               IndPeriod_WarmUp = IndPeriod_WarmUp,
                               IndPeriod_Run = IndPeriod_Run)
InputsCrit <- CreateInputsCrit(IM_OL,
                               FUN_CRIT = ErrorCrit_KGE2,
                               RunOptions = RunOptions, Obs = Qobs[IndPeriod_Run,],
                               AprioriIds = c("54057" = "54032", "54032" = "54001"),
                               transfo = "sqrt", k = 0.15
)
CalibOptions <- CreateCalibOptions(IM_OL)
```

The **airGR** calibration process is applied on each hydrological node of the `GRiwrm` network from upstream nodes to downstream nodes.

```{r Calibration}
OC_OL <- suppressWarnings(
  Calibration(IM_OL, RunOptions, InputsCrit, CalibOptions))
ParamV03 <- sapply(griwrm$id, function(x) {OC_OL[[x]]$Param})
```

## Run of the model with this newly calibrated parameters

```{r RunModel}
OM_OL <- RunModel(
  IM_OL,
  RunOptions = RunOptions,
  Param = ParamV03
)
```

## Plotting of the results

As can be seen below, compared to results of vignette "V02_Calibration_SD_model", the use of measured flows on upstream influenced basins largely improves the model performance at downstream stations (better low-flow simulations).

```{r, fig.height = 5, fig.width = 8}
plot(OM_OL, Qobs = Qobs[IndPeriod_Run, ], which = "Regime")
```

The resulting flows of each node in m<sup>3</sup>/s are directly available and can be plotted with these commands:

```{r}
Qm3s <- attr(OM_OL, "Qm3s")
plot(Qm3s[1:150, ])
```


# References
