assets_functions: Assets functions

In rstac: Client Library for SpatioTemporal Asset Catalog

Assets functions

Description

These functions provide support to work with STACItemCollection and STACItem 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,
  ...,
  download_fn = NULL,
  fn = deprecated()
)

## S3 method for class 'STACItem'
assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  create_json = FALSE,
  download_fn = NULL,
  fn = deprecated()
)

## S3 method for class 'STACItemCollection'
assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  download_fn = NULL,
  create_json = TRUE,
  items_max = Inf,
  progress = TRUE,
  fn = deprecated()
)

## Default S3 method:
assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  create_json = FALSE,
  download_fn = NULL,
  fn = deprecated()
)

assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)

## S3 method for class 'STACItem'
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)

## S3 method for class 'STACItemCollection'
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)

## Default S3 method:
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)

assets_select(items, ..., asset_names = NULL, select_fn = NULL)

## S3 method for class 'STACItem'
assets_select(items, ..., asset_names = NULL, select_fn = NULL)

## S3 method for class 'STACItemCollection'
assets_select(items, ..., asset_names = NULL, select_fn = NULL)

## Default S3 method:
assets_select(items, ..., asset_names = NULL, select_fn = NULL)

assets_rename(items, mapper = NULL, ...)

## S3 method for class 'STACItem'
assets_rename(items, mapper = NULL, ...)

## S3 method for class 'STACItemCollection'
assets_rename(items, mapper = NULL, ...)

## Default S3 method:
assets_rename(items, mapper = NULL, ...)

has_assets(items)

## S3 method for class 'STACItem'
has_assets(items)

## S3 method for class 'STACItemCollection'
has_assets(items)

## Default S3 method:
has_assets(items)

asset_key()

asset_eo_bands(field)

asset_raster_bands(field)

Arguments

items	a STACItem or STACItemCollection 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.
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.
fn	use download_fn parameter instead.
create_json	a logical indicating if a JSON file with item metadata (STACItem or STACItemCollection) 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 (STACItem or STACItemCollection). 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 (STACItem or STACItemCollection). 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.

  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.

Value

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

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

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

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

See Also

stac_search(), items(), get_request()

Examples

## Not run: 
 # 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())

## End(Not run)

## Not run: 
 # 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()

## End(Not run)

## Not run: 
 # 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")

## End(Not run)

## Not run: 
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)

## End(Not run)

rstac documentation built on Oct. 18, 2023, 1:15 a.m.