-
Notifications
You must be signed in to change notification settings - Fork 4
/
README.Rmd
111 lines (88 loc) · 9.48 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
---
output: github_document
bibliography: "`r here::here('README-references.bib')`"
header-includes:
- \usepackage{color}
- \usepackage{amsmath}
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
[](https://travis-ci.com/dazamora/DWBmodelUN)
[](https://codecov.io/gh/dazamora/DWBmodelUN)
[](https://doi.org/10.5281/zenodo.3813037)
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-",
out.width = "100%"
)
```
# DWBmodelUN
The R package Modelling aims to implement Dynamic Water Balance model proposed by @Zhang2008 in a monthly time step. It is a tool for hydrologic modelling using the Budyko Framework and the Dynamic Water Balance Model, with DDS @Tolson2007 algorithm to calibrate the model and analyze the outputs.
## Installation
Currently, you can install the version under development from [Github](https://github.com/dazamora/DWBmodelUN), using these commands:
```{r eval=FALSE, include=TRUE}
install.packages("devtools")
devtools::install_github("dazamora/DWBmodelUN")
```
## Concepts behind DWBmodelUN
Two physical laws are taken into account in Dynamic Water Balance model (DWB), mass balance and energy balance. To represent the mass conservation, DWB is based on the equilibrium of water balance shown in equation (1).
```{r fig.1, echo=FALSE, fig.align= "center", fig.height=1, fig.width=6, dpi = 200}
par(mar=c(0.8,0.8,0.8,0.8)+0.1)
plot(0,0, yaxt = "n", xaxt = "n", type = "n",bty= "n", ylab = "", xlab = "")
text(0,0, labels = expression(italic(paste(frac("d","dt"),S[c],(t)," = ", "P(",S[c], ", t) - ",
"ET(",S[c], ", t) - ", "R(",S[c], ", t) - ","Q(",S[c], ", t)", " [eq.1]", sep =""))), cex = 0.9, font = 3, family = "sans")
```
Where $S_{c}$ is the total stored water in the basin, *P* is the precipitation, *ET* is actual evapotranspiration, *R* corresponds to surface runoff and *Q* to aquifers recharge. To evaluate the water balance of a basin is necessary to know several kind information like climatic variables, basin physical characteristics and further uniqueness relationships of each study. In the case of water balance models, some information can be replaced by equations and mathematical relations physically based, which makes the models much simpler but functional.
To represent energy conservation the model includes a conceptualization made by @budyko1961 where the energy availability influences over the atmospheric water demand which is represented by potential evapotranspiration (*PET*). The conceptualization also states that the dominant control of the water balance is atmospheric demand and water availability (P), which impose a limit to how much water can be evapotranspirated. @Zhang2008 worked on the mathematical assumption presented by @baw1981 (equation 2) that is a continuation of Budyko framework.
```{r fig.2, echo=FALSE, fig.align= "center", fig.height=1, fig.width=6, dpi = 600}
par(mar=c(0.6,0.6,0.6,0.6)+0.1)
plot(0,0, yaxt = "n", xaxt = "n", type = "n",bty= "n", ylab = "", xlab = "")
text(0,0, labels = expression(italic(paste(frac("ET","P")," = ", "1 + ", frac("PET","P"),
" - ", bgroup("[",1 - bgroup("(",frac("PET", "P"), ")")^(frac(1,1+alpha)), "]")^(1+alpha), " [eq.2]", sep =""))),
cex = 0.9)
```
Where $\alpha$ is a model parameter with an interval of [0-1]. @Zhang2008 detailed the influence of α parameter on the hydrological response in their model DWB.
DWB is a lumped conceptual hydrological model developed for annual and monthly time step. The model inputs are precipitation, potential evapotranspiration and streamflow. In general terms, DWB calculates the streamflow using two tanks and doing the following processes:
1. Precipitation is partitioned to basin water consumption and basin water yield. When it rains the soil is replenished and part of the rainfall is returned to the atmosphere, this process corresponds to basin water consumption, by the other hand, the remaining rainfall is the basin water yield.
2. Total water available for evapotranspiration is divided into water remaining in the soil storage and actual evapotranspiration.
3. The basin water yield is divided into surface runoff and water that supplies the groundwater store.
4. The base flow is the result of groundwater storage drainage.
5. The total monthly flow is the result of adding base flow and surface runoff.
```{r rstudio-create-pkg, echo = FALSE}
knitr::include_graphics("DWB_diagram.png", dpi = 200)
```
All these processes are done under the Top Down approach consider only four parameters are added to the model structure: $\alpha_{1}$, precipitation catchment efficiency; $\alpha$, evapotranspiration efficiency; *d*, groundwater store time constant; $S_{max}$, maximum water holding capacity of soil store (@Zhang2008).
## DWBmodelUN functions
DWBmodelUN package contains 12 functions, most of them have a practical example about their usage. The functions are:
* `BuildGRUmaps`: This function builds raster maps for each parameter based on a raster file where the location of the Grouped Response Units (GRUs) are defined.
* `cellBasins`: This function identifies the cells that are within a basin.
* `Coord_comparison`: This function compares three characteristics from two rasters:coordinates, resolution, and number of layers
* `dds`: This function allows the user to calibrate the DWB or other models with the Dynamical Dimension Search (DDS) algorithm (@Tolson2007).
* `DWBCalculator`: The function performs the distributed DWB hydrological model calculations in the defined domain and time period.
* `funFU`: Fu's function for relationship between precipitation and potential evapotranspiration.
* `graphDWB`: This function dynamically graphs the inputs and results of the Modelling. It has four types of graphs.
* `init_state`: This function uploads or creates the initial conditions of the two-state variables present in the DWB model, in raster format.
* `printVar`: This function that allows to print some of the variables simulated by the DWB model.
* `readSetup`: This function reads the setup features of the model. These include the dates that define the simulated time period, and also the variables that will be printed in individual directories
* `upForcing`: This function loads the precipitation and evapotranspiration estimates that will be used to run or force the DWB model
* `varBasins`: This function retrieves the value of a variable in each of the cells that are within a basin boundary. It also returns the time series average value of the variable.
## Datasets
DWBmodelUN also contains 11 data that allow to run the practical examples (@Duque2018):
* `basins`: The polygons of the 23 subbasins across the Sogamoso Basin.
* `cells`: Coordinates (Latitud and Longitud) and ID number of cells in Sogamoso River Basin.
* `dwb_results`: Results from DWB in Sogamoso River Basin.
* `EscSogObs`: Flow rates observed in Sogamoso River Basin at 32 gauges from January 2001 to December 2016.
* `GRU`: Raster data of Group Response Units in Sogamoso River Basin
* `param`: Values to four parameters *alpha_{1}*, *alpha_{2}* *d*, *S_{max}* of DWB model in each GRU.
* `PET_sogamoso`: Distributed monthly potential evapotranspiration in Sogamoso River Basin from January 2001 to December 2016.
* `setup_data`: Data.frame with the initial configuration of the model run.
* `simDWB.sogamoso`: Simulated runoff by the DWBmodelUN in the same stations where there were observed data from the Sogamoso basin.
* `sogamoso`: Sogamoso River Basin data.
* `P_sogamoso`: Distributed monthly precipitation in Sogamoso River Basin from January 2001 to December 2016.
* `r.cells`: Data.frame with the initial configuration of the model run.
## Disclaimer
DWBmodelUN is a public R library that is made freely available by the voluntary work of the researchers/authors of the Grupo de Investigación en Recursos Hídricos (GIREH) at the Universidad Nacional de Colombia (UNAL), hereafter call as creators, so as to promote the environmental modelling of the water cycle.
The representations of the physical world within the software are widely known. The codification and use of them are offered through this R library as a public service and are no cause of action against the creators. The user of this software/information is responsible for verifying the suitability, accuracy, completeness and quality for the particular use of it and hence the user asumes all liability and waives any claims or actions against the creators. Creators do not make any claim, guarantee or warranty the, expressed or implied, suitability, accuracy, completeness and quality for the particular use of the library. The creators disclaim any and all liability for any claims or damages that may result from the application of the information/software contained in the library. The information/software is provided as a guide.
Regarding other information contained in the library. The links or information that are accessed through external sites, which are not maintained by the creators, do not make the creators responsible for that content or the any claims or damages that may result from the use of these external sites. Information within this library is considered to be accurate with the considerations of uncertainties associated with hydrological modelling.
## References