---
title: 'Severn_01: Set up of a semi-distributed GR model network'
author: "David Dorchies"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Severn_01: Set up of a semi-distributed GR model network}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: airGRiwrm.bib
---

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

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

The package **airGRiwrm** is a modeling tool for integrated water resources management based on the **airGR** package [See @coronSuiteLumpedGR2017].

In a semi-distributed model, the catchment is divided into several sub-catchments. Each sub-catchment is an hydrological entity where a runfall-runoff model produces a flow time series at the outlet of the sub-catchment. Then, these flows are propagated from sub-catchment outlets thanks to a hydraulic function to model the flow at the outlet of the whole catchment. The aim of **airGRiwrm** is to organize the structure and schedule the execution of the hydrological and hydraulic sub-models contained in the semi-distributed model.

In this vignette, we show how to prepare observation data for the model.

## Description of the example used in this tutorial

The example of this tutorial takes place on the Severn River in the United Kingdom. The data set comes from the CAMELS GB database [see @coxonCatchmentAttributesHydrometeorological2020].

```{r}
data(Severn)
Severn$BasinsInfo
```

## Semi-distributed network description

The semi-distributed model comprises nodes. Each node, identified by an ID, represents a location where water is injected to or withdrawn from the network.

The description of the topology consists, for each node, in providing several fields:

- the node ID,
- the ID of the first node located downstream (set to `NA` for the last downstream node (i.e. the outlet of the simulated catchment)),
- the distance (m) between these two nodes (set to `NA` for the last downstream node),
- an area (km<sup>2</sup>) related to the node in case a hydrological model is used (otherwise set to `NA`).

Below, we constitute a `data.frame` bringing together all this information for the tutorial example:

```{r}
nodes <- Severn$BasinsInfo[, c("gauge_id", "downstream_id", "distance_downstream", "area")]
nodes$model <- "RunModel_GR4J"
```

The network description consists in a `GRiwrm` object that lists the nodes and describes the network diagram. It is a `data.frame` of class `GRiwrm` with specific column names:

- `id`: the identifier of the node in the network,
- `down`: the identifier of the next hydrological node downstream,
- `length`: hydraulic distance to the next hydrological downstream node (m),
- `model`: name of the hydrological model used (E.g. "RunModel_GR4J"). `NA` for other types of nodes,
- `area`: area of the sub-catchment (km<sup>2</sup>). Used for hydrological model such as GR models. `NA` if not used.


The `GRiwrm` function helps to create an object of class `GRiwrm`. It renames the columns of the `data.frame`.

```{r}
griwrm <- CreateGRiwrm(nodes, list(id = "gauge_id", down = "downstream_id", length = "distance_downstream"))
griwrm
```

The diagram of the network structure is represented below with in blue the upstream nodes with a GR4J model and in green the intermediate nodes with an SD (GR4J + LAG) model.

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



## Observation time series

Observations (precipitation, potential evapotranspiration (PE) and flows) should be formatted in a separate data.frame with one column of data per sub-catchment.

```{r}
BasinsObs <- Severn$BasinsObs
str(BasinsObs)
```


```{r, warning=FALSE, message=FALSE}

DatesR <- BasinsObs[[1]]$DatesR

PrecipTot <- cbind(sapply(BasinsObs, function(x) {x$precipitation}))
PotEvapTot <- cbind(sapply(BasinsObs, function(x) {x$peti}))
Qobs <- cbind(sapply(BasinsObs, function(x) {x$discharge_spec}))
```

These meteorological data consist in mean precipitation and PE for each basin. However, the model needs mean precipitation and PE at sub-basin scale. The function `ConvertMeteoSD` calculates these values for downstream sub-basins:

```{r}
Precip <- ConvertMeteoSD(griwrm, PrecipTot)
PotEvap <- ConvertMeteoSD(griwrm, PotEvapTot)
```


## Generation of the GRiwrmInputsModel object

The `GRiwrmInputsModel` object is a list of **airGR** `InputsModel` objects. The identifier of the sub-basin is used as a key in the list which is ordered from upstream to downstream.

The **airGR** `CreateInputsModel` function is extended in order to handle the `GRiwrm` object that describes the basin diagram:


```{r}
InputsModel <- CreateInputsModel(griwrm, DatesR, Precip, PotEvap)
```

# References