Merge branch '1-add-data-download-at-ouvrage-scale' into 'master'

Resolve "Add data download at "ouvrage" scale"

Closes #1

See merge request in-wop/bnpe!1

.Rbuildignore

@@ -3,3 +3,4 @@
 ^README\.Rmd$
 ^LICENSE\.md$
 ^man-roxygen$
+^docs$

.gitignore

@@ -2,3 +2,4 @@
 .Rhistory
 .RData
 .Ruserdata
+docs

DESCRIPTION

 Package: bnpe
 Type: Package
 Title: Retrieval Functions for the French national data bank of quantitative withdrawals (BNPE)
-Version: 0.1.0
+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")
     )

NAMESPACE

@@ -3,5 +3,6 @@
 export(doQuery)
 export(getComSeriesDep)
 export(getCookie)
+export(getOuvrageSeries)
 export(getTimeSeriesCom)
 export(getTimeSeriesDep)

R/getOuvrageSeries.R

+#' Retrieve data by device ("ouvrage") (metadata and annual withdrawal volumes)
+#'
+#' @param code_sandre [character] Sandre identifier of the device
+#' @param cookie a named [character] [vector] with the values of the cookies (See [getCookie])
+#' @inheritParams getCookie
+#'
+#' @return [list] compiling data of the device with the following items:
+#' - `id`: BNPE identifier
+#' - `code`: code Sandre
+#' - `codeCommune`: insee code of the commune
+#' - `codePrecision`: ???
+#' - `codeStatut`: ???
+#' - `codeTypeEau`: the withdrawal source which can take the following values:
+#'        - "CONT" for continental surface
+#'        - "SOUT" for subsurface
+#'        - "LIT" for littoral
+#' - `codeUsage`: a numeric code related to water destination: energy, canals, turbined, AEP, industry or irrigation
+#' - `commentaire`: comment
+#' - `exploitationDebut`: start date of the
+#'
+#' @export
+#'
+#' @examples
+#' getOuvrageSeries("OPR0000200109")
+getOuvrageSeries <- function(code_sandre,
+                            cfg = config::get(file = system.file("config.yml",
+                                                                 package = "bnpe")),
+                            cookie = getCookie(cfg)) {
+  params <- list(
+    code = code_sandre
+  )
+
+  resp <- doQuery(url_path = cfg$url_ouvrage,
+                  params = params,
+                  cfg = cfg,
+                  cookie = cookie)
+  l <- httr::content(resp, "parsed")[[1]]
+
+  l$exploitationDebut <- as.Date(
+    format(
+      as.POSIXct(l$exploitationDebut / 1000, origin = "1970-01-01", tz = "CET")
+    )
+  )
+
+  params <- list(
+    code_ouvrage = code_sandre,
+    ecrasant = "false"
+  )
+
+  resp <- doQuery(url_path = cfg$url_ouv_series,
+                  params = params,
+                  cfg = cfg,
+                  cookie = cookie)
+  lTS <- httr::content(resp, "parsed")
+  hasVolume <- sapply(lTS, function(x) { !is.null(x$volume) })
+  annees <- sapply(lTS, "[[", "annee")
+  volumes <- unlist(sapply(lTS, "[[", "volume"))
+  peuplements <- unlist(sapply(lTS, "[[", "peuplement"))
+  l$TS <- data.frame(annee = annees[hasVolume],
+                     volume = volumes,
+                     peuplement = peuplements[hasVolume])
+  return(l)
+}

README.Rmd

@@ -72,3 +72,12 @@ For getting list of communes of departement with corresponding withdrawal volume
 getComSeriesDep("08", 2016, code_usage = "AEP", code_type_eau = "CONT")
 ```
 
+### Properties and time series from one device ("ouvrage")
+
+For getting metadata and withdrawal yearly time series from on device identified by its "code Sandre" (See https://www.sandre.eaufrance.fr/atlas/srv/fre/catalog.search#/metadata/e315633f-0930-41e8-a1c4-61fb2303039c):
+
+```{r}
+# metadata and timeseries from withdrawal "COPRIMANCHE-forage LD LE PACO (40m)" 
+ouvrage <- getOuvrageSeries("OPR0000200109")
+str(ouvrage)
+```

README.md

@@ -112,3 +112,35 @@ getComSeriesDep("08", 2016, code_usage = "AEP", code_type_eau = "CONT")
 #> 3     08247 439424
 #> 4     08420  95274
 ```
+
+### Properties and time series from one device (“ouvrage”)
+
+For getting metadata and withdrawal yearly time series from on device
+identified by its “code Sandre” (See
+<https://www.sandre.eaufrance.fr/atlas/srv/fre/catalog.search#/metadata/e315633f-0930-41e8-a1c4-61fb2303039c>):
+
+``` r
+# metadata and timeseries from withdrawal "COPRIMANCHE-forage LD LE PACO (40m)" 
+ouvrage <- getOuvrageSeries("OPR0000200109")
+str(ouvrage)
+#> List of 12
+#>  $ id               : int 200108
+#>  $ code             : chr "OPR0000200109"
+#>  $ codeCommune      : chr "50151"
+#>  $ codePrecision    : int 1
+#>  $ codeStatut       : chr "Validé"
+#>  $ codeTypeEau      : chr "SOUT"
+#>  $ codeUsage        : chr "4"
+#>  $ commentaire      : chr ""
+#>  $ exploitationDebut: Date[1:1], format: "1987-01-01"
+#>  $ geom             :List of 2
+#>   ..$ type       : chr "Point"
+#>   ..$ coordinates:List of 2
+#>   .. ..$ : num -1.58
+#>   .. ..$ : num 49.2
+#>  $ ouvNom           : chr "COPRIMANCHE-forage LD LE PACO (40m)"
+#>  $ TS               :'data.frame':   6 obs. of  3 variables:
+#>   ..$ annee     : chr [1:6] "2013" "2014" "2015" "2016" ...
+#>   ..$ volume    : int [1:6] 101970 84430 85220 87820 106219 118124
+#>   ..$ peuplement: chr [1:6] "1" "1" "1" "1" ...
+```

inst/config.yml

 default:
-  url: https://bnpe.eaufrance.fr/Bnpe-Diffusion/synthese
-  url_time_series: synthese_temporelle
-  url_com_series: synthese_geographique
+  url: https://bnpe.eaufrance.fr/Bnpe-Diffusion
+  url_time_series: synthese/synthese_temporelle
+  url_com_series: synthese/synthese_geographique
+  url_ouvrage: suggest/get_ouvrages
+  url_ouv_series: synthese/synthese_temporelle_ouvrage
   user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:88.0) Gecko/20100101 Firefox/88.0

man/getOuvrageSeries.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/getOuvrageSeries.R
+\name{getOuvrageSeries}
+\alias{getOuvrageSeries}
+\title{Retrieve data by device ("ouvrage") (metadata and annual withdrawal volumes)}
+\usage{
+getOuvrageSeries(
+  code_sandre,
+  cfg = config::get(file = system.file("config.yml", package = "bnpe")),
+  cookie = getCookie(cfg)
+)
+}
+\arguments{
+\item{code_sandre}{\link{character} Sandre identifier of the device}
+
+\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{list} compiling data of the device with the following items:
+\itemize{
+\item \code{id}: BNPE identifier
+\item \code{code}: code Sandre
+\item \code{codeCommune}: insee code of the commune
+\item \code{codePrecision}: ???
+\item \code{codeStatut}: ???
+\item \code{codeTypeEau}: the withdrawal source which can take the following values:
+- "CONT" for continental surface
+- "SOUT" for subsurface
+- "LIT" for littoral
+\item \code{codeUsage}: a numeric code related to water destination: energy, canals, turbined, AEP, industry or irrigation
+\item \code{commentaire}: comment
+\item \code{exploitationDebut}: start date of the
+}
+}
+\description{
+Retrieve data by device ("ouvrage") (metadata and annual withdrawal volumes)
+}
+\examples{
+getOuvrageSeries("OPR0000200109")
+}