-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.Rmd
168 lines (118 loc) · 7.55 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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# wateRinfo <img src="man/figures/logo.png" align="right" alt="" width="120">
<!-- badges: start -->
[](https://CRAN.R-project.org/package=wateRinfo)
[](https://github.com/inbo/wateRinfo/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/ropensci/wateRinfo/)
[](https://www.repostatus.org/#active)
[](https://github.com/ropensci/software-review/issues/255)
<!-- badges: end -->
wateRinfo facilitates access to [waterinfo.be](https://www.waterinfo.be/), a website managed by the [Flanders Environment Agency (VMM)](https://en.vmm.be/) and [Flanders Hydraulics Research](https://www.waterbouwkundiglaboratorium.be/). The website provides access to real-time water and weather related environmental variables for Flanders (Belgium), such as rainfall, air pressure, discharge, and water level. The package provides functions to search for stations and variables, and download time series.
To get started, see:
- [Get started](https://docs.ropensci.org/wateRinfo/articles/wateRinfo.html): an introduction to the package's main functionalities.
- [Function reference](https://docs.ropensci.org/wateRinfo/reference/index.html): overview of all functions.
- [Articles](https://docs.ropensci.org/wateRinfo/articles/): tutorials on how to use the package.
## Installation
You can install the development version of wateRinfo from [GitHub](https://github.com/) with:
```R
# install.packages("devtools")
devtools::install_github("ropensci/wateRinfo")
# Or rOpenSci R-universe
install.packages("wateRinfo", repos = "https://ropensci.r-universe.dev")
```
## Example
For a number of supported variables ([documented](https://www.waterinfo.be/download/9f5ee0c9-dafa-46de-958b-7cac46eb8c23?dl=0) by VMM), the stations providing time series data for a given variable can be listed with the command `get_stations()`.
If you want to know the supported variables, ask for the supported variables:
```{r var_listing}
library(wateRinfo)
supported_variables("en")
```
Listing the available air pressure stations:
```{r station_listing}
get_stations("air_pressure")
```
Each of the stations in the list for a given variable, are represented by a `ts_id`. These can be used to download the data of a given period with the command `get_timeseries_tsid()`, for example Overpelt (`ts_id = 78124042`):
```{r download_pressure}
overpelt_pressure <- get_timeseries_tsid("78124042",
from = "2017-04-01",
to = "2017-04-02")
head(overpelt_pressure)
```
Making a plot of the data with [`ggplot2`](https://ggplot2.tidyverse.org/):
```{r plot_pressure, echo = TRUE, eval = FALSE}
library(ggplot2)
ggplot(overpelt_pressure, aes(x = Timestamp, y = Value)) +
geom_line() +
xlab("") + ylab("hPa") +
scale_x_datetime(date_labels = "%H:%M\n%Y-%m-%d", date_breaks = "6 hours")
```
```{r showplot1, fig.width = 7, echo = FALSE, out.width = '80%'}
knitr::include_graphics("man/figures/README-plot_pressure-1.png")
```
Another option is to check the available variables for a given station, with the function `get_variables()`. Let's consider again Overpelt (`ME11_002`) and check the first ten available variables at the Overpelt measurement station:
```{r var_overpelt, message = FALSE}
vars_overpelt <- get_variables("ME11_002")
head(vars_overpelt, 10)
```
Different pre-calculated variables are already available and a `ts_id` value is available for each of them to download the corresponding data. For example, `DagGem` (= daily mean values) of `RH` (= relative humidity), i.e. `ts_id = 78382042`:
```{r download_rh}
overpelt_rh_daily <- get_timeseries_tsid("78382042",
from = "2017-04-01",
to = "2017-04-30")
head(overpelt_rh_daily)
```
```{r plot_rh, echo = TRUE, eval = FALSE}
ggplot(overpelt_rh_daily, aes(x = Timestamp, y = Value)) +
geom_line() +
xlab("") + ylab(" RH (%)") +
scale_x_datetime(date_labels = "%b-%d\n%Y", date_breaks = "5 days")
```
```{r showplot2, fig.width = 7, echo = FALSE, out.width = '80%'}
knitr::include_graphics("man/figures/README-plot_rh-1.png")
```
Unfortunately, not all variables are documented, for which the check for the appropriate variable is not (yet) fully supported by the package.
More detailed tutorials are available in the package vignettes!
## Note on restrictions of the downloads
The amount of data downloaded from waterinfo.be is limited via a credit system. You do not need to get a token right away to download data. For limited and irregular downloads, a token will not be required.
When you require more extended data requests, please request a download token from the waterinfo.be site administrators via the e-mail address <[email protected]> with a statement of which data and how frequently you would like to download data. You will then receive a client-credit code that can be used to obtain a token that is valid for 24 hours, after which the token can be refreshed with the same client-credit code.
Get token with client-credit code: (limited client-credit code for testing purposes)
```{r token_receive}
client <- paste0("MzJkY2VlY2UtODI2Yy00Yjk4LTljMmQtYjE2OTc4ZjBjYTZhOjRhZGE4",
"NzFhLTk1MjgtNGI0ZC1iZmQ1LWI1NzBjZThmNGQyZA==")
my_token <- get_token(client = client)
print(my_token)
```
Receive information on the validity of the token:
```{r token_expired}
is.expired(my_token)
```
Check when the token expires:
```{r token_expires_when}
expires.in(my_token)
```
Use token when retrieving data:
```{r use_expires_when}
get_stations(variable_name = "verdamping_monteith", token = my_token)
```
## Other clients
Besides this wateRinfo R client to gather data from [waterinfo.be](https://www.waterinfo.be/), there is also a Python client available. The [pywaterinfo](https://fluves.github.io/pywaterinfo/) package contains similar functionalities.
The [Flanders Hydraulics Research center](https://www.waterbouwkundiglaboratorium.be/en/) also distributes clients for R, Python and Matlab upon request to download the data they share on [waterinfo.be](https://www.waterinfo.be/). For more information, contact them directly via [[email protected]](mailto:[email protected]).
## Acknowledgements
This package is just a small wrapper around waterinfo.be to facilitate researchers and other stakeholders in downloading the data from [waterinfo.be](http://www.waterinfo.be). The availability of this data is made possible by _de Vlaamse Milieumaatschappij, Waterbouwkundig Laboratorium, Maritieme Dienstverlening & Kust, Waterwegen en Zeekanaal NV en De Scheepvaart NV_.
## Meta
- We welcome [contributions](.github/CONTRIBUTING.md) including bug reports.
- License: MIT
- Get citation information for wateRinfo in R doing `citation("wateRinfo")`.
- Please note that this project is released with a [Contributor Code of Conduct](.github/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
[](https://ropensci.org)