Merge pull request #38 from inrae/9-add-api-qualité-des-cours-deau

9 add api qualité des cours deau

CRAN-SUBMISSION

@@ -1,3 +1,3 @@
-Version: 0.4.0
-Date: 2023-03-15 16:34:12 UTC
-SHA: 136d4c30724c088fbcfdf9cfb4cb66b3a53ef3fc
+Version: 0.4.1
+Date: 2023-05-31 11:22:27 UTC
+SHA: fde87c07014b25b08af803f40ce7e92b1854ee59

DESCRIPTION

@@ -1,13 +1,16 @@
 Type: Package
 Package: hubeau
 Title: Get Data from the French National Database on Water 'Hub'Eau'
-Version: 0.4.1
+Version: 0.4.1.9000
 Date: 2023-06-01
 Authors@R: c(
     person("David", "Dorchies", , "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0002-6595-7984")),
-    person("Pascal", "Irz", , "[email protected]", role = "ctb"),
-    person("Sébastien", "Grall", , "[email protected]", role = "ctb")
+    person("Pascal", "Irz", , "[email protected]", role = "ctb",
+           comment = c(ORCID = "00000-0002-2066-8935")),
+    person("Sébastien", "Grall", , "[email protected]", role = "ctb"),
+    person("Philippe", "Amiotte Suchet", , "[email protected]", role = "ctb",
+           comment = c(ORCID = "0000-0003-3514-1447"))
   )
 Description: Collection of functions to help retrieving data from
     'Hub'Eau' the free and public French National APIs on water
@@ -28,6 +31,7 @@ Imports:
     utils
 Suggests:
     ggplot2,
+    Hmisc,
     knitr,
     leafpop,
     lubridate,
@@ -44,4 +48,4 @@ Encoding: UTF-8
 Language: en-US
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.1

NAMESPACE

@@ -26,6 +26,10 @@ export(get_qualite_eau_potable_communes_udi)
 export(get_qualite_eau_potable_resultats_dis)
 export(get_qualite_nappes_analyses)
 export(get_qualite_nappes_stations)
+export(get_qualite_rivieres_analyse)
+export(get_qualite_rivieres_condition_environnementale)
+export(get_qualite_rivieres_operation)
+export(get_qualite_rivieres_station)
 export(get_temperature_chronique)
 export(get_temperature_stations)
 export(list_apis)

NEWS.md

@@ -1,3 +1,5 @@
+# hubeau (development version)
+
 # hubeau 0.4.1
 
 New features

R/doApiQuery.R

@@ -83,6 +83,9 @@ doApiQuery <- function(api,
       )
     }
     if (!is.null(params[[paramName]])) {
+      if (length(params[[paramName]]) > 1) {
+        params[[paramName]] <- paste(params[[paramName]], collapse = ",")
+      }
       query <- urltools::param_set(query,
                                    key = paramName,
                                    value = params[[paramName]])

R/get_qualite_rivieres.R

@@ -0,0 +1,154 @@
+#' Retrieve data from API "Qualité physico-chimique des cours d'eau"
+#'
+#' @description
+#' The "Quality of rivers" API data comes from the Naïades database.
+#' Available for the whole of France (including the French overseas departments
+#' and territories), they relate to the results of measurements of the
+#' physico-chemical quality of rivers and water bodies transmitted by the Water
+#' Agencies.
+#'
+#' Available endpoints are:
+#'
+#' - `get_qualite_rivieres_station` retrieves physico-chemical measuring stations
+#' - `get_qualite_rivieres_operation` retrieves physico-chemical operations
+#' - `get_qualite_rivieres_analyse` retrieves physico-chemical analysis
+#' - `get_qualite_rivieres_condition_environnementale` retrieves physico-chemical
+#' environmental conditions for analyses (please note that pagination is based
+#' on the number of analyses)
+#'
+#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-qualite-cours-deau}
+#'
+#' @inheritParams doApiQuery
+#' @inherit convert_list_to_tibble return return
+#'
+#' @export
+#' @rdname get_qualite_rivieres
+#'
+#' @examples
+#' \dontrun{
+#' # Tutorial provided by https://hubeau.eaufrance.fr/page/api-qualite-cours-deau-tuto
+#'
+#' # List of stations in Longuyon
+#' get_qualite_rivieres_station(libelle_commune="Longuyon")
+#' # ... with field selection
+#' get_qualite_rivieres_station(
+#'   libelle_commune = "Longuyon",
+#'   fields = c("code_station",
+#'              "libelle_station",
+#'              "localisation_precise",
+#'              "code_commune",
+#'              "libelle_commune",
+#'              "code_cours_eau",
+#'              "nom_cours_eau")
+#' )
+#'
+#' # Query results of nitrate analyses at the station since 2013
+#' get_qualite_rivieres_analyse(
+#'   code_station = "02115725",
+#'   libelle_parametre = "Nitrates",
+#'   date_debut_prelevement = "2013-01-01",
+#'   code_qualification = 1,
+#'   fields = c("code_station",
+#'              "libelle_station",
+#'              "code_parametre",
+#'              "libelle_parametre",
+#'              "date_prelevement",
+#'              "resultat",
+#'              "symbole_unite",
+#'              "code_remarque",
+#'              "mnemo_remarque",
+#'              "code_statut",
+#'              "mnemo_statut",
+#'              "code_qualification",
+#'              "libelle_qualification")
+#' )
+#'
+#' # dates sorted from most recent to oldest
+#' get_qualite_rivieres_analyse(
+#'   code_station = "02115725",
+#'   libelle_parametre = "Nitrates",
+#'   date_debut_prelevement = "2013-01-01",
+#'   code_qualification = 1,
+#'   fields = c("code_station",
+#'              "libelle_station",
+#'              "code_parametre",
+#'              "libelle_parametre",
+#'              "date_prelevement",
+#'              "resultat",
+#'              "symbole_unite",
+#'              "code_remarque",
+#'              "mnemo_remarque",
+#'              "code_statut",
+#'              "mnemo_statut",
+#'              "code_qualification",
+#'              "libelle_qualification"),
+#'  sort = "desc"
+#' )
+#'
+#' # Nitrate analysis results since 1 August 2016 for 5 stations
+#' get_qualite_rivieres_analyse(
+#'   code_station = c("02115725",
+#'                    "02115650",
+#'                    "02115685",
+#'                    "02115700",
+#'                    "02115715"),
+#'   libelle_parametre = "Nitrates",
+#'   date_debut_prelevement = "2016-08-01",
+#'   code_qualification = 1,
+#'   fields = c("code_station",
+#'              "libelle_station",
+#'              "libelle_parametre",
+#'              "date_prelevement",
+#'              "resultat",
+#'              "symbole_unite",
+#'              "code_remarque"),
+#'  sort = "desc"
+#' )
+#'
+#' # Geographical search by distance
+#' get_qualite_rivieres_station(longitude = 5.62,
+#'                              latitude = 49.44,
+#'                              distance = 8,
+#'                              fields = c("code_station", "libelle_station"))
+#'
+#' }
+get_qualite_rivieres_analyse <- function(...) {
+  l <- doApiQuery(api = "qualite_rivieres",
+                  endpoint = "analyse_pc",
+                  ...)
+  convert_list_to_tibble(l) %>% fix_encoding_libelle_station
+}
+
+#' @export
+#' @rdname get_qualite_rivieres
+get_qualite_rivieres_condition_environnementale <- function(...) {
+  l <- doApiQuery(api = "qualite_rivieres",
+                  endpoint = "condition_environnementale_pc",
+                  ...)
+  convert_list_to_tibble(l) %>% fix_encoding_libelle_station
+}
+
+#' @export
+#' @rdname get_qualite_rivieres
+get_qualite_rivieres_operation <- function(...) {
+  l <- doApiQuery(api = "qualite_rivieres",
+                  endpoint = "operation_pc",
+                  ...)
+  convert_list_to_tibble(l) %>% fix_encoding_libelle_station
+}
+
+#' @export
+#' @rdname get_qualite_rivieres
+get_qualite_rivieres_station <- function(...) {
+  l <- doApiQuery(api = "qualite_rivieres",
+                  endpoint = "station_pc",
+                  ...)
+  convert_list_to_tibble(l) %>% fix_encoding_libelle_station
+}
+
+fix_encoding_libelle_station <- function(df) {
+  if ("libelle_station" %in% names(df)) {
+    return(df %>% mutate(libelle_station = iconv(libelle_station, to = "iso8859-1", from = "utf8")))
+  }
+  return(df)
+}

R/globals.R

@@ -3,6 +3,7 @@ utils::globalVariables(
     'code_commune',
     'libelle_departement',
     'libelle_region',
+    'libelle_station',
     'longitude'
   )
 )

data-raw/config.yml

@@ -23,3 +23,5 @@ default:
       path: v1/qualite_eau_potable
     qualite_nappes:
       path: v1/qualite_nappes
+    qualite_rivieres:
+      path: v2/qualite_rivieres

data-raw/vignette_data_extraction_naiades.R

@@ -0,0 +1,22 @@
+## code to prepare `vignette_example_ecoulement_api` dataset goes here
+
+library(hubeau)
+library(dplyr)
+library(lubridate)
+
+station_21 <- get_qualite_rivieres_station(code_departement = "21")
+
+nitrates_21_raw <- get_qualite_rivieres_analyse(code_departement = "21",
+                                            date_debut_prelevement = "2000-01-01",
+                                            date_fin_prelevement = "2000-12-31",
+                                            code_parametre = "1340")
+
+nitrates_21 <- get_qualite_rivieres_analyse(
+  code_departement = "21",
+  date_debut_prelevement = "2000-01-01",
+  date_fin_prelevement = "2022-12-31",
+  code_parametre = "1340",
+  fields = c("code_station", "libelle_station", "libelle_fraction", "date_prelevement", "resultat", "symbole_unite")
+)
+
+save(station_21, nitrates_21_raw, nitrates_21, file = "inst/vignettes/data_extraction_naiades.RData")

hubeau.Rproj

@@ -19,3 +19,5 @@ BuildType: Package
 PackageUseDevtools: Yes
 PackageInstallArgs: --no-multiarch --with-keep.source
 PackageRoxygenize: rd,collate,namespace
+
+SpellingDictionary: en_US