Commit 6468d3e7 authored by Dorchies David's avatar Dorchies David
Browse files

Initial commit:

- R CMD check: OK
parents
^.*\.Rproj$
^\.Rproj\.user$
^README\.Rmd$
^LICENSE\.md$
^man-roxygen$
.Rproj.user
.Rhistory
.RData
.Ruserdata
Package: bnpe
Type: Package
Title: Retrieval Functions for the French national data bank of quantitative withdrawals (BNPE)
Version: 0.1.0.9000
Authors@R: c(
person("David", "Dorchies", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-6595-7984"), email = "david.dorchies@inrae.fr")
)
Description: Collection of functions to help retrieve the French national data bank of
quantitative withdrawals (Banque Nationale des Prélèvements quantitatifs en Eau - BNPE)
available on its website <https://bnpe.eaufrance.fr/>.
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: true
Imports:
config,
httr,
urltools
RoxygenNote: 7.1.1
Roxygen: list(markdown = TRUE)
YEAR: 2021
COPYRIGHT HOLDER: INRAE
# MIT License
Copyright (c) 2021 INRAE
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
# Generated by roxygen2: do not edit by hand
export(doQuery)
export(getComSeriesDep)
export(getCookie)
export(getTimeSeriesCom)
export(getTimeSeriesDep)
#' Internal function for doing the queries
#'
#' @param url_path the end of the URL path
#' @param params A list containing the parameters sent in the query. [character] Name of the geographical identifier ("insee_com", "code_dep"...)
#' @inheritParams getCookie
#' @param cookie a named [character] [vector] with the values of the cookies (See [getCookie])
#'
#' @return a [httr::response] object from a [httr::GET]
#' @export
#'
doQuery <- function(url_path,
params = list(code_usage = NULL,
code_type_eau = NULL,
commune_adj = NULL,
ecrasant = "false"),
cfg = config::get(file = system.file("config.yml", package = "bnpe")),
cookie = getCookie(cfg)) {
paramsDef <- list(code_usage = NULL,
code_type_eau = NULL,
commune_adj = NULL,
ecrasant = "false")
params <- utils::modifyList(paramsDef, as.list(params))
# Building URL query https://website/?param1=value1&param2=value2...
query <- file.path(cfg$url, url_path)
for (paramName in names(params)) {
if (!is.null(params[[paramName]])) {
query <- urltools::param_set(query,
key = paramName,
value = params[[paramName]])
}
}
# Request
resp <- httr::GET(query,
httr::user_agent(cfg$user_agent),
httr::set_cookies(.cookies = cookie))
if(length(grep("<title>Request Rejected</title>", httr::content(resp, "text"))) > 0) {
stop("The following URL request has been rejected: ", query)
}
return(resp)
}
#' Retrieve data by commune for one departement and one year
#'
#' @param code_dep [character] of length 2
#' @param year [numeric] Year of the data to retrieve
#' @template param_get_common
#'
#' @return [data.frame] with one row by commune and two columns: "insee_com" and "volume"
#' @export
#'
#' @examples
#' getComSeriesDep("08", 2016, code_usage = "AEP", code_type_eau = "CONT")
getComSeriesDep <- function(code_dep,
year,
code_usage = NULL,
code_type_eau = NULL,
cfg = config::get(file = system.file("config.yml", package = "bnpe")),
cookie = getCookie(cfg)) {
params <- list(
code_dep = code_dep,
annee = year,
code_usage = code_usage,
code_type_eau = code_type_eau
)
resp <- doQuery(url_path = cfg$url_com_series,
params = params,
cfg = cfg,
cookie = cookie)
l <- httr::content(resp, "parsed")
codesInsee <- sapply(l$features, function(x) { x$properties$codeInsee })
hasVolume <- sapply(l$features, function(x) { !is.null(x$properties$volume) })
volumes <- unlist(sapply(l$features, function(x) { x$properties$volume }))
data.frame(insee_com = codesInsee[hasVolume], volume = volumes)
}
#' Get cookie from the BNPE website in order to be able to do requests
#'
#' By default it is automatically called at each request but this function
#' can be used once to store a unique cookie and avoiding asking a cookie for each request (See example).
#'
#' @param cfg a [config] object Configuration of the communication. Use by default the internal package
#' configuration stored at location `system.file("config.yml", package = "bnpe")`
#'
#' @return a named [character] [vector] with the values of the cookies
#' @export
#'
#' @examples
#' cookie <- getCookie()
#' getTimeSeriesDep("08", cookie = cookie)
#' getTimeSeriesCom("08105", cookie = cookie)
getCookie <- function(cfg = config::get(file = system.file("config.yml", package = "bnpe"))) {
URL1 <- paste0(urltools::scheme(cfg$url), "://", urltools::domain(cfg$url))
userAgent <- httr::user_agent(cfg$user_agent)
resp <- httr::GET(URL1, userAgent)
ck <- httr::cookies(resp)$value
names(ck) <- httr::cookies(resp)$name
return(ck)
}
#' Get withdrawal time series for a geographical entity
#' @param insee_com a [character] of length 5 representing the INSEE code of the commune
#' @template param_get_common
#'
#' @return a [data.frame] with one year by row and the following columns:
#' - "volume" the withdrawal annual volume in cubic meters
#' - "annee" the year
#' - "peuplement" a unknown code
#' @export
#' @rdname getTimeSeries
#'
#' @examples
#' # Withdrawal time series for Ardennes department
#' getTimeSeriesDep("08")
#'
#' # Withdrawal time series for the commune of Charleville-Mézières
#' getTimeSeriesCom("08105")
#'
getTimeSeriesCom <- function(insee_com,
code_usage = NULL,
code_type_eau = NULL,
cfg = config::get(file = system.file("config.yml", package = "bnpe")),
cookie = getCookie(cfg)) {
getTimeSeries(level = "commune",
id_name = "insee_com",
id_value = insee_com,
commune_adj = "false",
cfg = cfg,
cookie = cookie)
}
#' @param insee_dep a [character] of length 2 representing the INSEE code of the commune
#' @rdname getTimeSeries
#' @export
getTimeSeriesDep <- function(insee_dep,
code_usage = NULL,
code_type_eau = NULL,
cfg = config::get(file = system.file("config.yml", package = "bnpe")),
cookie = getCookie(cfg)) {
getTimeSeries(level ="departement",
id_name = "code_dep",
id_value = insee_dep,
code_usage = code_usage,
code_type_eau = code_type_eau,
cfg = cfg,
cookie = cookie)
}
#' @param level [character] geographical level ("commune", "departement", ...)
#' @param id_name geographical identifier name ("insee_com", "code_dep", ...)
#' @param id_value geographical identifier value ("08105", "08", ...)
#' @inherit getTimeSeries
#' @noRd
getTimeSeries <-
function(level,
id_name,
id_value,
code_usage = NULL,
code_type_eau = NULL,
commune_adj = NULL,
cfg = config::get(file = system.file("config.yml", package = "bnpe")),
cookie = getCookie(cfg)) {
params <- list(
id = id_value,
code_usage = code_usage,
code_type_eau = code_type_eau,
commune_adj = commune_adj
)
names(params)[names(params) == "id"] <- id_name
resp <- doQuery(url_path = paste(cfg$url_time_series, level, sep = "_"),
params = params, cfg = cfg, cookie = cookie)
# return a data.frame
do.call(rbind, httr::content(resp, "parsed"))
}
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r opts, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# bnpe
<!-- badges: start -->
`r badger::badge_license(color = "orange")`
`r badger::badge_lifecycle("experimental", color = "blue")`
<!-- badges: end -->
'bnpe' is an R-package proposes a collection of function to help retrieve the French national data bank of quantitative withdrawals (Banque Nationale des Prélèvements quantitatifs en Eau - BNPE) available on its website: https://bnpe.eaufrance.fr
## Installation
You can install the bnpe R-package from it's development repository with:
``` r
install.packages("remotes")
remotes::install_gitlab("in-wop/bnpe", host = "gitlab.irstea.fr")
```
## Get started
### Loading library
```{r library}
library(bnpe)
```
### Time series
Functions for getting time series are:
- `getTimeSeriesDep`: for one department
- `getTimeSeriesCom`: for one commune
These functions uses the French official geographical codification (https://fr.wikipedia.org/wiki/Code_officiel_g%C3%A9ographique).
Type `?getTimeSeriesCom` for getting help.
Examples:
```{r timeseries}
# Time series for all type of withdrawal sources and destinations in the Ardennes departement
getTimeSeriesDep("08")
# Time series for drinking water withdrawals in surface water bodies in the Ardennes department
getTimeSeriesDep("08", code_usage = "AEP", code_type_eau = "CONT")
# Withdrawal time series for the commune of Charleville-Mézières
getTimeSeriesCom("08105")
```
### Communal data in one departement
For getting list of communes of departement with corresponding withdrawal volumes for one year, use the function `getComSeriesDep` as follow:
```{r}
# All source and destination withdrawals for the year 2016 in the Ardennes departement
getComSeriesDep("08", 2016, code_usage = "AEP", code_type_eau = "CONT")
```
<!-- README.md is generated from README.Rmd. Please edit that file -->
# bnpe
<!-- badges: start -->
[![License:
MIT](https://img.shields.io/badge/license-MIT-orange.svg)](https://cran.r-project.org/web/licenses/MIT)
[![](https://img.shields.io/badge/lifecycle-experimental-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->
‘bnpe’ is an R-package proposes a collection of function to help
retrieve the French national data bank of quantitative withdrawals
(Banque Nationale des Prélèvements quantitatifs en Eau - BNPE) available
on its website: <https://bnpe.eaufrance.fr>
## Installation
You can install the bnpe R-package from it’s development repository
with:
``` r
install.packages("remotes")
remotes::install_gitlab("in-wop/bnpe", host = "gitlab.irstea.fr")
```
## Get started
### Loading library
``` r
library(bnpe)
```
### Time series
Functions for getting time series are:
- `getTimeSeriesDep`: for one department
- `getTimeSeriesCom`: for one commune
These functions uses the French official geographical codification
(<https://fr.wikipedia.org/wiki/Code_officiel_g%C3%A9ographique>).
Type `?getTimeSeriesCom` for getting help.
Examples:
``` r
# Time series for all type of withdrawal sources and destinations in the Ardennes departement
getTimeSeriesDep("08")
#> volume annee peuplement
#> [1,] NULL "2008" "2"
#> [2,] NULL "2009" "2"
#> [3,] NULL "2010" "2"
#> [4,] NULL "2011" "2"
#> [5,] 750878007 "2012" "1"
#> [6,] 1070936432 "2013" "1"
#> [7,] 930232502 "2014" "1"
#> [8,] 918264038 "2015" "1"
#> [9,] 899230351 "2016" "1"
#> [10,] 790975515 "2017" "1"
#> [11,] 324131543 "2018" "1"
#> [12,] 163293169 "2019" "3"
# Time series for drinking water withdrawals in surface water bodies in the Ardennes department
getTimeSeriesDep("08", code_usage = "AEP", code_type_eau = "CONT")
#> volume annee peuplement
#> [1,] NULL "2008" "2"
#> [2,] NULL "2009" "2"
#> [3,] NULL "2010" "2"
#> [4,] NULL "2011" "2"
#> [5,] 506356 "2012" "1"
#> [6,] 479622 "2013" "1"
#> [7,] 599626 "2014" "1"
#> [8,] 631363 "2015" "1"
#> [9,] 581305 "2016" "1"
#> [10,] 1134831 "2017" "1"
#> [11,] 504790 "2018" "1"
#> [12,] 380556 "2019" "3"
# Withdrawal time series for the commune of Charleville-Mézières
getTimeSeriesCom("08105")
#> volume annee peuplement
#> [1,] NULL "2008" "2"
#> [2,] NULL "2009" "2"
#> [3,] NULL "2010" "2"
#> [4,] NULL "2011" "2"
#> [5,] 55898 "2012" "1"
#> [6,] 15359 "2013" "1"
#> [7,] 79086 "2014" "1"
#> [8,] 100624 "2015" "1"
#> [9,] 16359 "2016" "1"
#> [10,] 17162 "2017" "1"
#> [11,] 67910 "2018" "1"
#> [12,] 512130 "2019" "1"
```
### Communal data in one departement
For getting list of communes of departement with corresponding
withdrawal volumes for one year, use the function `getComSeriesDep` as
follow:
``` r
# All source and destination withdrawals for the year 2016 in the Ardennes departement
comData <- getComSeriesDep("08", 2016, code_usage = "AEP", code_type_eau = "CONT")
str(comData)
#> 'data.frame': 4 obs. of 2 variables:
#> $ insee_com: chr "08096" "08135" "08247" "08420"
#> $ volume : int 33024 13583 439424 95274
```
Version: 1.0
RestoreWorkspace: Default
SaveWorkspace: Default
AlwaysSaveHistory: Default
EnableCodeIndexing: Yes
UseSpacesForTab: Yes
NumSpacesForTab: 2
Encoding: UTF-8
RnwWeave: Sweave
LaTeX: pdfLaTeX
AutoAppendNewline: Yes
StripTrailingWhitespace: Yes
BuildType: Package
PackageUseDevtools: Yes
PackageInstallArgs: --no-multiarch --with-keep.source
PackageRoxygenize: rd,collate,namespace
default:
url: https://bnpe.eaufrance.fr/Bnpe-Diffusion/synthese
url_time_series: synthese_temporelle
url_com_series: synthese_geographique
user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:88.0) Gecko/20100101 Firefox/88.0
#' @param cookie a named [character] [vector] with the values of the cookies (See [getCookie])
#' @inheritParams getCookie
#' @param code_usage a [character()] representing the withdrawal destination which can take the following values:
#' - "ENE" for energy
#' - "CAN" for artificial canals
#' - "BAR" for turbined water (dam)
#' - "AEP" for drinking water
#' - "IND" for industry
#' - "IRR" for irrigation
#' @param code_type_eau a [character()] representing the withdrawal source which can take the following values:
#' - "CONT" for continental surface
#' - "SOUT" for subsurface
#' - "LIT" for littoral
#' @param cookie a named [character] [vector] with the values of the cookies (See [getCookie])
#' @inheritParams getCookie
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/doQuery.R
\name{doQuery}
\alias{doQuery}
\title{Internal function for doing the queries}
\usage{
doQuery(
url_path,
params = list(code_usage = NULL, code_type_eau = NULL, commune_adj = NULL, ecrasant =
"false"),
cfg = config::get(file = system.file("config.yml", package = "bnpe")),
cookie = getCookie(cfg)
)
}
\arguments{
\item{url_path}{the end of the URL path}
\item{params}{A list containing the parameters sent in the query. \link{character} Name of the geographical identifier ("insee_com", "code_dep"...)}
\item{cfg}{a \link{config} object Configuration of the communication. Use by default the internal package
configuration stored at location \code{system.file("config.yml", package = "bnpe")}}
\item{cookie}{a named \link{character} \link{vector} with the values of the cookies (See \link{getCookie})}
}
\value{
a \link[httr:response]{httr::response} object from a \link[httr:GET]{httr::GET}
}
\description{
Internal function for doing the queries
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/getComSeries.R
\name{getComSeriesDep}
\alias{getComSeriesDep}
\title{Retrieve data by commune for one departement and one year}
\usage{
getComSeriesDep(
code_dep,
year,
code_usage = NULL,
code_type_eau = NULL,
cfg = config::get(file = system.file("config.yml", package = "bnpe")),
cookie = getCookie(cfg)
)
}
\arguments{
\item{code_dep}{\link{character} of length 2}
\item{year}{\link{numeric} Year of the data to retrieve}
\item{code_usage}{a \code{\link[=character]{character()}} representing the withdrawal destination which can take the following values:
- "ENE" for energy
- "CAN" for artificial canals
- "BAR" for turbined water (dam)
- "AEP" for drinking water
- "IND" for industry
- "IRR" for irrigation}
\item{code_type_eau}{a \code{\link[=character]{character()}} representing the withdrawal source which can take the following values:
- "CONT" for continental surface
- "SOUT" for subsurface
- "LIT" for littoral}
\item{cfg}{a \link{config} object Configuration of the communication. Use by default the internal package
configuration stored at location \code{system.file("config.yml", package = "bnpe")}}
\item{cookie}{a named \link{character} \link{vector} with the values of the cookies (See \link{getCookie})}
}
\value{
\link{data.frame} with one row by commune and two columns: "insee_com" and "volume"
}
\description{
Retrieve data by commune for one departement and one year
}
\examples{
getComSeriesDep("08", 2016, code_usage = "AEP", code_type_eau = "CONT")
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/getCookie.R
\name{getCookie}
\alias{getCookie}
\title{Get cookie from the BNPE website in order to be able to do requests}
\usage{
getCookie(
cfg = config::get(file = system.file("config.yml", package = "bnpe"))
)
}
\arguments{
\item{cfg}{a \link{config} object Configuration of the communication. Use by default the internal package
configuration stored at location \code{system.file("config.yml", package = "bnpe")}}
}
\value{
a named \link{character} \link{vector} with the values of the cookies
}
\description{
By default it is automatically called at each request but this function
can be used once to store a unique cookie and avoiding asking a cookie for each request (See example).
}
\examples{
cookie <- getCookie()
getTimeSeriesDep("08", cookie = cookie)
getTimeSeriesCom("08105", cookie = cookie)
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/getTimeSeries.R
\name{getTimeSeriesCom}
\alias{getTimeSeriesCom}
\alias{getTimeSeriesDep}
\title{Get withdrawal time series for a geographical entity}
\usage{
getTimeSeriesCom(
insee_com,
code_usage = NULL,
code_type_eau = NULL,
cfg = config::get(file = system.file("config.yml", package = "bnpe")),
cookie = getCookie(cfg)
)
getTimeSeriesDep(
insee_dep,
code_usage = NULL,
code_type_eau = NULL,
cfg = config::get(file = system.file("config.yml", package = "bnpe")),
cookie = getCookie(cfg)
)
}
\arguments{
\item{insee_com}{a \link{character} of length 5 representing the INSEE code of the commune}
\item{code_usage}{a \code{\link[=character]{character()}} representing the withdrawal destination which can take the following values:
- "ENE" for energy
- "CAN" for artificial canals
- "BAR" for turbined water (dam)
- "AEP" for drinking water
- "IND" for industry
- "IRR" for irrigation}
\item{code_type_eau}{a \code{\link[=character]{character()}} representing the withdrawal source which can take the following values:
- "CONT" for continental surface
- "SOUT" for subsurface
- "LIT" for littoral}
\item{cfg}{a \link{config} object Configuration of the communication. Use by default the internal package
configuration stored at location \code{system.file("config.yml", package = "bnpe")}}
\item{cookie}{a named \link{character} \link{vector} with the values of the cookies (See \link{getCookie})}