Initial commit:

- R CMD check: OK

.Rbuildignore

+^.*\.Rproj$
+^\.Rproj\.user$
+^README\.Rmd$
+^LICENSE\.md$
+^man-roxygen$

.gitignore

+.Rproj.user
+.Rhistory
+.RData
+.Ruserdata

DESCRIPTION

+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)

LICENSE

+YEAR: 2021
+COPYRIGHT HOLDER: INRAE

LICENSE.md

+# 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.

NAMESPACE

+# Generated by roxygen2: do not edit by hand
+
+export(doQuery)
+export(getComSeriesDep)
+export(getCookie)
+export(getTimeSeriesCom)
+export(getTimeSeriesDep)

R/doQuery.R

+#' 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)
+}

R/getComSeries.R

+#' 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)
+}

R/getCookie.R

+#' 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)
+}

R/getTimeSeries.R

+#' 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"))
+  }

README.Rmd

+---
+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

+
+<!-- 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
+```

bnpe.Rproj

+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

inst/config.yml

+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

man-roxygen/param_cfg_cookie.R

+#' @param cookie a named [character] [vector] with the values of the cookies (See [getCookie])
+#' @inheritParams getCookie

man-roxygen/param_get_common.R

+#' @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

man/doQuery.Rd

+% 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
+}

man/getComSeriesDep.Rd

+% 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")
+}

man/getCookie.Rd

+% 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)
+}

man/getTimeSeries.Rd

+% 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})}