Skip to content

Commit 34e9396

Browse files
mckeeamckeea
authored
Merge pull request #2 from eea/develop
Updated docs & communication messsages
2 parents 847b49e + 84ad2d2 commit 34e9396

File tree

6 files changed

+165
-35
lines changed

6 files changed

+165
-35
lines changed

‎DESCRIPTION‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,19 @@
11
Package: hdar
22
Type: Package
3-
Title: REST API Client for Accessing Data on WEkEO HDA V2
3+
Title: 'REST' API Client for Accessing Data on 'WEkEO HDA V2'
44
Version: 1.0.0
55
URL: https://www.wekeo.eu/
66
BugReports: https://github.com/eea/hdar/issues
77
Authors@R: person("Matteo", "Mattiuzzi", email = "matteo@mattiuzzi.com", role = c("aut", "cre"))
88
Maintainer: Matteo Mattiuzzi <matteo@mattiuzzi.com>
9-
Description: Download Copernicus data from WEkEO by means of HTTPS REST queries.
10-
License: EUPL (>= 1.2) | file LICENSE
9+
Description:
10+
The `hdar` R package offers seamless access to the 'WEkEO Harmonised Data Access (HDA)' API,
11+
enabling users to query, download, and process data efficiently from the HDA platform.
12+
With `hdar`, researchers and data scientists can integrate HDA's extensive datasets
13+
into their R workflows, enhancing their data analysis capabilities. The API documentation
14+
is available at [https://gateway.prod.wekeo2.eu/hda-broker/docs]https://gateway.prod.wekeo2.eu/hda-broker/docs, providing comprehensive
15+
information on the API's functionalities and usage.
16+
License: EUPL (>= 1.2)
1117
Encoding: UTF-8
1218
RoxygenNote: 7.3.2
1319
Imports:

‎R/client.R‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -299,8 +299,8 @@ Client <- R6::R6Class("Client",
299299

300300
search_results <- SearchResults$new(self, results, query$dataset_id)
301301

302-
print(paste("Found", search_results$total_count, "files"))
303-
print(paste("Total Size", humanize::natural_size(search_results$total_size)))
302+
message(paste("Found", search_results$total_count, "files"))
303+
message(paste("Total Size", humanize::natural_size(search_results$total_size)))
304304

305305
search_results
306306
},

‎R/search_results.R‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -38,17 +38,17 @@ SearchResults <- R6::R6Class("SearchResults",
3838

3939
#' @description
4040
#' Downloads resources based on stored results or selected indices of results.
41-
#' @param output_dir A string specifying the directory where downloaded files will be saved, defaulting to the current directory.
41+
#' @param output_dir A string specifying the directory where downloaded files will be saved.
4242
#' @param selected_indexes Optional; indices of the specific results to download.
4343
#' @param stop_at_failure Optional; controls whether the download process of multiple files should immediately stop upon encountering the first failure.
4444
#' @return Nothing returned but downloaded files are saved at the specified location.
4545
#' @export
46-
download = function(output_dir = ".", selected_indexes, stop_at_failure = TRUE) {
46+
download = function(output_dir, selected_indexes, stop_at_failure = TRUE) {
4747
if (self$total_count == 0 || !private$prompt_user_confirmation(self$total_size)) {
4848
return(NULL)
4949
}
5050

51-
print("[Download] Start")
51+
message("[Download] Start")
5252

5353
if (!dir.exists(output_dir)) {
5454
dir.create(output_dir)
@@ -66,7 +66,7 @@ SearchResults <- R6::R6Class("SearchResults",
6666

6767
i <- i + 1
6868

69-
print(paste0("[Download] Downloading file ", i, "/", length(resources_to_download)))
69+
message(paste0("[Download] Downloading file ", i, "/", length(resources_to_download)))
7070

7171
tryCatch(
7272
{
@@ -77,13 +77,13 @@ SearchResults <- R6::R6Class("SearchResults",
7777
}
7878
},
7979
error = function(err) {
80-
print(err)
81-
print("[!] An error occurred during the download.")
80+
warning(err)
81+
warning("[!] An error occurred during the download.")
8282
should_break <<- stop_at_failure
8383
}
8484
)
8585
}
86-
print("[Download] DONE")
86+
message("[Download] DONE")
8787
}
8888
),
8989
private = list(
@@ -129,7 +129,6 @@ SearchResults <- R6::R6Class("SearchResults",
129129

130130
resp <- private$client$send_request(req, TRUE)
131131
if (resp$status_code != 200) {
132-
print(resp)
133132
stop(paste("Couldn't download: ", url))
134133
}
135134

‎man/SearchResults.Rd‎

Lines changed: 2 additions & 6 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎tests/testthat/test_search.R‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -48,16 +48,17 @@ QUERY_FAILED <- jsonlite::fromJSON('{
4848
test_that("Search - Matches Found", {
4949
client <- Client$new()
5050

51-
matches <- client$search(QUERY_CORRECT, 1)
51+
matches <- client$search(QUERY_CORRECT, 10)
5252

5353
# Download files for *all* results
54-
matches$download("~/deleteme")
55-
print(list.files("~/deleteme", recursive = TRUE))
54+
temp_dir <- tempdir()
55+
matches$download(temp_dir)
56+
print(list.files(temp_dir, recursive = TRUE))
5657
# delete the folder and files
57-
unlink("~/deleteme", recursive = TRUE, force = TRUE)
58+
unlink(temp_dir, recursive = TRUE, force = TRUE)
5859
})
5960

60-
test_that("Search - Failed Query", {
61-
client <- Client$new()
62-
expect_error(matches <- client$search(QUERY_FAILED), "Search query failed")
63-
})
61+
#test_that("Search - Failed Query", {
62+
# client <- Client$new()
63+
# expect_error(matches <- client$search(QUERY_FAILED), "Search query failed")
64+
#})

‎vignettes/hdar.Rmd‎

Lines changed: 136 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ The basic usage of the datasets method is straightforward. You can retrieve a li
9595
# client <- Client$new()
9696
all_datasets <- client$datasets()
9797
all_datasets
98+
all_datasets
9899
```
99100

100101
## Filtering Datasets
@@ -105,12 +106,15 @@ You can also filter the datasets by providing a text pattern. This is useful whe
105106
# Assuming 'client' is already created and authenticated
106107
# client <- Client$new()
107108
109+
pattern <- "Seasonal Trajectories"
110+
# client <- Client$new()
111+
108112
pattern <- "Seasonal Trajectories"
109113
filtered_datasets <- client$datasets(pattern)
110114
111-
# list dataset IDs
115+
# list dataset IDs
112116
sapply(filtered_datasets,FUN = function(x){x$dataset_id})
113-
[1] "EO:EEA:DAT:CLMS_HRVPP_VPP-LAEA" "EO:EEA:DAT:CLMS_HRVPP_ST" "EO:EEA:DAT:CLMS_HRVPP_ST-LAEA"
117+
[1] "EO:EEA:DAT:CLMS_HRVPP_VPP-LAEA" "EO:EEA:DAT:CLMS_HRVPP_ST" "EO:EEA:DAT:CLMS_HRVPP_ST-LAEA"
114118
[4] "EO:EEA:DAT:CLMS_HRVPP_VPP"
115119
```
116120

@@ -125,9 +129,13 @@ To search for data in the HDA service, you need to create a query template. Manu
125129
## Basic Usage
126130

127131
The `generate_query_template` function generates a template of a query for a specified dataset. This function fetches information about existing parameters, default values, etc., from the `/queryable` endpoint of the HDA service.
132+
The `generate_query_template` function generates a template of a query for a specified dataset. This function fetches information about existing parameters, default values, etc., from the `/queryable` endpoint of the HDA service.
133+
134+
#### Example: Generating a Query
128135

129136
#### Example: Generating a Query
130137

138+
Here is an example of how to generate a query template for the dataset with the ID "EO:EEA:DAT:CLMS_HRVPP_ST":
131139
Here is an example of how to generate a query template for the dataset with the ID "EO:EEA:DAT:CLMS_HRVPP_ST":
132140

133141
```{r, eval = FALSE}
@@ -151,7 +159,7 @@ query_template
151159
180,
152160
90
153161
]
154-
}
162+
}
155163
```
156164

157165
```{r, eval = FALSE}
@@ -191,21 +199,123 @@ $end
191199
192200
$bbox
193201
[1] -180 -90 180 90
202+
# client <- Client$new()
203+
query_template <- client$generate_query_template("EO:EEA:DAT:CLMS_HRVPP_ST")
204+
query_template
205+
{
206+
"dataset_id": "EO:EEA:DAT:CLMS_HRVPP_ST",
207+
"uid": "__### Value of string type with pattern: [\\w-]+",
208+
"productType": "PPI",
209+
"platformSerialIdentifier": "S2A, S2B",
210+
"tileId": "__### Value of string type with pattern: [\\w-]+",
211+
"productVersion": "__### Value of string type with pattern: [\\w-]+",
212+
"resolution": "10",
213+
"processingDate": "__### Value of string",
214+
"start": "__### Value of string",
215+
"end": "__### Value of string",
216+
"bbox": [
217+
-180,
218+
-90,
219+
180,
220+
90
221+
]
222+
}
194223
```
195224

225+
```{r, eval = FALSE}
226+
# convert to list for easier manipulation in R
227+
library(jsonlite)
228+
query_template <- fromJSON(query_template)
229+
query_template
230+
$dataset_id
231+
[1] "EO:EEA:DAT:CLMS_HRVPP_ST"
232+
233+
$uid
234+
[1] "__### Value of string type with pattern: [\\w-]+"
235+
236+
$productType
237+
[1] "PPI"
238+
239+
$platformSerialIdentifier
240+
[1] "S2A, S2B"
241+
242+
$tileId
243+
[1] "__### Value of string type with pattern: [\\w-]+"
244+
245+
$productVersion
246+
[1] "__### Value of string type with pattern: [\\w-]+"
247+
248+
$resolution
249+
[1] "10"
250+
251+
$processingDate
252+
[1] "__### Value of string"
253+
254+
$start
255+
[1] "__### Value of string"
256+
257+
$end
258+
[1] "__### Value of string"
259+
260+
$bbox
261+
[1] -180 -90 180 90
262+
```
263+
264+
## Modify and use the generated Query Template
265+
196266
## Modify and use the generated Query Template
197267

268+
You can and should customize the generated query template to fit your specific needs. Fields starting with '\_\_###' are placeholder values indicating possible values, but if unchanged it will be stripped off before sending the query to the HDA service.
198269
You can and should customize the generated query template to fit your specific needs. Fields starting with '\_\_###' are placeholder values indicating possible values, but if unchanged it will be stripped off before sending the query to the HDA service.
199270

200271
Here is an example of how to use the query template in a search:
201272

202273
```{r, eval = FALSE}
203-
# set a new bbox
274+
# set a new bbox
204275
query_template$bbox <- c(11.1090, 46.6210, 11.2090, 46.7210)
205276
206277
# limit the time range
207278
query_template$start <- "2018-03-01T00:00:00.000Z"
208-
query_template$end <- "2018-05-31T00:00:00.000Z"
279+
query_template$end <- "2018-05-31T00:00:00.000Z"
280+
query_template
281+
$dataset_id
282+
[1] "EO:EEA:DAT:CLMS_HRVPP_ST"
283+
284+
$uid
285+
[1] "__### Value of string type with pattern: [\\w-]+"
286+
287+
$productType
288+
[1] "PPI"
289+
290+
$platformSerialIdentifier
291+
[1] "S2A, S2B"
292+
293+
$tileId
294+
[1] "__### Value of string type with pattern: [\\w-]+"
295+
296+
$productVersion
297+
[1] "__### Value of string type with pattern: [\\w-]+"
298+
299+
$resolution
300+
[1] "10"
301+
302+
$processingDate
303+
[1] "__### Value of string"
304+
305+
$start
306+
[1] "2018-03-01T00:00:00.000Z"
307+
308+
$end
309+
[1] "2018-05-31T00:00:00.000Z"
310+
311+
$bbox
312+
[1] 11.109 46.621 11.209 46.721
313+
# set a new bbox
314+
query_template$bbox <- c(11.1090, 46.6210, 11.2090, 46.7210)
315+
316+
# limit the time range
317+
query_template$start <- "2018-03-01T00:00:00.000Z"
318+
query_template$end <- "2018-05-31T00:00:00.000Z"
209319
query_template
210320
$dataset_id
211321
[1] "EO:EEA:DAT:CLMS_HRVPP_ST"
@@ -257,6 +367,16 @@ matches <- client$search(query_template)
257367
[1] "Found 9 files"
258368
[1] "Total Size 1.8 GB"
259369
370+
sapply(matches$results,FUN = function(x){x$id})
371+
[1] "ST_20180301T000000_S2_T32TPS-010m_V101_PPI" "ST_20180311T000000_S2_T32TPS-010m_V101_PPI"
372+
[3] "ST_20180321T000000_S2_T32TPS-010m_V101_PPI" "ST_20180401T000000_S2_T32TPS-010m_V101_PPI"
373+
[5] "ST_20180411T000000_S2_T32TPS-010m_V101_PPI" "ST_20180421T000000_S2_T32TPS-010m_V101_PPI"
374+
[7] "ST_20180501T000000_S2_T32TPS-010m_V101_PPI" "ST_20180511T000000_S2_T32TPS-010m_V101_PPI"
375+
[9] "ST_20180521T000000_S2_T32TPS-010m_V101_PPI"
376+
matches <- client$search(query_template)
377+
[1] "Found 9 files"
378+
[1] "Total Size 1.8 GB"
379+
260380
sapply(matches$results,FUN = function(x){x$id})
261381
[1] "ST_20180301T000000_S2_T32TPS-010m_V101_PPI" "ST_20180311T000000_S2_T32TPS-010m_V101_PPI"
262382
[3] "ST_20180321T000000_S2_T32TPS-010m_V101_PPI" "ST_20180401T000000_S2_T32TPS-010m_V101_PPI"
@@ -267,13 +387,14 @@ sapply(matches$results,FUN = function(x){x$id})
267387

268388
## Downloading the files
269389

390+
The `SearchResults` class has a public field results and a method called download that is responsible for downloading the found data. The `download()` function takes an output directory (which is created if no existing) and the optional parameter `selected_indexes` to specify which files to download.
270391
The `SearchResults` class has a public field results and a method called download that is responsible for downloading the found data. The `download()` function takes an output directory (which is created if no existing) and the optional parameter `selected_indexes` to specify which files to download.
271392

272393
```{r, eval = FALSE}
273394
# Assuming 'matches' is an instance of SearchResults obtained from the search
274-
odir <- "~/deleteme"
395+
odir <- tempdir()
275396
matches$download(odir)
276-
The total size is 1.8 GB . Do you want to proceed? (Y/N):
397+
The total size is 1.8 GB . Do you want to proceed? (Y/N):
277398
y
278399
[1] "[Download] Start"
279400
[1] "[Download] Downloading file 1/9"
@@ -296,5 +417,12 @@ list.files(odir)
296417
[9] "ST_20180521T000000_S2_T32TPS-010m_V101_PPI.tif"
297418
298419
unlink(odir,recursive = TRUE)
299-
```
420+
list.files(odir)
421+
[1] "ST_20180301T000000_S2_T32TPS-010m_V101_PPI.tif" "ST_20180311T000000_S2_T32TPS-010m_V101_PPI.tif"
422+
[3] "ST_20180321T000000_S2_T32TPS-010m_V101_PPI.tif" "ST_20180401T000000_S2_T32TPS-010m_V101_PPI.tif"
423+
[5] "ST_20180411T000000_S2_T32TPS-010m_V101_PPI.tif" "ST_20180421T000000_S2_T32TPS-010m_V101_PPI.tif"
424+
[7] "ST_20180501T000000_S2_T32TPS-010m_V101_PPI.tif" "ST_20180511T000000_S2_T32TPS-010m_V101_PPI.tif"
425+
[9] "ST_20180521T000000_S2_T32TPS-010m_V101_PPI.tif"
300426
427+
unlink(odir,recursive = TRUE)
428+
```

0 commit comments

Comments
 (0)