-
+library(Hmisc)
Data extraction using the The API “qualité des -cours d’eau”
+Getting data from the API “qualité des cours +d’eau”
Philippe Amiotte Suchet, David Dorchies
@@ -102,57 +105,35 @@Philippe -
This script applies functions of the R package Hubeau “Get
-Data from the French National Database on Water Hub’Eau” to query
-the french Naiades database through the API
+ This vignette describes how to use functions of the R package
+hubeau to query the French Naiades database through the API
“qualité des cours d’eau”. The Naiades database
-gather hydrobiology, hydrogeomophomogy and physico-chemical informations
-for french river and lake water. The information is associated with a
-water quality station (location) , a date (the day of the sampling or of
+gathers hydrobiology, hydrogeomophomogy and physico-chemical information
+for French river and lake water. The information is associated with a
+water quality station (location), a date (the day of the sampling or of
the observation) and a material (water, suspended matter, sediment,
-river bed, fish, …). The API “qualité des cours d’eau” focuses
-only on water physico-chemical properties. This example shows how to extract physico-chemical (here nitrates
-concentration and total pesticides) informations from the Naiades
-database on water station belonging to an administrative entity (here
-the Cote d’Or department).
This example shows how to get physico-chemical information (here +nitrates concentration) from the Naiades database on water monitoring +sites belonging to an administrative entity (here the Cote d’Or +department).
library(hubeau)
library(dplyr)
-#>
-#> Attaching package: 'dplyr'
-#> The following objects are masked from 'package:stats':
-#>
-#> filter, lag
-#> The following objects are masked from 'package:base':
-#>
-#> intersect, setdiff, setequal, union
library(lubridate)
-#>
-#> Attaching package: 'lubridate'
-#> The following objects are masked from 'package:base':
-#>
-#> date, intersect, setdiff, union
library(ggplot2)
-library(Hmisc)
-#>
-#> Attaching package: 'Hmisc'
-#> The following objects are masked from 'package:dplyr':
-#>
-#> src, summarize
-#> The following objects are masked from 'package:base':
-#>
-#> format.pval, unitsGet started
How it works
-The Hubeau package provides functions to query the databases of the -french water information system using the Hub’eau API.
-The function names are wrtitten as follow: +
The hubeau package provides functions to query the databases +of the French water information system using the Hub’eau API.
+The functions are named as follows:
hubeau::get_[API]_[endpoint](argument) where:
[API] is the name of the API (one API = one database)
@@ -160,16 +141,16 @@
How it worksget_qualite_rivieres_station()
-uses the API “qualité des cours d’eau” to recover the water quality
-stations corresponding to requirements described in the station()
+uses the API “qualité des cours d’eau” to get the water quality stations
+corresponding to requirements described in the station()
function.
See the readme in -the R package Hubeau
+the R package hubeau.
-Listing the available API in the R package
+
Listing the available API in the R package
+Listing the APIs searchable with the hubeau R package
-
The 0.4.1 version is able to query 10 different databases which can +
The hubeau R package allows to query 11 databases which can be listed as follow:
list_apis()
@@ -187,7 +168,7 @@ Available endpoints fo
The function
list_endpoints(api = "name of the api given by <list_apis>")
-of the Hubeau R package lists the available endpoints. For the
+of the hubeau R package lists the available endpoints. For the
qualite_rivieres API it gives:
list_endpoints(api = "qualite_rivieres")
@@ -201,7 +182,7 @@ Available endpoints fo
[operation_pc] lists the sampling operation
occuring on each water station;
[condition_environnementale_pc] lists the
-environmental conditions observed during water sampming (air
+environmental conditions observed during water sampling (air
temperature, presence of mosses, alguae, etc.);
[analyse_pc] gives the results of the
physico-chemical analysis made on water samples of a selected water
@@ -216,7 +197,8 @@
List of arguments by endpoint
gives the arguments which can be used in the query. These arguments
-correspond the parameters of the Hub’eau API and are described in the Hub’eau
+correspond to the parameters of the Hub’eau API and are described in the
+Hub’eau
web page of the API.
For example, the following instruction lists the available arguments
for the endpoint “condition_environnementale_pc”:
@@ -241,10 +223,10 @@ List of arguments by endpointExtracting physico-chemical data
This example shows how to extract the nitrates concentration values
-in river water samples for station located in the Cote d’Or department
+in river water samples for stations located in the Cote d’Or department
from 2000 to 2022.
-Availability of station in the Côte d’Or department
+Availability of stations in the Côte d’Or department
The function get_qualite_rivieres_station(…) will be
used to list the available stations. Arguments for the function can be
@@ -269,7 +251,7 @@
Availability of sta
#> [46] "nom_sous_bassin" "page" "size"
#> [49] "sort" "type_entite_hydro"
The argument “code_departement” will be used with the value “21”
-which is the french administrative code for Côte d’Or.
+which is the French administrative code for Côte d’Or.
station_21 <- get_qualite_rivieres_station(code_departement = "21")
@@ -294,13 +276,13 @@ Availability of sta
#> # libelle_region <chr>, code_cours_eau <chr>, nom_cours_eau <chr>,
#> # uri_cours_eau <chr>, code_masse_deau <chr>, code_eu_masse_deau <chr>,
#> # nom_masse_deau <chr>, uri_masse_deau <chr>, code_eu_sous_bassin <chr>, …
-The result of the query gives a tibble of 466 lines and 48 columns
+
The result of the query gives a tibble of 466 rows and 48 columns
which means that the database comprises 466 water stations in the Côte
d’Or department being described by 48 parameters.
-Retrieving nitrates concentration in river water of the Côte d’or
-department
+Retrieving nitrate concentration in river water of the Côte d’or
+department
The function get_qualite_rivieres_analyse(…) is used to
get the physico-chemical analysis for selected stations. Arguments for
@@ -324,25 +306,26 @@
#> [43] "nom_bassin_dce" "nom_cours_eau" "nom_groupe_parametres"
#> [46] "nom_sous_bassin" "page" "size"
#> [49] "sort" "type_entite_hydro"
-These arguments are described in theHub’eau
+These arguments are described in the Hub’eau
API web page.
-Needed arguments in this example are:
+The arguments in this example are:
-
-
code_departement: french administrative code for
+code_departement: French administrative code for
department (“21” for Côte d’Or)
-
code_param: Code of the physico-chemical parameter; if
-more than one parameter, codes must be separated by a commas; maximum
-number of code is 200. The code of a given parameter that can be found
-in the french
-water reference system “Sandre; For nitrates the code is “1340”
+more than one parameter, codes must be separated by a commas; the
+maximum number of codes is 200. The code of a given parameter that can
+be found in the French
+water reference system “Sandre”. For nitrates the code is
+“1340”
-
date_debut_prelevement et
date_fin_prelevement: beginning and end dates of samples
(“yyyy-mm-dd” format).
-The query can be written as follow:
+The query can be written as follows:
nitrates_21_raw <- get_qualite_rivieres_analyse(code_departement = "21",
date_debut_prelevement = "2000-01-01",
@@ -372,7 +355,7 @@ #> # code_parametre <chr>, libelle_parametre <chr>, uri_parametre <chr>,
#> # resultat <dbl>, code_groupe_parametre1 <chr>, code_groupe_parametre2 <chr>,
#> # code_groupe_parametre3 <chr>, code_groupe_parametre4 <chr>, …
-The query gives a tibble of more than 13000 lines and 134 columns.
+
The query returns a tibble of more than 13000 lines and 134 columns.
Each line corresponds to a nitrate concentration value
(resultat) in mg.L-1 for a given station
(code_station) and for a given date
@@ -441,8 +424,7 @@
ObjectivesSelection of stations available for analysis
In the following example, a list of the stations of the Côte d’Or
-department is created
-(get_qualite_rivieres_station(code_departement = "21")
+department is created.
#list of station to query
station_21 <- get_qualite_rivieres_station(code_departement = "21")
@@ -450,10 +432,9 @@ Selection of stations avai
nrow(station_21)
#> [1] 468
-
We use the function
-get_qualite_rivieres_analyse(code_station = "") for
-retrieving nitrate concentration values
-(code_parametre = "1340") from 2000 to 2022.
+We use the function get_qualite_rivieres_analyse() to
+retrieve nitrate concentration values
+(code_parametre = "1340") from 2000 to 2022.
nitrates_21 <- get_qualite_rivieres_analyse(
code_departement = "21",
@@ -471,10 +452,12 @@ Selection of stations avai
)
We compute some annual statistics for each station:
-nitrates_21$date_prelevement <- as.POSIXct(nitrates_21$date_prelevement)
-nitrates_21$year <- year(nitrates_21$date_prelevement)
+nitrates_21 <- nitrates_21 %>%
+ mutate(date_prelevement = as.POSIXct(date_prelevement),
+ year = year(date_prelevement))
-station_stats <- nitrates_21 %>% group_by(code_station, libelle_station, year) %>%
+station_stats <- nitrates_21 %>%
+ group_by(code_station, libelle_station, year) %>%
summarise(nb_analyses = n(),
nitrate_mean = mean(resultat),
nitrate_p90 = quantile(resultat, probs = 0.9),
@@ -499,11 +482,11 @@ Selection of stations avai
Stations with less than 10 values per year on average and less than
10 years of data are excluded of the statistical analysis.
-valid_stations <- station_stats %>% group_by(code_station, libelle_station) %>%
+valid_stations <- station_stats %>%
+ group_by(code_station, libelle_station) %>%
summarise(analyses_per_year = mean(nb_analyses), nb_years = n()) %>%
filter(analyses_per_year >= 10, nb_years >= 10)
-#> `summarise()` has grouped output by 'code_station'. You can override using the
-#> `.groups` argument.
+
valid_stations
#> # A tibble: 13 × 4
#> # Groups: code_station [13]
@@ -522,14 +505,14 @@ Selection of stations avai
#> 11 06016500 "OUCHE A ECHENON " 11.2 22
#> 12 06017050 "SAONE A CHARREY-SUR-SAONE " 12.9 22
#> 13 06017070 "SAONE A SEURRE " 12.8 16
-The number of lines of the tibble valid_stations
+
The number of rows of the tibble valid_stations
corresponds to the number of stations with at least 10 samples per year
on average and 10 years of data.
Statistical analysis of samples
-Then, we plot the year distribution of nitrate levels with violin
+
Then, we plot the annual distribution of nitrate levels with violin
plots.
plot_nitrates <- function(code) {
@@ -588,45 +571,8 @@ Statistical analysis of samples ) # adds the mean and the standard deviation in blue
}
-lapply(valid_stations$code_station, plot_nitrates)
-#> [[1]]
-
-#>
-#> [[2]]
-
-#>
-#> [[3]]
-
-#>
-#> [[4]]
-
-#>
-#> [[5]]
-
-#>
-#> [[6]]
-
-#>
-#> [[7]]
-
-#>
-#> [[8]]
-
-#>
-#> [[9]]
-
-#>
-#> [[10]]
-
-#>
-#> [[11]]
-
-#>
-#> [[12]]
-
-#>
-#> [[13]]
-
+lapply(valid_stations$code_station, plot_nitrates)
+
Performing queries on the ‘Ecoulement’ API
-Pascal Irz, -David Dorchies
+Pascal Irz +& David Dorchies
-2024-02-21
+2024-02-22
Source:vignettes/example_ecoulement_api.Rmd
example_ecoulement_api.RmdGetting started
observations is the data itself, indicating if, at the
date of the survey, the river flows or if it is dry (which is assessed
-visually in the field).
+visually in the field)
station and observations can be joined
at least by the field code_station.
@@ -229,8 +232,8 @@ Sites
label = "libelle_station",
legend = FALSE
)
station and observations can be joined
at least by the field code_station.Surveys
diff --git a/dev/articles/example_niveaux_nappes_api.html b/dev/articles/example_niveaux_nappes_api.html
new file mode 100644
index 0000000..f0a2df9
--- /dev/null
+++ b/dev/articles/example_niveaux_nappes_api.html
@@ -0,0 +1,318 @@
+
+
+
+
+
+
+
+Performing queries on the 'niveaux_nappes' API • hubeau
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Performing queries on the ‘niveaux_nappes’
+API
+ Pascal Irz
+& David Dorchies
+
+ 2024-02-22
+
+ Source: vignettes/example_niveaux_nappes_api.Rmd
+ example_niveaux_nappes_api.Rmd
+
+
+
+
+
+This vignette shows how to use the hubeau R package
+in order to retrieve data from the French piezometric monitoring network
+(portail national d’Accès aux
+Données sur les Eaux Souterraines, ADES) from the API
+“piézométrie” (or “niveaux nappes”) of the Hub’eau portal.
+We illustrate the use of this API for the geological layer “Calcaires
+et marnes du Dogger du bassin versant du Clain libres”
+(code=GG063) with an example of map and chart useful for
+the interpretation of these data.
+
+my_water_table_code <- "GG063"
+
+Getting started
+
+First, we need to load the packages used in this vignette for
+processing data and display results on charts and map:
+
+library(hubeau)
+
+library(dplyr)
+#>
+#> Attaching package: 'dplyr'
+#> The following objects are masked from 'package:stats':
+#>
+#> filter, lag
+#> The following objects are masked from 'package:base':
+#>
+#> intersect, setdiff, setequal, union
+library(sf)
+#> Linking to GEOS 3.10.2, GDAL 3.4.1, PROJ 8.2.1; sf_use_s2() is TRUE
+library(mapview)
+library(ggplot2)
+library(purrr)
+“niveaux_nappes” is one of the 11 APIs that can be queried with the
+hubeau R package.
+The list of the API endpoints is provided by the function
+list_endpoints.
+
+list_endpoints(api = "niveaux_nappes")
+#> [1] "chroniques" "chroniques_tr" "stations"
+
+-
+
chroniques long-term time series
+-
+
chroniques_tr real time observations
+-
+
stations lists the monitoring stations
+
+The tables can be joined at least by the field
+code_bss (i.e. the site Id).
+For each endpoint, the function list_params() gives the
+different parameters that can be retrieved.
+
+list_params(api = "niveaux_nappes",
+ endpoint = "stations")
+#> [1] "bbox" "bss_id" "code_bdlisa"
+#> [4] "code_bss" "code_commune" "code_departement"
+#> [7] "codes_masse_eau_edl" "date_recherche" "fields"
+#> [10] "format" "nb_mesures_piezo_min" "page"
+#> [13] "size" "srid"
+
+
+Retrieving the data
+
+
+Sites
+
+Download the data.
+
+stations <- get_niveaux_nappes_stations(
+ codes_masse_eau_edl = my_water_table_code
+)
+
+
+Time series
+
+The aim here is to retrieve the time series of water levels measures
+in the piezometers.
+
+param_chroniques <- paste(
+ list_params(api = "niveaux_nappes",
+ endpoint = "chroniques"),
+ collapse = ","
+)
+No field allows to select a departement, so it is necessary to
+iterate through stations.
+
+water_table_level <- map_df(
+ .x = stations$code_bss,
+ .f = function(x)
+ get_niveaux_nappes_chroniques(code_bss = x,
+ date_debut_mesure = "2015-01-01")
+)
+
+
+
+Tidying the data
+
+The dataframe is processed to get a ‘year’ and a ‘month’ variables,
+then averaged by year for each site.
+
+water_table_level <- water_table_level %>%
+ mutate(date_mesure = lubridate::ymd(date_mesure),
+ year = lubridate::year(date_mesure),
+ month = lubridate::month(date_mesure))
+Selection, for each of the stations, of the years with 12 months of
+data. This is done to prevent incomplete time periods to influence the
+yearly mean water level excessively.
+
+yearly_mean_water_table_level <- water_table_level %>%
+ group_by(code_bss,
+ year) %>%
+ summarise(n_months = n_distinct(month)) %>%
+ filter(n_months == 12) # complete years
+
+yearly_mean_water_table_level <- yearly_mean_water_table_level %>%
+ select(-n_months) %>%
+ left_join(water_table_level) %>% # filtering join
+ group_by(code_bss,
+ year,
+ month) %>%
+ summarise(monthly_mean_water_table_level = mean(niveau_nappe_eau, na.rm = TRUE)) %>%
+ group_by(code_bss,
+ year) %>%
+ summarise(yearly_mean_water_table_level = mean(monthly_mean_water_table_level, na.rm = TRUE)) %>%
+ ungroup()
+
+
+Plotting
+
+
+ggplot(data = yearly_mean_water_table_level,
+ aes(x = year,
+ y = yearly_mean_water_table_level)) +
+ geom_line() +
+ facet_wrap(~code_bss,
+ scales = "free_y")
+
+
+
+Mapping
+
+The stations data.frame is transformed into a
+sf geographical object.
+
+We create a plot for each station ready to be displayed as map
+“pop-up”.
+
+p <- lapply(unique(yearly_mean_water_table_level$code_bss),
+ function(x) {
+ ggplot(data = yearly_mean_water_table_level %>% filter(code_bss == x),
+ aes(x = year,
+ y = yearly_mean_water_table_level)) +
+ geom_line() +
+ labs(title = x)
+ })
+Then they are mapped using the mapview R package. Click
+on a spot to popup the plot.
+
+mapview(
+ stations_geo,
+ map.types = c("OpenStreetMap",
+ "Esri.WorldShadedRelief",
+ "OpenTopoMap"),
+ popup = leafpop::popupGraph(p)
+)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/dev/articles/example_niveaux_nappes_api_files/HomeButton-0.0.1/LICENSE b/dev/articles/example_niveaux_nappes_api_files/HomeButton-0.0.1/LICENSE
new file mode 100644
index 0000000..a1d3414
--- /dev/null
+++ b/dev/articles/example_niveaux_nappes_api_files/HomeButton-0.0.1/LICENSE
@@ -0,0 +1,7 @@
+Copyright (C) 2014 Daniel Montague
+
+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.
diff --git a/dev/articles/example_niveaux_nappes_api_files/HomeButton-0.0.1/easy-button-src.min.js b/dev/articles/example_niveaux_nappes_api_files/HomeButton-0.0.1/easy-button-src.min.js
new file mode 100644
index 0000000..8270ab1
--- /dev/null
+++ b/dev/articles/example_niveaux_nappes_api_files/HomeButton-0.0.1/easy-button-src.min.js
@@ -0,0 +1 @@
+!function(){function a(a,c){this.title=a.title,this.stateName=a.stateName?a.stateName:"unnamed-state",this.icon=L.DomUtil.create("span",""),L.DomUtil.addClass(this.icon,"button-state state-"+this.stateName.replace(/(^\s*|\s*$)/g,"")),this.icon.innerHTML=b(a.icon),this.onClick=L.Util.bind(a.onClick?a.onClick:function(){},c)}function b(a){var b;return a.match(/[&;=<>"']/)?b=a:(a=a.replace(/(^\s*|\s*$)/g,""),b=L.DomUtil.create("span",""),0===a.indexOf("fa-")?L.DomUtil.addClass(b,"fa "+a):0===a.indexOf("glyphicon-")?L.DomUtil.addClass(b,"glyphicon "+a):L.DomUtil.addClass(b,a),b=b.outerHTML),b}L.Control.EasyBar=L.Control.extend({options:{position:"bottomright",id:null,leafletClasses:!0},initialize:function(a,b){b&&L.Util.setOptions(this,b),this._buildContainer(),this._buttons=[];for(var c=0;cON$&;6fSWRh9-@I3zNyhOC<&ctLxqMV0vb1x~h|g>2cE2B#o=wx%YN=W$Ip>E|dXx`2hhTAOu7a0=ZSw-I+y5K~U`&X
z=T#qWtY0jb7D^n)m7AB`HhZ68_v!hQ?D@ivSANMA)a%mCxJO4YC7grfEdrV$?2|Tu
zc<1fk$Rfwh&HJ4$?Y7oz6o(a<+f>G3!q6PIxI9iE+9niik-i_*_`iSpnFl_u@mKYh
z)Jp1P;9uHJ$>#2Q2kmYn3-ilMU~z0S2O*&ljKd(x>~W1R{Mt;;)gliH6S`gFk4SY}
z8=xMi1n8BjfTXGc467pRhM^g607a5@QBp-!5){?eBwJI!dGQa_=79D&>;+=_>^#xtfz
zDTGO@HFF$glR~kQiDQ_EazzruFwd*7&S;xFq48Afth194u}!jgm?GAX-nl85)$ZAW
zriK{J?2=&`6nSDKl7NIHq8TG47mOHl`_0s64TOOkqhbEF>DKt+(8qRF_o}KTRn2O>
zAy9F)K@jh$b;n$jsuydf*ICPJ;&8N!_-w(mOb6{G^ycArtDhm<;<|n
zD5Ee!BoCTn{U_M!GqH9(C6LBxCys;ZsB8>k8fSwz0rh$@8sN1SM1GVjU(dTa;Y(8g
z9fBKa9D<@9w*M3sY%B~(H=%$P!xS{FiUnwzOhTrFO}M2SYLB1b@v+h!jWg4*Op+-f
z8)>+QWeEug5nYgF<`P;aW=GsZmT6hAC-EYqh>=Zw8j#8KIsu(XfuB#19l)s1N+n>@
zgTsLGOZ{Lc8TcrUvPChU&cJ7YLOQ~V$2=D5W8*xvWIK|Jv*l!m*?N(`KklCX%mSZecl#^g
z{_U49|I@v`aGBfwwfq-%B6Uu#Y+jgqZf(AFXYa(VucN&+?z@kT!<$#Q@(-n3%MX;V
zR?hE#u=ho|{_yjIe=q(A&c2tv^~y_U_8(nX_V&5wIq87lSMTHV`Cq8%t-If@UVHyB
DN350C
literal 0
HcmV?d00001
diff --git a/dev/articles/example_niveaux_nappes_api_files/HomeButton-0.0.1/home-button.css b/dev/articles/example_niveaux_nappes_api_files/HomeButton-0.0.1/home-button.css
new file mode 100644
index 0000000..030bc3c
--- /dev/null
+++ b/dev/articles/example_niveaux_nappes_api_files/HomeButton-0.0.1/home-button.css
@@ -0,0 +1,69 @@
+.leaflet-bar button/*,
+.leaflet-bar button:hover*/ {
+ background-color: rgba(255,255,255, 0.95) /*#fff*/;
+ border: none;
+ width: 100%;
+ height: 20px;
+ line-height: 15px;
+ font-size: 85%;
+ /*display: block;*/
+ text-align: center;
+ text-decoration: none;
+ color: black;
+ cursor: pointer;
+ overflow-x: visible;
+ overflow-y: hidden;
+ opacity: 0.25;
+ filter: alpha(opacity = 25);
+ background-position: 50% 50%;
+ background-repeat: no-repeat;
+ display: inline-block;
+}
+
+.leaflet-bar button:hover {
+ background-color: #00ffff; /* #909090 */;
+ text-decoration: underline;
+ opacity: 0.9;
+ filter: alpha(opacity=90);
+}
+
+/* uncomment this to get rid of button borders, this also removes border from zoom buttons
+.leaflet-touch .leaflet-bar {
+ border: none;
+}
+
+/*.leaflet-bar button:first-of-type {
+ border-top-left-radius: 3px;
+ border-top-right-radius: 3px;
+}
+
+.leaflet-bar button:last-of-type {
+ border-bottom-left-radius: 3px;
+ border-bottom-right-radius: 3px;
+ border-bottom: none;
+}
+
+.leaflet-bar.disabled,
+.leaflet-bar button.disabled {
+ cursor: default;
+ pointer-events: none;
+ opacity: .4;
+}
+
+.easy-button-button .button-state{
+ display: block;
+ width: 100%;
+ height: 100%;
+ position: relative;
+}
+
+
+/*.leaflet-touch .leaflet-bar button {
+ width: 100%;
+ height: 20px;
+ line-height: 18px;
+ overflow-y: hidden;
+ opacity: .5;
+ filter: alpha(opacity=50);
+ white-space: nowrap;
+}*/
diff --git a/dev/articles/example_niveaux_nappes_api_files/HomeButton-0.0.1/home-button.js b/dev/articles/example_niveaux_nappes_api_files/HomeButton-0.0.1/home-button.js
new file mode 100644
index 0000000..a7a8e7f
--- /dev/null
+++ b/dev/articles/example_niveaux_nappes_api_files/HomeButton-0.0.1/home-button.js
@@ -0,0 +1,40 @@
+LeafletWidget.methods.addHomeButton = function (xmin, ymin, xmax, ymax, useext,
+ group, label, icon, position) {
+
+ if (this.easyButton) {
+ this.easyButton.removeFrom(this);
+ }
+
+ var bx = [];
+ if (useext) {
+ bx = [[ymin, xmin], [ymax, xmax]];
+ } else {
+ bx = this.layerManager._groupContainers[group].getBounds();
+ }
+
+ var easyButton = new L.easyButton({
+ position: position,
+ states: [{
+ stateName: label, // name the state
+ icon: icon, // and define its properties
+ title: label, // like its title
+ onClick: function(btn, map){
+ map.fitBounds(bx, {maxZoom: 18});
+ btn.state(label);
+ }
+ }]
+ });
+
+ easyButton.addTo(this);
+
+ this.currentEasyButton = easyButton;
+
+};
+
+
+LeafletWidget.methods.removeHomeButton = function () {
+ if (this.currentEasyButton) {
+ this.currentEasyButton.removeFrom(this);
+ this.currentEasyButton = null;
+ }
+};
diff --git a/dev/articles/example_niveaux_nappes_api_files/Proj4Leaflet-1.0.1/proj4leaflet.js b/dev/articles/example_niveaux_nappes_api_files/Proj4Leaflet-1.0.1/proj4leaflet.js
new file mode 100644
index 0000000..eaa650c
--- /dev/null
+++ b/dev/articles/example_niveaux_nappes_api_files/Proj4Leaflet-1.0.1/proj4leaflet.js
@@ -0,0 +1,272 @@
+(function (factory) {
+ var L, proj4;
+ if (typeof define === 'function' && define.amd) {
+ // AMD
+ define(['leaflet', 'proj4'], factory);
+ } else if (typeof module === 'object' && typeof module.exports === "object") {
+ // Node/CommonJS
+ L = require('leaflet');
+ proj4 = require('proj4');
+ module.exports = factory(L, proj4);
+ } else {
+ // Browser globals
+ if (typeof window.L === 'undefined' || typeof window.proj4 === 'undefined')
+ throw 'Leaflet and proj4 must be loaded first';
+ factory(window.L, window.proj4);
+ }
+}(function (L, proj4) {
+ if (proj4.__esModule && proj4.default) {
+ // If proj4 was bundled as an ES6 module, unwrap it to get
+ // to the actual main proj4 object.
+ // See discussion in https://github.com/kartena/Proj4Leaflet/pull/147
+ proj4 = proj4.default;
+ }
+
+ L.Proj = {};
+
+ L.Proj._isProj4Obj = function(a) {
+ return (typeof a.inverse !== 'undefined' &&
+ typeof a.forward !== 'undefined');
+ };
+
+ L.Proj.Projection = L.Class.extend({
+ initialize: function(code, def, bounds) {
+ var isP4 = L.Proj._isProj4Obj(code);
+ this._proj = isP4 ? code : this._projFromCodeDef(code, def);
+ this.bounds = isP4 ? def : bounds;
+ },
+
+ project: function (latlng) {
+ var point = this._proj.forward([latlng.lng, latlng.lat]);
+ return new L.Point(point[0], point[1]);
+ },
+
+ unproject: function (point, unbounded) {
+ var point2 = this._proj.inverse([point.x, point.y]);
+ return new L.LatLng(point2[1], point2[0], unbounded);
+ },
+
+ _projFromCodeDef: function(code, def) {
+ if (def) {
+ proj4.defs(code, def);
+ } else if (proj4.defs[code] === undefined) {
+ var urn = code.split(':');
+ if (urn.length > 3) {
+ code = urn[urn.length - 3] + ':' + urn[urn.length - 1];
+ }
+ if (proj4.defs[code] === undefined) {
+ throw 'No projection definition for code ' + code;
+ }
+ }
+
+ return proj4(code);
+ }
+ });
+
+ L.Proj.CRS = L.Class.extend({
+ includes: L.CRS,
+
+ options: {
+ transformation: new L.Transformation(1, 0, -1, 0)
+ },
+
+ initialize: function(a, b, c) {
+ var code,
+ proj,
+ def,
+ options;
+
+ if (L.Proj._isProj4Obj(a)) {
+ proj = a;
+ code = proj.srsCode;
+ options = b || {};
+
+ this.projection = new L.Proj.Projection(proj, options.bounds);
+ } else {
+ code = a;
+ def = b;
+ options = c || {};
+ this.projection = new L.Proj.Projection(code, def, options.bounds);
+ }
+
+ L.Util.setOptions(this, options);
+ this.code = code;
+ this.transformation = this.options.transformation;
+
+ if (this.options.origin) {
+ this.transformation =
+ new L.Transformation(1, -this.options.origin[0],
+ -1, this.options.origin[1]);
+ }
+
+ if (this.options.scales) {
+ this._scales = this.options.scales;
+ } else if (this.options.resolutions) {
+ this._scales = [];
+ for (var i = this.options.resolutions.length - 1; i >= 0; i--) {
+ if (this.options.resolutions[i]) {
+ this._scales[i] = 1 / this.options.resolutions[i];
+ }
+ }
+ }
+
+ this.infinite = !this.options.bounds;
+
+ },
+
+ scale: function(zoom) {
+ var iZoom = Math.floor(zoom),
+ baseScale,
+ nextScale,
+ scaleDiff,
+ zDiff;
+ if (zoom === iZoom) {
+ return this._scales[zoom];
+ } else {
+ // Non-integer zoom, interpolate
+ baseScale = this._scales[iZoom];
+ nextScale = this._scales[iZoom + 1];
+ scaleDiff = nextScale - baseScale;
+ zDiff = (zoom - iZoom);
+ return baseScale + scaleDiff * zDiff;
+ }
+ },
+
+ zoom: function(scale) {
+ // Find closest number in this._scales, down
+ var downScale = this._closestElement(this._scales, scale),
+ downZoom = this._scales.indexOf(downScale),
+ nextScale,
+ nextZoom,
+ scaleDiff;
+ // Check if scale is downScale => return array index
+ if (scale === downScale) {
+ return downZoom;
+ }
+ if (downScale === undefined) {
+ return -Infinity;
+ }
+ // Interpolate
+ nextZoom = downZoom + 1;
+ nextScale = this._scales[nextZoom];
+ if (nextScale === undefined) {
+ return Infinity;
+ }
+ scaleDiff = nextScale - downScale;
+ return (scale - downScale) / scaleDiff + downZoom;
+ },
+
+ distance: L.CRS.Earth.distance,
+
+ R: L.CRS.Earth.R,
+
+ /* Get the closest lowest element in an array */
+ _closestElement: function(array, element) {
+ var low;
+ for (var i = array.length; i--;) {
+ if (array[i] <= element && (low === undefined || low < array[i])) {
+ low = array[i];
+ }
+ }
+ return low;
+ }
+ });
+
+ L.Proj.GeoJSON = L.GeoJSON.extend({
+ initialize: function(geojson, options) {
+ this._callLevel = 0;
+ L.GeoJSON.prototype.initialize.call(this, geojson, options);
+ },
+
+ addData: function(geojson) {
+ var crs;
+
+ if (geojson) {
+ if (geojson.crs && geojson.crs.type === 'name') {
+ crs = new L.Proj.CRS(geojson.crs.properties.name);
+ } else if (geojson.crs && geojson.crs.type) {
+ crs = new L.Proj.CRS(geojson.crs.type + ':' + geojson.crs.properties.code);
+ }
+
+ if (crs !== undefined) {
+ this.options.coordsToLatLng = function(coords) {
+ var point = L.point(coords[0], coords[1]);
+ return crs.projection.unproject(point);
+ };
+ }
+ }
+
+ // Base class' addData might call us recursively, but
+ // CRS shouldn't be cleared in that case, since CRS applies
+ // to the whole GeoJSON, inluding sub-features.
+ this._callLevel++;
+ try {
+ L.GeoJSON.prototype.addData.call(this, geojson);
+ } finally {
+ this._callLevel--;
+ if (this._callLevel === 0) {
+ delete this.options.coordsToLatLng;
+ }
+ }
+ }
+ });
+
+ L.Proj.geoJson = function(geojson, options) {
+ return new L.Proj.GeoJSON(geojson, options);
+ };
+
+ L.Proj.ImageOverlay = L.ImageOverlay.extend({
+ initialize: function (url, bounds, options) {
+ L.ImageOverlay.prototype.initialize.call(this, url, null, options);
+ this._projectedBounds = bounds;
+ },
+
+ // Danger ahead: Overriding internal methods in Leaflet.
+ // Decided to do this rather than making a copy of L.ImageOverlay
+ // and doing very tiny modifications to it.
+ // Future will tell if this was wise or not.
+ _animateZoom: function (event) {
+ var scale = this._map.getZoomScale(event.zoom);
+ var northWest = L.point(this._projectedBounds.min.x, this._projectedBounds.max.y);
+ var offset = this._projectedToNewLayerPoint(northWest, event.zoom, event.center);
+
+ L.DomUtil.setTransform(this._image, offset, scale);
+ },
+
+ _reset: function () {
+ var zoom = this._map.getZoom();
+ var pixelOrigin = this._map.getPixelOrigin();
+ var bounds = L.bounds(
+ this._transform(this._projectedBounds.min, zoom)._subtract(pixelOrigin),
+ this._transform(this._projectedBounds.max, zoom)._subtract(pixelOrigin)
+ );
+ var size = bounds.getSize();
+
+ L.DomUtil.setPosition(this._image, bounds.min);
+ this._image.style.width = size.x + 'px';
+ this._image.style.height = size.y + 'px';
+ },
+
+ _projectedToNewLayerPoint: function (point, zoom, center) {
+ var viewHalf = this._map.getSize()._divideBy(2);
+ var newTopLeft = this._map.project(center, zoom)._subtract(viewHalf)._round();
+ var topLeft = newTopLeft.add(this._map._getMapPanePos());
+
+ return this._transform(point, zoom)._subtract(topLeft);
+ },
+
+ _transform: function (point, zoom) {
+ var crs = this._map.options.crs;
+ var transformation = crs.transformation;
+ var scale = crs.scale(zoom);
+
+ return transformation.transform(point, scale);
+ }
+ });
+
+ L.Proj.imageOverlay = function (url, bounds, options) {
+ return new L.Proj.ImageOverlay(url, bounds, options);
+ };
+
+ return L.Proj;
+}));
diff --git a/dev/articles/example_niveaux_nappes_api_files/clipboard-0.0.1/setClipboardText.js b/dev/articles/example_niveaux_nappes_api_files/clipboard-0.0.1/setClipboardText.js
new file mode 100644
index 0000000..919477d
--- /dev/null
+++ b/dev/articles/example_niveaux_nappes_api_files/clipboard-0.0.1/setClipboardText.js
@@ -0,0 +1,51 @@
+// taken from
+// https://ourcodeworld.com/articles/read/143/how-to-copy-text-to-clipboard-with-javascript-easily
+function setClipboardText(text) {
+ var id = 'mycustom-clipboard-textarea-hidden-id';
+ var existsTextarea = document.getElementById(id);
+
+ if (!existsTextarea) {
+ console.log('Creating textarea');
+ var textarea = document.createElement('textarea');
+ textarea.id = id;
+ // Place in top-left corner of screen regardless of scroll position.
+ textarea.style.position = 'fixed';
+ textarea.style.top = 0;
+ textarea.style.left = 0;
+
+ // Ensure it has a small width and height. Setting to 1px / 1em
+ // doesn't work as this gives a negative w/h on some browsers.
+ textarea.style.width = '1px';
+ textarea.style.height = '1px';
+
+ // We don't need padding, reducing the size if it does flash render.
+ textarea.style.padding = 0;
+
+ // Clean up any borders.
+ textarea.style.border = 'none';
+ textarea.style.outline = 'none';
+ textarea.style.boxShadow = 'none';
+
+ // Avoid flash of white box if rendered for any reason.
+ textarea.style.background = 'transparent';
+ document.querySelector('body').appendChild(textarea);
+ console.log('The textarea now exists :)');
+ existsTextarea = document.getElementById(id);
+ } else {
+ console.log('The textarea already exists :3');
+ }
+
+ existsTextarea.value = text;
+ existsTextarea.select();
+
+ try {
+ var status = document.execCommand('copy');
+ if (!status) {
+ console.error('Cannot copy text');
+ } else {
+ console.log('The text is now on the clipboard');
+ }
+ } catch (err) {
+ console.log('Unable to copy.');
+ }
+}
diff --git a/dev/articles/example_niveaux_nappes_api_files/figure-html/unnamed-chunk-10-1.png b/dev/articles/example_niveaux_nappes_api_files/figure-html/unnamed-chunk-10-1.png
new file mode 100644
index 0000000000000000000000000000000000000000..2d753f80632ebc2bf55530899d9086f1a99205c5
GIT binary patch
literal 195222
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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Performing queries on the ‘niveaux_nappes’ +API
+Pascal Irz +& David Dorchies
+ +2024-02-22
+ + Source:vignettes/example_niveaux_nappes_api.Rmd
+ example_niveaux_nappes_api.RmdThis vignette shows how to use the hubeau R package
+in order to retrieve data from the French piezometric monitoring network
+(portail national d’Accès aux
+Données sur les Eaux Souterraines, ADES) from the API
+“piézométrie” (or “niveaux nappes”) of the Hub’eau portal.
We illustrate the use of this API for the geological layer “Calcaires
+et marnes du Dogger du bassin versant du Clain libres”
+(code=GG063) with an example of map and chart useful for
+the interpretation of these data.
+my_water_table_code <- "GG063"
+
+
+
+
+Getting started +
+First, we need to load the packages used in this vignette for +processing data and display results on charts and map:
+
+library(hubeau)
+
+library(dplyr)
+#>
+#> Attaching package: 'dplyr'
+#> The following objects are masked from 'package:stats':
+#>
+#> filter, lag
+#> The following objects are masked from 'package:base':
+#>
+#> intersect, setdiff, setequal, union
+library(sf)
+#> Linking to GEOS 3.10.2, GDAL 3.4.1, PROJ 8.2.1; sf_use_s2() is TRUE
+library(mapview)
+library(ggplot2)
+library(purrr)“niveaux_nappes” is one of the 11 APIs that can be queried with the +hubeau R package.
+The list of the API endpoints is provided by the function
+list_endpoints.
+list_endpoints(api = "niveaux_nappes")
+#> [1] "chroniques" "chroniques_tr" "stations"-
+
-
+
chroniqueslong-term time series
+ -
+
chroniques_trreal time observations
+ -
+
stationslists the monitoring stations
+
The tables can be joined at least by the field
+code_bss (i.e. the site Id).
For each endpoint, the function list_params() gives the
+different parameters that can be retrieved.
+list_params(api = "niveaux_nappes",
+ endpoint = "stations")
+#> [1] "bbox" "bss_id" "code_bdlisa"
+#> [4] "code_bss" "code_commune" "code_departement"
+#> [7] "codes_masse_eau_edl" "date_recherche" "fields"
+#> [10] "format" "nb_mesures_piezo_min" "page"
+#> [13] "size" "srid"
+
+Retrieving the data +
+
+
+
+Sites +
+Download the data.
+
+stations <- get_niveaux_nappes_stations(
+ codes_masse_eau_edl = my_water_table_code
+)
+
+
+
+Time series +
+The aim here is to retrieve the time series of water levels measures +in the piezometers.
+
+param_chroniques <- paste(
+ list_params(api = "niveaux_nappes",
+ endpoint = "chroniques"),
+ collapse = ","
+)No field allows to select a departement, so it is necessary to +iterate through stations.
+
+water_table_level <- map_df(
+ .x = stations$code_bss,
+ .f = function(x)
+ get_niveaux_nappes_chroniques(code_bss = x,
+ date_debut_mesure = "2015-01-01")
+)
+
+
+
+Tidying the data +
+The dataframe is processed to get a ‘year’ and a ‘month’ variables, +then averaged by year for each site.
+
+water_table_level <- water_table_level %>%
+ mutate(date_mesure = lubridate::ymd(date_mesure),
+ year = lubridate::year(date_mesure),
+ month = lubridate::month(date_mesure))Selection, for each of the stations, of the years with 12 months of +data. This is done to prevent incomplete time periods to influence the +yearly mean water level excessively.
+
+yearly_mean_water_table_level <- water_table_level %>%
+ group_by(code_bss,
+ year) %>%
+ summarise(n_months = n_distinct(month)) %>%
+ filter(n_months == 12) # complete years
+
+yearly_mean_water_table_level <- yearly_mean_water_table_level %>%
+ select(-n_months) %>%
+ left_join(water_table_level) %>% # filtering join
+ group_by(code_bss,
+ year,
+ month) %>%
+ summarise(monthly_mean_water_table_level = mean(niveau_nappe_eau, na.rm = TRUE)) %>%
+ group_by(code_bss,
+ year) %>%
+ summarise(yearly_mean_water_table_level = mean(monthly_mean_water_table_level, na.rm = TRUE)) %>%
+ ungroup()
+
+
+Plotting +
+
+ggplot(data = yearly_mean_water_table_level,
+ aes(x = year,
+ y = yearly_mean_water_table_level)) +
+ geom_line() +
+ facet_wrap(~code_bss,
+ scales = "free_y")
+
+
+
+
+
+ Mapping +
+The stations data.frame is transformed into a
+sf geographical object.
We create a plot for each station ready to be displayed as map +“pop-up”.
+
+p <- lapply(unique(yearly_mean_water_table_level$code_bss),
+ function(x) {
+ ggplot(data = yearly_mean_water_table_level %>% filter(code_bss == x),
+ aes(x = year,
+ y = yearly_mean_water_table_level)) +
+ geom_line() +
+ labs(title = x)
+ })Then they are mapped using the mapview R package. Click
+on a spot to popup the plot.
+mapview(
+ stations_geo,
+ map.types = c("OpenStreetMap",
+ "Esri.WorldShadedRelief",
+ "OpenTopoMap"),
+ popup = leafpop::popupGraph(p)
+)