, Elio Campitelli
[ctb] , BlueGreen Labs
[cph, fnd]| Title: | Interface to 'AppEEARS' NASA Web Services |
|---|---|
| Description: | Programmatic interface to the NASA Application for Extracting and Exploring Analysis Ready Samples services (AppEEARS; <https://appeears.earthdatacloud.nasa.gov/>). The package provides easy access to analysis ready earth observation data in R. |
| Authors: | Koen Hufkens [aut, cre]
, Elio Campitelli
[ctb] , BlueGreen Labs
[cph, fnd] |
| Maintainer: | Koen Hufkens <[email protected]> |
| License: | AGPL-3 |
| Version: | 1.1 |
| Built: | 2024-06-27 06:17:01 UTC |
| Source: | CRAN |
Builds a valid JSON formatted API request from either a tidy data frame with point based sub-tasks, or when a region of interest (roi) is specified coordinates (latitude/longitude) will be ignored and a bounding box for an sf or SpatRaster object will be used instead.
rs_build_task(df, roi, format = "geotiff")rs_build_task(df, roi, format = "geotiff")
df |
a data frame with task name (task), subtask name (subtask), latitude, longitude, start (start) and end (end) date. |
roi |
a region of interest defined by a SpatRaster or sf object, the roi will override any point based data provided as latittude-longitude coordinates in the data frame |
format |
file format of the downloaded data either geotiff (the default) or netcdf4 |
a valid AppEEARS JSON formatted task
# define a task as a tidy data frame # multiple subtasks can be provided df <- data.frame( task = "task_name", subtask = c("sub_task"), latitude = c(36.206228), longitude = c(-112.127134), start = c("2018-01-01"), end = c("2018-01-15"), product = c("MCD12Q2.006"), layer = c("Greenup") ) # build a task rs_build_task(df)# define a task as a tidy data frame # multiple subtasks can be provided df <- data.frame( task = "task_name", subtask = c("sub_task"), latitude = c(36.206228), longitude = c(-112.127134), start = c("2018-01-01"), end = c("2018-01-15"), product = c("MCD12Q2.006"), layer = c("Greenup") ) # build a task rs_build_task(df)
Returns a data frame of all data ready for download as one bundle
rs_bundle(task_id, user)rs_bundle(task_id, user)
task_id |
task id for which to return the file download bundle |
user |
username used to sign up |
returns a nested list of files to download
Koen Hufkens
## Not run: # get a list of datasets rs_bundle( user = "your_user_name", task_id = "a_task_id" ) ## End(Not run)## Not run: # get a list of datasets rs_bundle( user = "your_user_name", task_id = "a_task_id" ) ## End(Not run)
Removes a task from the queue and or buffer
rs_delete(task_id, user, purge = FALSE)rs_delete(task_id, user, purge = FALSE)
task_id |
AppEEARS task id |
user |
username used to sign up |
purge |
if TRUE, remove all previously finished tasks from the task list (default = FALSE) |
returns the content of the API call
Koen Hufkens
## Not run: # delete a single task rs_delete( user = "your_user_name", task_id = "a_task_id" ) # delete all finished or crashed # jobs (if not deleted previously) rs_delete( user = "your_user_name", purge = TRUE ) ## End(Not run)## Not run: # delete a single task rs_delete( user = "your_user_name", task_id = "a_task_id" ) # delete all finished or crashed # jobs (if not deleted previously) rs_delete( user = "your_user_name", purge = TRUE ) ## End(Not run)
Returns you token set by rs_set_key
rs_get_key(user)rs_get_key(user)
user |
username used to sign up |
the password set using rs_set_key saved
in the keychain
Koen Hufkens
## Not run: # set key rs_set_key(user = "[email protected]", password = "123") # get key rs_get_key(user = "[email protected]") ## End(Not run)## Not run: # set key rs_set_key(user = "[email protected]", password = "123") # get key rs_get_key(user = "[email protected]") ## End(Not run)
Returns a data frame of available layers for an AppEEARS product
rs_layers(product)rs_layers(product)
product |
product for which to list the layers |
returns a data frame with the AppEEARS datasets
Koen Hufkens
# is the server reachable server_check <- appeears:::rs_running( file.path(appeears:::rs_server(),"product") ) # get a list of datasets if(server_check){ layers <- rs_layers("MCD43A4.006") print(layers$Layer) }# is the server reachable server_check <- appeears:::rs_running( file.path(appeears:::rs_server(),"product") ) # get a list of datasets if(server_check){ layers <- rs_layers("MCD43A4.006") print(layers$Layer) }
Returns a data frame of all submitted tasks either in full of when providing the di
rs_list_task(task_id, user)rs_list_task(task_id, user)
task_id |
task for which to list the status (if missing all tasks are listed) |
user |
username used to sign up |
returns a data frame with the AppEEARS tasks
Koen Hufkens
## Not run: # get a list of datasets rs_list_task() ## End(Not run)## Not run: # get a list of datasets rs_list_task() ## End(Not run)
Returns a valid token for a session if successful otherwise fails with an error (stop())
rs_login(user)rs_login(user)
user |
AppEEARS username |
returns an AppEEARS session (bearer) token
Given a token it will log out / delete this token, invalidating it.
rs_logout(token)rs_logout(token)
token |
a Bearer token as returned by rs_login() |
returns if the session has closed TRUE/FALSE
Returns a data frame of available data products
rs_products()rs_products()
returns a data frame with the AppEEARS datasets
Koen Hufkens
rs_set_key
rs_transfer
rs_request
# is the server reachable server_check <- appeears:::rs_running( file.path(appeears:::rs_server(),"product") ) # get a list of datasets if(server_check){ products <- rs_products() }# is the server reachable server_check <- appeears:::rs_running( file.path(appeears:::rs_server(),"product") ) # get a list of datasets if(server_check){ products <- rs_products() }
Returns a data frame of all quality layers, or the translation of a quality layer value into plain language.
rs_quality(product, layer, value)rs_quality(product, layer, value)
product |
AppEEARS product name |
layer |
name of a product quality control layer |
value |
quality control value to translate |
returns a data frame of all AppEEARS quality layers, or those associated with a product. When a value is provided this quality flag will be translated from bitwise representation to plain language.
Koen Hufkens
## Not run: # get a list of quality layers for all data products rs_quality() ## End(Not run)## Not run: # get a list of quality layers for all data products rs_quality() ## End(Not run)
Stage a data request, and optionally download the data to disk. Alternatively
you can only stage requests, logging the request URLs to submit download
queries later on using rs_transfer.
rs_request( request, user, transfer = TRUE, path = tempdir(), time_out = 3600, job_name, verbose = TRUE ) rs_request_batch( request_list, workers = 2, user, path = tempdir(), time_out = 7200, total_timeout = length(request_list) * time_out/workers, verbose = TRUE )rs_request( request, user, transfer = TRUE, path = tempdir(), time_out = 3600, job_name, verbose = TRUE ) rs_request_batch( request_list, workers = 2, user, path = tempdir(), time_out = 7200, total_timeout = length(request_list) * time_out/workers, verbose = TRUE )
request |
nested list with query parameters following the layout as specified on the AppEEARS APIs page |
user |
user (email address or ID) provided by the AppEEARS data service,
used to retrieve the token set by |
transfer |
logical, download data TRUE or FALSE (default = TRUE) |
path |
path were to store the downloaded data |
time_out |
individual time out for each request |
job_name |
optional name to use as an RStudio job and as output variable name. It has to be a syntactically valid name. |
verbose |
show feedback on processing |
request_list |
a list of requests that will be processed in parallel. |
workers |
maximum number of simultaneous request that will be submitted to the service. Most services are limited to ~20 concurrent requests (default = 2). |
total_timeout |
overall timeout limit for all the requests in seconds. (note that the overall timeout on a session is 48h) |
the path of the downloaded (requested file) or the an R6 object with download/transfer information
Koen Hufkens
## Not run: # specifiy a task/request as a # data frame df <- data.frame( task = "grand canyon", subtask = c("test1", "test2"), latitude = c(36.206228, 36.206228), longitude = c(-112.127134, -112.127134), start = c("2018-01-01","2018-01-01"), end = c("2018-01-15","2018-01-15"), product = c("MOD11A2.061","MCD12Q2.006"), layer = c("LST_Day_1km","Dormancy") ) # build a proper JSON query task <- rs_build_task(df = df) # request the task to be executed rs_request( request = task, user = "earth_data_user", transfer = TRUE, path = "~/some_path", verbose = TRUE ) ## End(Not run)## Not run: # specifiy a task/request as a # data frame df <- data.frame( task = "grand canyon", subtask = c("test1", "test2"), latitude = c(36.206228, 36.206228), longitude = c(-112.127134, -112.127134), start = c("2018-01-01","2018-01-01"), end = c("2018-01-15","2018-01-15"), product = c("MOD11A2.061","MCD12Q2.006"), layer = c("LST_Day_1km","Dormancy") ) # build a proper JSON query task <- rs_build_task(df = df) # request the task to be executed rs_request( request = task, user = "earth_data_user", transfer = TRUE, path = "~/some_path", verbose = TRUE ) ## End(Not run)
Saves the token to your local keychain under a service called "appeears".
rs_set_key(user, password)rs_set_key(user, password)
user |
user used to sign up for the AppEEARS data service (this is not the email address, but the true user name!) |
password |
used to sign up for AppEEARS |
In systems without keychain management set the option keyring_backend to 'file' (i.e. options(keyring_backend = "file")) in order to write the keychain entry to an encrypted file. This mostly pertains to headless Linux systems. The keychain files can be found in ~/.config/r-keyring.
It invisibly returns the user.
Koen Hufkens
## Not run: # set key rs_set_key(user = "test", password = "123") # get key rs_get_key(user = "test") # leave user and key empty to open a browser window to the service's website # and type the key interactively rs_get_key() ## End(Not run)## Not run: # set key rs_set_key(user = "test", password = "123") # get key rs_get_key(user = "test") # leave user and key empty to open a browser window to the service's website # and type the key interactively rs_get_key() ## End(Not run)
Returns the contents of the requested url as a NetCDF file downloaded to disk or the current status of the requested transfer.
rs_transfer(task_id, user, path = tempdir(), verbose = TRUE)rs_transfer(task_id, user, path = tempdir(), verbose = TRUE)
task_id |
R6 |
user |
user (email address) used to sign up for the AppEEARS data service,
used to retrieve the token set by |
path |
path were to store the downloaded data |
verbose |
show feedback on data transfers |
data on disk as specified by a
rs_request
Koen Hufkens
## Not run: # set key rs_set_key(user = "test", password = "123") # request data and grab url and try a transfer r <- rs_request(request, "test", transfer = FALSE) # check transfer, will download if available rs_transfer(r$get_task_id(), user = "test") ## End(Not run)## Not run: # set key rs_set_key(user = "test", password = "123") # request data and grab url and try a transfer r <- rs_request(request, "test", transfer = FALSE) # check transfer, will download if available rs_transfer(r$get_task_id(), user = "test") ## End(Not run)