From 69530568127a9a9e820b6b80a40c180007880796 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= <maelle.salmon@yahoo.se>
Date: Mon, 1 Jul 2024 13:50:13 +0200
Subject: [PATCH] docs: more guidance for big layers

---
 DESCRIPTION               |  4 ++--
 R/layers.R                | 27 +++++++++++++++++++++++----
 man/emodnet_get_layers.Rd | 31 ++++++++++++++++++++++++++++---
 3 files changed, 53 insertions(+), 9 deletions(-)

diff --git a/DESCRIPTION b/DESCRIPTION
index 4e0ec8e..c73228c 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -52,8 +52,8 @@ Config/testthat/edition: 3
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
 SystemRequirements: C++11, GDAL (>= 2.0.1), GEOS (>= 3.4.0), PROJ (>=
     4.8.0)
-Remotes:  
+Remotes: 
     eblondel/ows4R
diff --git a/R/layers.R b/R/layers.R
index 2c89fdc..8d5448b 100644
--- a/R/layers.R
+++ b/R/layers.R
@@ -28,7 +28,9 @@
 #' @param reduce_layers whether to reduce output layers to a single `sf` object.
 #' @param ... additional vendor parameter arguments passed to
 #' [`ows4R::GetFeature()`](https://docs.geoserver.org/stable/en/user/services/wfs/reference.html#getfeature).# nolint
-#' For example, including `count=1` returns the first available feature.
+#' For example, including `count = 1` returns the first available feature.
+#' Or `outputFormat = "CSV"` (or `outputFormat = "JSON"`) might help downloading
+#' bigger datasets.
 #' @return If `reduce_layers = FALSE` (default), a list of `sf`
 #' objects, one element for each layer. Any layers for which download was
 #' unsuccessful will be NULL. If `reduce_layers = TRUE`, all layers are
@@ -37,8 +39,7 @@
 #' an `sf` out of a single layer request instead of a list of length 1.
 #' @export
 #'
-#' @examples
-#' \dontrun{
+#' @examplesIf interactive()
 #' # Layers as character vector
 #' emodnet_get_layers(
 #'   service = "biology",
@@ -58,7 +59,25 @@
 #'   layers = "mediseh_zostera_m_pnt",
 #'   count = 1
 #' )
-#' }
+#'
+#' # Usage of csv output
+#' data <- emodnet_get_layers(
+#'     service = "biology_occurrence_data",
+#'     layers = "abiotic_observations",
+#'     outputFormat = "CSV"
+#' )
+#' str(data[["abiotic_observations"]])
+#'
+#' @section Big downloads:
+#'
+#' If a layer is really big (like `"abiotic_observations"` of the
+#' `"biology_occurrence_data"` service),
+#' you might consider a combination of these ideas:
+#' - using [`outputFormat = "CSV"`](https://docs.geoserver.org/stable/en/user/services/wfs/reference.html#getfeature);
+#' - filtering using [`cql_filters`](https://emodnet.github.io/EMODnetWFS/articles/ecql_filtering.html) or
+#' [bounding boxes](https://emodnet.github.io/EMODnetWFS/articles/request-params.html#limit-spatial-extent-using-a-boundary-box)
+#' (possibly splitting the area of interests into several requests);
+#' - Using [EMODnet's download toolbox](https://emodnet.ec.europa.eu/geoviewer/).
 emodnet_get_layers <- function(wfs = NULL,
                                service = NULL,
                                service_version = NULL,
diff --git a/man/emodnet_get_layers.Rd b/man/emodnet_get_layers.Rd
index 787876a..abd4fca 100644
--- a/man/emodnet_get_layers.Rd
+++ b/man/emodnet_get_layers.Rd
@@ -52,7 +52,9 @@ Layers without corresponding filters are returned whole }
 
 \item{...}{additional vendor parameter arguments passed to
 \href{https://docs.geoserver.org/stable/en/user/services/wfs/reference.html#getfeature}{\code{ows4R::GetFeature()}}.# nolint
-For example, including \code{count=1} returns the first available feature.}
+For example, including \code{count = 1} returns the first available feature.
+Or \code{outputFormat = "CSV"} (or \code{outputFormat = "JSON"}) might help downloading
+bigger datasets.}
 }
 \value{
 If \code{reduce_layers = FALSE} (default), a list of \code{sf}
@@ -67,8 +69,23 @@ Performs an WFS getFeature request for layers from a \code{wfs} object or
 specified EMODnet Service. Filtering
 of layer features can also be handled via ECQL language filters.
 }
+\section{Big downloads}{
+
+
+If a layer is really big (like \code{"abiotic_observations"} of the
+\code{"biology_occurrence_data"} service),
+you might consider a combination of these ideas:
+\itemize{
+\item using \href{https://docs.geoserver.org/stable/en/user/services/wfs/reference.html#getfeature}{\code{outputFormat = "CSV"}}
+\item filtering using \href{https://emodnet.github.io/EMODnetWFS/articles/ecql_filtering.html}{\code{cql_filters}} or
+\href{https://emodnet.github.io/EMODnetWFS/articles/request-params.html#limit-spatial-extent-using-a-boundary-box}{bounding boxes}
+(possibly splitting the area of interests into several requests);
+\item Using \href{https://emodnet.ec.europa.eu/geoviewer/}{EMODnet's download toolbox}.
+}
+}
+
 \examples{
-\dontrun{
+\dontshow{if (interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
 # Layers as character vector
 emodnet_get_layers(
   service = "biology",
@@ -88,5 +105,13 @@ emodnet_get_layers(
   layers = "mediseh_zostera_m_pnt",
   count = 1
 )
-}
+
+# Usage of csv output
+data <- emodnet_get_layers(
+    service = "biology_occurrence_data",
+    layers = "abiotic_observations",
+    outputFormat = "CSV"
+)
+str(data[["abiotic_observations"]])
+\dontshow{\}) # examplesIf}
 }