rstac (version 1.0.1)

assets_functions: Assets functions

Description

These functions provide support to work with doc_items and doc_item item objects.

• assets_download(): Downloads the assets provided by the STAC API.

• assets_url(): Returns a character vector with each asset href. For the URL, you can add the GDAL library drivers for the following schemes: HTTP/HTTPS files, S3 (AWS S3) and GS (Google Cloud Storage).

• assets_select(): Selects the assets of each item by its name (asset_names parameter), by expressions (... parameter), or by a selection function (select_fn parameter). Note: This function can produce items with empty assets. In this case, users can use the items_compact() function to remove items with no assets.

• assets_rename(): Rename each asset using a named list or a function.

Usage

assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  use_gdal = FALSE,
  download_fn = NULL
)
# S3 method for doc_item
assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  use_gdal = FALSE,
  create_json = FALSE,
  download_fn = NULL
)
# S3 method for doc_items
assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  use_gdal = FALSE,
  download_fn = NULL,
  create_json = TRUE,
  items_max = Inf,
  progress = TRUE
)
# S3 method for default
assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  use_gdal = FALSE,
  create_json = FALSE,
  download_fn = NULL
)
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)
# S3 method for doc_item
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)
# S3 method for doc_items
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)
# S3 method for default
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)
assets_select(items, ..., asset_names = NULL, select_fn = NULL)
# S3 method for doc_item
assets_select(items, ..., asset_names = NULL, select_fn = NULL)
# S3 method for doc_items
assets_select(items, ..., asset_names = NULL, select_fn = NULL)
# S3 method for default
assets_select(items, ..., asset_names = NULL, select_fn = NULL)
assets_rename(items, mapper = NULL, ...)
# S3 method for doc_item
assets_rename(items, mapper = NULL, ...)
# S3 method for doc_items
assets_rename(items, mapper = NULL, ...)
# S3 method for default
assets_rename(items, mapper = NULL, ...)
has_assets(items)
# S3 method for doc_item
has_assets(items)
# S3 method for doc_items
has_assets(items)
# S3 method for default
has_assets(items)
asset_key()
asset_eo_bands(field)
asset_raster_bands(field)

Value

• assets_download(): returns the same input object item (doc_item or doc_items) where href properties point to the download assets.

• assets_url(): returns a character vector with all assets href of an item (doc_item or doc_items).

• assets_select(): returns the same input object item (doc_item or doc_items) with the selected assets.

• assets_rename(): returns the same input object item (doc_items or doc_item) with the assets renamed.

Arguments

items

a doc_item or doc_items object representing the result of /stac/search, /collections/{collectionId}/items or /collections/{collectionId}/items/{itemId} endpoints.

asset_names

a character vector with the names of the assets to be selected.

output_dir

a character directory in which the assets will be saved. Default is the working directory (getwd())

overwrite

a logical if TRUE will replace the existing file, if FALSE, a warning message is shown.

...

additional arguments. See details.

use_gdal

a logical indicating if the file should be downloaded by GDAL instead httr package.

download_fn

a function to handle download of assets for each item to be downloaded. Using this function, you can change the hrefs for each asset, as well as the way download is done.

create_json

a logical indicating if a JSON file with item metadata (doc_item or doc_items) must be created in the output directory.

items_max

a numeric corresponding to how many items will be downloaded.

progress

a logical indicating if a progress bar must be shown or not. Defaults to TRUE.

append_gdalvsi

a logical value. If true, gdal drivers are included in the URL of each asset. The following schemes are supported: HTTP/HTTPS files, S3 (AWS S3) and GS (Google Cloud Storage).

select_fn

a function to select assets an item (doc_item or doc_items). This function receives as parameter the asset element and, optionally, the asset name. Asset elements contain metadata describing spatial-temporal objects. Users can provide a function to select assets based on this metadata by returning a logical value where TRUE selects the asset, and FALSE discards it.

mapper

either a named list or a function to rename assets of an item (doc_item or doc_items). In the case of a named list, use <old name> = <new name> to rename the assets. The function can be used to rename the assets by returning a character string using the metadata contained in the asset object.

field

a character with the name of the asset field to return.

Details

Ellipsis argument (...) appears in different assets functions and has distinct purposes:

• assets_download(): ellipsis is used to pass additional httr options to GET or POST methods, such as add_headers or set_cookies.

• assets_select(): ellipsis is used to pass expressions that will be evaluated against each asset metadata. Expressions must be evaluated as a logical value where TRUE selects the asset and FALSE discards it. Multiple expressions are combine with AND operator. Expressions can use asset helper functions (i.e. asset_key(), asset_eo_bands(), and asset_raster_bands()). Multiple expressions are combined with AND operator. assets_select() uses non-standard evaluation to evaluate its expressions. That means users must escape any variable or call to be able to use them in the expressions. The escape is done by using double-curly-braces, i.e., {{variable}}.

  WARNING: Errors in the evaluation of expressions are considered as FALSE.

• assets_rename(): ellipsis is used to pass named parameters to be processed in the same way as the named list in mapper argument.

See Also

stac_search(), items(), get_request()

Examples

if (FALSE) {
 # assets_download function
 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
   stac_search(collections = "CB4-16D-2",
               datetime = "2019-06-01/2019-08-01") %>%
   stac_search() %>%
   get_request() %>%
   assets_download(asset_names = "thumbnail", output_dir = tempdir())
}

if (FALSE) {
 # assets_url function
 stac_item <- stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
  stac_search(collections = "CB4-16D-2", limit = 100,
         datetime = "2017-08-01/2018-03-01",
         bbox = c(-48.206,-14.195,-45.067,-12.272)) %>%
  get_request() %>% items_fetch(progress = FALSE)

 stac_item %>% assets_url()
}

if (FALSE) {
 # assets_select function
 stac_item <- stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
  stac_search(collections = "CB4-16D-2", limit = 100,
         datetime = "2017-08-01/2018-03-01",
         bbox = c(-48.206,-14.195,-45.067,-12.272)) %>%
  get_request() %>% items_fetch(progress = FALSE)

 stac_item %>% assets_select(asset_names = "NDVI")
}

if (FALSE) {
items <- stac("https://planetarycomputer.microsoft.com/api/stac/v1") %>%
  stac_search(collections = c("landsat-8-c2-l2", "sentinel-2-l2a"),
              bbox = c(xmin = -64.85976089, ymin = -10.49199395,
                       xmax = -64.79272527, ymax =-10.44736091),
              datetime = "2019-01-01/2019-06-28",
              limit = 50) %>%
  post_request()

# Selects assets by name
items <- assets_select(items,
                       asset_names = c("B02", "B03", "SR_B1", "SR_B2"))
# Renames the landsat assets
items <- assets_rename(items,
                       SR_B1 = "blue",
                       SR_B2 = "green",
                       B02   = "blue",
                       B03   = "green")
# Get the assets url's
assets_url(items)
}