docs: fixing issue of a slow URL not passing the CRAN checks

add shapefile of the river network to the Blavet dataset

DESCRIPTION

 Package: transfR
 Type: Package
 Title: Transfer of Hydrograph from Gauged to Ungauged Catchments
-Version: 1.0.1
-Date: 2022-11-08
+Version: 1.0.2
+Date: 2022-11-20
 Authors@R: c(
   person("Alban", "de Lavenne", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-9448-3490"), email = "alban.delavenne@inrae.fr"),
   person("Christophe", "Cudennec", role = c("ths"), comment = c(ORCID = "0000-0002-1707-8926"), email = "christophe.cudennec@agrocampus-ouest.fr"),

README.md

@@ -3,7 +3,7 @@
 
 ## Overview
 
-This R package aims to propose a geomorphology-based hydrological modelling to transfer streamflow measurements from gauged catchments to ungauged catchments (where there is no stations monitoring the streamflow). It follows a runoff-runoff approach, i.e. it directly combines the observed streamflow series available at monitoring stations to estimate the streamflow series anywhere else in the surroundings rivers and without the need to implement a full rainfall-runoff model. 
+This R package aims to propose a geomorphology-based hydrological modelling to transfer streamflow measurements from gauged catchments to ungauged catchments, i.e. where there is no station monitoring the streamflow. It follows a runoff-runoff approach, i.e. it directly combines the observed streamflow series available at monitoring stations to estimate the streamflow series anywhere else in the surroundings rivers and without the need to implement a full rainfall-runoff model. The package itself and theoretical aspects of the approach are presented in detail and discussed by de Lavenne et al. (2023). 
 
 ## Short description of the modelling approach
 
@@ -30,7 +30,9 @@ To implement the method, it is advised to explore the following functions in thi
 
 ## How to get started
 
-This package comes with two datasets (Blavet and Oudon) that contains all the necessary inputs to test the package and perform discharge prediction. Users are advised to check the 'Get started with transfR' vignette (`vignette("V01_get_started", package = "transfR")`) that provides a complete implementation of the method with the Oudon dataset. In addition, each function comes with different examples.
+This package comes with two datasets (Blavet and Oudon) that contains all the necessary inputs to test the package and perform discharge prediction. Users are advised to check the 'Get started with transfR' vignette (`vignette("V01_get_started", package = "transfR")`) that provides a complete implementation of the method with the Oudon dataset. Two additional vignettes are proposed to help the preparation of input data: a spatiotemporal array of observed discharge (`vignette("V02_inputs_preparation_stars", package = "transfR")`) and a morphometric description of the catchments (`vignette("V03_inputs_preparation_whitebox", package = "transfR")`). In addition, each function comes with different examples.
+
+A detailed description of the modelling approach and the package has been published by de Lavenne et al. (2023): the theoretical aspects of each modelling step are described in more detail, arguments justifying the default values used in the functions are presented, and limitations of the approach are discussed for a consistent implementation of the approach.
 
 For the French region of Brittany, a [web service (SIMFEN)](https://geosas.fr/simfen/) using this package was developed to facilitate the implementation of the method without the need for the user to have programming skills in R or to collect the necessary input data (Dallery et al. 2020).
 
@@ -48,5 +50,7 @@ de Lavenne A, Boudhraâ H, Cudennec C (2015). “Streamflow prediction in ungaug
 
 de Lavenne A, Skøien JO, Cudennec C, Curie F, Moatar F (2016). “Transferring measured discharge time series: Large-scale comparison of Top-kriging to geomorphology-based inverse modeling.” Water Resources Research, 52(7), 5555–5576. doi: [10.1002/2016WR018716](https://doi.org/10.1002/2016WR018716).
 
-de Lavenne A, Cudennec C (2019). “Assessment of freshwater discharge into a coastal bay through multi-basin ensemble hydrological modelling.” Science of The Total Environment, 669, 812 - 820. ISSN 0048-9697, doi: [10.1016/j.scitotenv.2019.02.387](https://doi.org/10.1016/j.scitotenv.2019.02.387).
+de Lavenne A, Cudennec C (2019). “Assessment of freshwater discharge into a coastal bay through multi-basin ensemble hydrological modelling.” Science of The Total Environment, 669, 812 - 820. doi: [10.1016/j.scitotenv.2019.02.387](https://doi.org/10.1016/j.scitotenv.2019.02.387).
+
+de Lavenne A, Loree T, Squividant H, Cudennec C (2023). “The transfR toolbox for transferring observed streamflow series to ungauged basins based on their hydrogeomorphology.” Environmental Modelling & Software, 159, 105562. doi: [10.1016/j.envsoft.2022.105562](https://doi.org/10.1016/j.envsoft.2022.105562).
 

man/Blavet.Rd

@@ -23,10 +23,11 @@ Hourly discharge observations of the six catchments are provided for one hydrolo
 }
 
 
-\format{'Blavet' is a list of two objects:
+\format{'Blavet' is a list of three objects:
 \itemize{
   \item {hl}  {A list of stars objects containing the six rasters maps of hydraulic length.}
   \item {obs}  {A stars object with two dimensions (time and space, with catchment delineations as spatial support) and one attribute (discharge observations).}
+  \item {network} {A sf object of the [French TOPAGE river network](https://bdtopage.eaufrance.fr/). It can be downloaded using the Web Feature Service (WFS) "Sandre - Eau France", as shown in the example below.}
 }}
 
 
@@ -34,6 +35,29 @@ Hourly discharge observations of the six catchments are provided for one hydrolo
 http://www.hydro.eaufrance.fr
 
 https://www6.inrae.fr/ore_agrhys_eng
+
+http://bdtopage.eaufrance.fr
+}
+
+\examples{
+\dontrun{
+# Working directory
+wd <- tempdir(check = TRUE)
+# Define a bbox that will encompass the catchments of the study area
+blavet_bbox <- st_bbox(c(xmin = -3.3, xmax = -2.7, ymax = 48.11, ymin = 47.77),
+                           crs = st_crs(4326))
+# Download a French Topage river network within the bbox using the "Sandre - Eau France" WFS
+download.file(url = paste0("https://services.sandre.eaufrance.fr/geo/topage2019",
+                     "?request=GetFeature&service=WFS&version=2.0.0",
+                     "&typeName=CoursEau_FXX_Topage2019",
+                     "&outputFormat=application/json;%20subtype=geojson&BBOX=",
+                     paste0(blavet_bbox[c("ymin","xmin","ymax","xmax")],
+                            collapse=",")),
+              destfile = file.path(wd,"CoursEau_FXX_Topage2019.geojson"))
+CoursEau_Topage2019 <- st_read(dsn = file.path(wd,"CoursEau_FXX_Topage2019.geojson"),
+                               drivers = "GeoJSON", stringsAsFactors = FALSE, quiet = FALSE,
+                               query = "SELECT gid FROM CoursEau_FXX_Topage2019")
+}
 }
 
 

vignettes/V03_inputs_preparation_whitebox.Rmd

@@ -69,25 +69,7 @@ write_stars(dem_100m["warp"], file.path(wbt_wd,"dem_100m.tif"))
 
 ## 2. Retrieve a known river network and burn it into DEM (optional)
 
-The hydrological modelling distinguish the hillslope from the river network. Both will have very different transfer dynamics, and the `transfR` package aims to describe the transfer function of the river network only. Defining where this river network begins and the flow path it takes is a key, and non-trivial, issue for hydrogeomorphologists. The easiest way to draw a drainage network from a DEM is usually to define a minimum drainage area threshold at which the drainage network is assumed to start. However, defining this threshold can be difficult as it may vary spatially, especially with the geology of the region. It may therefore be better to use a known river network and force the flow paths to follow it. Here we will use the [French TOPAGE river network](https://bdtopage.eaufrance.fr/) as a reference and use a stream burning technique into the DEM following @Lindsay2016a.
-
-A vector layer of our reference river network is first downloaded from a Web Feature Service (WFS).
-
-```{r, echo=TRUE, message=FALSE, warning=FALSE, results='hide'}
-# Download a French Topage river network within the bbox using the "Sandre - Eau France" WFS
-download.file(url = paste0("https://services.sandre.eaufrance.fr/geo/topage2019",
-                     "?request=GetFeature&service=WFS&version=2.0.0",
-                     "&typeName=CoursEau_FXX_Topage2019",
-                     "&outputFormat=application/json;%20subtype=geojson&BBOX=",
-                     paste0(blavet_bbox[c("ymin","xmin","ymax","xmax")], 
-                            collapse=",")), 
-              destfile = file.path(wbt_wd,"CoursEau_FXX_Topage2019.geojson"))
-CoursEau_Topage2019 <- st_read(dsn = file.path(wbt_wd,"CoursEau_FXX_Topage2019.geojson"), 
-                               drivers = "GeoJSON", stringsAsFactors = FALSE, quiet = FALSE,
-                               query = "SELECT gid FROM CoursEau_FXX_Topage2019")
-```
-
-After a reprojection and rasterization of this river network, the function [`whitebox::wbt_burn_streams_at_roads()`](https://www.whiteboxgeo.com/manual/wbt_book/available_tools/hydrological_analysis.html#BurnStreamsAtRoads) is used to burn it into the DEM.
+The hydrological modelling distinguish the hillslope from the river network. Both will have very different transfer dynamics, and the `transfR` package aims to describe the transfer function of the river network only. Defining where this river network begins and the flow path it takes is a key, and non-trivial, issue for hydrogeomorphologists. The easiest way to draw a drainage network from a DEM is usually to define a minimum drainage area threshold at which the drainage network is assumed to start. However, defining this threshold can be difficult as it may vary spatially, especially with the geology of the region. It may therefore be better to use a known river network and force the flow paths to follow it. Here we will use the [French TOPAGE river network](https://bdtopage.eaufrance.fr/) as a reference (see the description of the `Blavet` dataset to download it from the Web Feature Service (WFS) "Sandre - Eau France"). We will implement a stream burning technique into the DEM using the function [`whitebox::wbt_burn_streams_at_roads()`](https://www.whiteboxgeo.com/manual/wbt_book/available_tools/hydrological_analysis.html#BurnStreamsAtRoads) and following @Lindsay2016a.
 
 ```{r, echo=FALSE, message=FALSE, warning=FALSE, eval=TRUE, results='hide'}
 # If WhiteboxTools executable are not present, install it in the temporary directory
@@ -103,8 +85,13 @@ if(!wbt_init()){
 ```
 
 ```{r, echo=TRUE, message=FALSE, warning=FALSE, results='hide'}
+library(transfR)
 library(whitebox)
 
+# Get the French Topage river network from the Blavet dataset
+data(Blavet)
+CoursEau_Topage2019 <- Blavet$network
+
 # Change projection and write files
 network_topage <- st_transform(CoursEau_Topage2019, EPSG)
 st_write(network_topage, file.path(wbt_wd, "network_topage.shp"), 
@@ -172,9 +159,6 @@ whitebox::wbt_remove_short_streams(d8_pntr = "d8.tif",
 Coordinates of the outlets are retrieved from [hydro.eaufrance.fr](https://www.hydro.eaufrance.fr/) and snapped to the pixel of the river network that is consistent with the previously defined flow directions.
 
 ```{r, echo=TRUE, message=FALSE, warning=FALSE, results='hide'}
-library(transfR)
-data(Blavet)
-
 # Localize the outlets of the studied catchments (with manual adjustments to help snapping)
 outlets_coordinates <- data.frame(id = names(Blavet$hl),
                              X = c(254010.612,255940-100,255903,237201,273672,265550),